Article

Requesting an Apple Pay Payment Session

Request a valid session from the Apple Pay server.

Overview

You need a new Apple Pay payment session for each transaction. Your server posts a request using two-way TLS by calling the Apple Pay server’s Payment Session endpoint. Use the Merchant Identity Certificate associated with your merchant ID in the call.

Payment Session Endpoint URL

Endpoint: POST https://<validation URL>/paymentSession

Returns an opaque Apple Pay session object.

  • For Apple Pay on the web, use the fully qualified validation URL received in onvalidatemerchant. This URL is dynamic and you should whitelist all of the domains listed in Setting Up Your Server.

  • For Apple Pay in Business Chat, use the endpoint https://apple-pay-gateway.apple.com/paymentservices/paymentSession.

Request Parameters

merchantIdentifier

Your merchant ID.

displayName

A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display. Do not localize the name. Use only characters from the supported character sets in the fonts listed in Table 1.

initiative

A predefined value that identifies the e-commerce application making the request.

initiativeContext

A value you provide based on the initiative.

The values for initiative and initiativeContext depend on the kind of application you're building:

  • For Apple Pay on the web, use "web" for the initiative parameter. For the initiativeContext parameter, provide your fully qualified domain name associated with your Apple Pay Merchant Identity Certificate.

  • For Business Chat, use "messaging" for the initiative parameter. For the initiativeContext parameter, pass your payment gateway URL. See Sending an Apple Pay Payment Request for more information.

On supported models of MacBook Pro, the Touch Bar displays the value you supply for the displayName parameter. The following table lists the valid fonts.

Table 1

Language

Font

Arabic

MyriadArabic-Regular.otf

Bengali

KohinoorBangla-Regular.otf

Chinese

PingFangTC-Regular.otf

English

SF-Compact-Text-Regular.otf

Hebrew

Myriad-Hebrew.ttc

Hindi

KohinoorDevanagari-Regular.otf

Japanese

PingFangTC-Regular.otf

Korean

NanumGothic.ttf

Telegu

KohinoorTelugu-Regular.otf

Thai

Ayuthaya.ttf

Response

In response to the POST request, your server receives an opaque Apple Pay session object. The session expires after five minutes.

  • For Apple Pay on the web, you pass the session object to the completion method, completeMerchantValidation.

  • For Apple Pay in Business Chat, you pass the session object to your Customer Service Platform (CSP), which handles communicating with Business Chat on your behalf.

Example

A session request with a JSON payload for Apple Pay on the web.

const options= {
    url: endpointURL,
    cert: merchIdentityCert,
    key: merchIdentityCert,
    method: 'post',
    body:{
            merchantIdentifier: "merchant.com.example.mystore",
            displayName: "MyStore",
            initiative: "web",
            initiativeContext: "mystore.example.com"
          },
     json: true,
}

The displayName you provide in the payload appears in the Touch Bar like this:

A screenshot of the Touch Bar requesting Touch ID for an Apple Pay transaction.

See Also

Apple Pay Session

Creating an Apple Pay Session

Provide a payment request and create the session.

Providing Merchant Validation

Validate your merchant identity and receive a session object for each payment request.

ApplePaySession

A session object for managing the payment process on the web.