Enable Apple Pay on the Web for PSPs

Salesforce B2C Commerce provides the API interface and works directly with key PSPs to enable Apple Pay. Each PSP determines whether to support this capability.

Important: Apple Pay PSP API does not support split instrument payments or gift certificates. Payment Authorization is always for the full amount of an order.

The PSP sets up an endpoint that can accept the request from B2C Commerce. The B2C Commerce server makes a call to the PSP to enable them to authorize the payment. The PSP puts the request into a format that they can accept, if necessary. The PSP returns the response in the correct format to the B2C Commerce server.

Alternatively, PSPs can update their LINK cartridge.

Each PSP determines which integration method (standard API or updated cartridge) they wish to support.

To handle Apple Pay payments, the merchant sends a request to the PSP. The PSP handles the request, and returns a response and an HTTPS status.

Apple Pay Request

In the request for authorization from the PSP, the following is passed. For Apple Pay, the merchant should request only the fields that are required to process the transaction.

Note: The addition of properties to the available properties doesn't require you to update your implementation of Apple Pay on the Web; however, if there are changes to any existing properties you must update your Apple Pay on the Web implementation.
Property Type Required Notes Description B2C Commerce Mapping Apple Mapping
_v string enumeration required Only "1" currently supported B2C Commerce request document version number    
merchant_account_id string required 256 characters maximum PSP merchant account identifier configuration data  
session_id string required 256 characters maximum B2C Commerce unique shopper session ID session.sessionID  
order_no string required 256 characters maximum B2C Commerce storefront order number order.orderNo  
payment.payment_id hex encoded string required 28 characters maximum B2C Commerce unique payment ID paymentTransaction.UUID  
payment.type string enumeration required   The type of payment to authorize "ApplePay" for Apple Pay transactions  
payment.amount number required between 1 and 999999999999 Amount to auth in cents or equivalent minor unit paymentTransaction.amount.value * 10 ^ currency.defaultFractionDigits PaymentRequest.total.amount
payment.currency string required 3 characters   paymentTransaction.amount.currency PaymentRequest.currencyCode
payment.token base64 encoded string required   Apple Pay payment token not stored on B2C Commerce ApplePayPaymentAuthorizedEvent.payment.token
client.ip_address string   40 characters maximum IP address of shopper browser request.httpRemoteAddress  
client.user_agent string   2000 characters maximum User agent of shopper browser request.httpUserAgent  
client.accept_header string   2000 characters maximum Accept header of shopper browser request.httpHeaders.accept  
customer_info.customer_no string   256 characters maximum B2C Commerce shopper customer number order.customerNo  
customer_info.email string   256 characters maximum B2C Commerce shopper email address order.customerEmail ApplePayPaymentAuthorizedEvent.payment.billingContact.emailAddress
customer_info.customer_name string   256 characters maximum B2C Commerce shopper name order.customerName ApplePayPaymentAuthorizedEvent.payment..billingContact.givenName + " " + ApplePayPaymentAuthorizedEvent.payment.billingContact.familyName
shipping_address.first_name string   256 characters maximum Apple Pay provided shipping contact name order.defaultShipment.shippingAddress.firstName ApplePayPaymentAuthorizedEvent.payment.shippingContact.givenName
shipping_address.last_name string   256 characters maximum Apple Pay provided shipping contact name order.defaultShipment.shippingAddress.lastName ApplePayPaymentAuthorizedEvent.payment.shippingContact.familyName
shipping_address.address1 string   256 characters maximum Apple Pay provided shipping contact street address order.defaultShipment.shippingAddress.address1 ApplePayPaymentAuthorizedEvent.payment.shippingContact.addressLines[0]
shipping_address.city string   256 characters maximum Apple Pay provided shipping contact city order.defaultShipment.shippingAddress.city ApplePayPaymentAuthorizedEvent.payment.shippingContact.locality
shipping_address.state_code string   256 characters maximum Apple Pay provided shipping contact state order.defaultShipment.shippingAddress.stateCode ApplePayPaymentAuthorizedEvent.payment.shippingContact.administrativeArea
shipping_address.postal_code string   256 characters maximum Apple Pay provided shipping contact postal code order.defaultShipment.shippingAddress.postalCode ApplePayPaymentAuthorizedEvent.payment.shippingContact.postalCode
shipping_address.country_code string   256 characters maximum Apple Pay provided shipping contact country order.defaultShipment.shippingAddress.countryCode ApplePayPaymentAuthorizedEvent.payment.shippingContact.countryCode
billing_address.first_name string   256 characters maximum Apple Pay provided billing contact name order.billingAddress.firstName ApplePayPaymentAuthorizedEvent.payment.billingContact.givenName
billing_address.last_name string   256 characters maximum Apple Pay provided billing contact name order.billing Address.lastName ApplePayPaymentAuthorizedEventt.payment.billingContact.familyName
billing_address.address1 string   256 characters maximum Apple Pay provided billing contact street address order.billing Address.address1 ApplePayPaymentAuthorizedEvent.payment.billingContact.addressLines[0]
billing_address.city string   256 characters maximum Apple Pay provided billing contact city order.billing Address.city ApplePayPaymentAuthorizedEvent.payment.billingContact.locality
billing_address.state_code string   256 characters maximum Apple Pay provided billing contact state order.billing Address.stateCode ApplePayPaymentAuthorizedEvent.payment.billingContact.administrativeArea
billing_address.postal_code string   256 characters maximum Apple Pay provided billing contact postal code order.billing Address.postalCode ApplePayPaymentAuthorizedEvent.payment.billingContact.postalCode
billing_address.country_code string   256 characters maximum Apple Pay provided billing contact country order.billing Address.countryCode ApplePayPaymentAuthorizedEvent.payment.billingContact.country

