Start Apple Pay session

Browse API reference

POST/processing-terminals/{processingTerminalId}/apple-pay-sessionsapplePaySessions

Use this method to start an Apple Pay session for your merchant.

In the response, we return the startSessionObject that you send to Apple when you retrieve the cardholder's encrypted payment details.

Note: For more information about how to integrate with Apple Pay, go to Apple Pay.

Parameters

Name	In	Type	Description
`processingTerminalId`Required	path	`string`	Unique identifier that we assigned to the terminal.

Request body

application/json · required

Field Edit request inputs →

appleDomainIdstringrequired
Unique appleDomainId of the merchant's domain that we assigned when you added their domain to our Self-Care Portal.
appleValidationUrlstringrequired
Validation URL from the Apple Pay JS API.

Responses

Successful request. We started the Apple Pay session.

200 OK · application/json

{
  "startSessionResponse": "{\n  \"epochTimestamp\": 1736264582447,\n  \"expiresAt\": 1736268182447,\n  \"merchantSessionIdentifier\": \"SSHE464E2B91B714F18BFD19D46D0F582BF_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24\",\n  \"nonce\": \"e5775127\",\n  \"merchantIdentifier\": \"BFB110EE83BE2AF4AA7468926C926CCFC57F4A541CCE6E7F3BEFD05002ECE503\",\n  \"domainName\": \"store.com\",\n  \"displayName\": \"Store One\",\n  \"signature\": \"a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000\",\n  \"operationalAnalyticsIdentifier\": \"Store One:BFB110EE83BE2AF4AA7468926C926CCFC57F4A541CCE6E7F3BEFD05002ECE503\",\n  \"retries\": 0,\n  \"pspId\": \"17D4AAA8D9357D26D771ABA0DAA0B9D3BB462AD1585492E1FE688AF8BB9558E5\"\n}\n"
}

Response schema · 1 field

startSessionResponsestringrequired
Object that Apple returns when they start the merchant's Apple Pay session. Send the content in this object to Apple to retrieve the cardholder's encrypted payment details.

Validation error

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

accept-apple-pay