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.
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.
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:
|
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:
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 |