Article

Requesting an Apple Pay Payment Session

Request a valid session from the Apple Pay server.

Overview

You need a new Apple Pay 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

Returns an opaque Apple Pay session object.

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

  • For Apple Pay on the web, use the fully qualified validation URL received in onvalidatemerchant. This URL is dynamic and you should support 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.

HTTPS Method: post

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.

initiative

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

initiativeContext

A value you provide based on the initiative.

The value you supply for the displayName parameter is displayed in the Touch Bar on supported models of MacBook Pro.

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 Processing Payment Requests for more information.

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.