A sample request is as follows:

{
    "_v" : "1",
    "merchant_account_id" : "example-merchant-account-id",
    "session_id" : "XyY8azgOHUE47HCz6fSBn3AsepzRXE3RbbZc5E5jsWO_xEymN7DlS4ktBrJPQzBY_nBUwSavMyc0fSWNJzu0SA==",
    "order_no" : "0000001",
    "payment" : {
        "payment_id" : "089e4cd378bff63d9d7bd63f8f",
        "type" : "ApplePay",
        "amount" : 1999,
        "currency" : "USD",
        "token": "c90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ec=="
    },
    "client" : {
        "ip_address" : "127.0.0.1",
        "user_agent" : "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0",
        "accept_header" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
    },
    "customer_info" : {
        "customer_no" : "1234567890",
        "email" : "[email protected]",
        "customer_name" : "John Doe"
    },
    "shipping_address" : {
        "first_name" : "John",
        "last_name" : "Doe",
        "address1" : "5 Wall Street",
        "city" : "Burlington",
        "state_code" : "MA",
        "postal_code" : "12345",
        "country_code" : "US"
    },
    "billing_address" : {
        "first_name" : "John",
        "last_name" : "Doe",
        "address1" : "5 Wall Street",
        "city" : "Burlington",
        "state_code" : "MA",
        "postal_code" : "12345",
        "country_code" : "US"
    },
    "custom" : {
        "avs" : true,
        "fraud" : {
            "profile" : "strict",
            "max_score" : 72,
            "filters" : ["ml", "review"]
        }
    }
} 

Response

The response is as follows:

Property Description B2C Commerce Mapping Notes
_v B2C Commerce response document version number    
transaction_id PSP unique transaction identifier paymentTransaction.transactionID  
status Enum of possible logical statuses order.paymentStatus Possible values are:
  • authorized (HTTP 200)
  • refused (HTTP 200)
  • error (HTTP not 200)
custom Contains custom data.
reason_code Enum of possible reasons for status   Logged on the B2C Commerce side For "refused" or "error" status
message Optional detail message   Logged on the B2C Commerce side

A sample response for authorization appears as follows:

HTTP 200
{
    "_v" : "1",
    "transaction_id" : "8989127187123781",
    "status" : "authorized"
}     

A sample response for refusal appears as follows:

HTTP 200
{
    "_v" : "1",
    "transaction_id" : "7123781898912718",
    "status" : "refused",
    "reason_code" : "declined"
}  

A sample response for an error appears as follows:

HTTP 400
{
    "_v" : "1",
    "status" : "error",
    "reason_code" : "invalid",
    "message" : "Missing required field: payment.token.payment_data"
}

A sample response that includes customization appears as follows:

{
    "_v" : "1",
    "transaction_id" : "8989127187123781",
    "status" : "authorized",
    "custom" : {
        "auth_code" : 1,
        "card_type" : "Visa",
        "masked_number" : "XXXX-XXXX-XXXX-1111",
        "fraud" : {
            "score" : 51,
            "status" : "REVIEW"
        }
    }
}    

HTTPS Statuses

The HTTPS statuses include:

Status Description Notes Example Cases
200 OK Request handled normally Possible statuses are:
  • authorized
  • refused

Omit message property

Successful authorization

Over credit limit

Insufficient funds

Fraud suspected

3xx Redirects B2C Commerce will follow redirects PSP should avoid in practice PSP operations need
400 Bad Request Request could not be handled Error status only

Malformed document

Missing required property, including merchant account identifier

Invalid property value

401 Unauthorized Request was not authorized Unauthorized HTTP request, not unauthorized payment

Authorization: Basic header missing

Authorization: Basic header not authorized

403 Forbidden Credentials are not permitted access Need correct PSP credentials

Authorization: Basic header authorized but not permitted use of this API

Merchant account identifier not permitted use of this API

404 Not Found Incorrect URL   B2C Commerce bug or configuration error
405 Method Not Allowed Incorrect HTTP method used Should always be POST B2C Commerce bug
500 Internal Server Error Unknown error on PSP side B2C Commerce will retry at least once PSP bug

Reason Codes

Code Status Notes Apple
parse error 400 Bad Request responses  
invalid error 400 Bad Request responses

Include message property if possible

 
billing_address refused Invalid billing postal address ApplePaySession.STATUS_INVALID_ID_BILLING_POSTAL_ADDRESS
shipping_address refused Invalid shipping postal address ApplePaySession.STATUS_INVALID_SHIPPING_POSTAL_ADDRESS
shipping_contact refused Invalid shipping contact ApplePaySession.STATUS_INVALID_SHIPPING_CONTACT
pin_required refused PIN required ApplePaySession.STATUS_PIN_REQUIRED
pin_incorrect refused PIN incorrect ApplePaySession.STATUS_PIN_INCORRECT
pin_lockout refused PIN lockout ApplePaySession.STATUS_PIN_LOCKOUT
declined refused All other declined transactions ApplePaySession.STATUS_FAILURE
fraud refused All fraud related refusals ApplePaySession.STATUS_FAILURE
canceled refused All canceled transactions ApplePaySession.STATUS_FAILURE