Apple Pay Processing

Apple Pay

Apple Pay is a mobile payment and digital wallet service by Apple Inc. that lets users make payments using the iOS apps and on the web. It is supported on the iPhone, Apple Watch, iPad and Mac. Apple Pay does not require Apple-specific contactless payment terminals and will work with Visa's PayWave, MasterCard's PayPass, and American Express's ExpressPay terminals. It digitizes and replaces the credit or debit magnetic stripe card transaction at credit card terminals. The service lets Apple devices wirelessly communicate with point of sale systems using a near field communication (NFC) antenna, a dedicated chip that stores encrypted payment information (known as the Secure Element), and Apple's Touch ID and Passbook.

To check out at brick and mortar stores, users hold their authenticated Apple device to the point of sale system. iPhone users authenticate by holding their fingerprint to the phone's Touch ID sensor, and Apple Watch users authenticate by double clicking a button on the device.

To check out online in supported mobile apps, users choose Apple Pay as their payment method and authenticate with Touch ID.

How does Apple Pay work?

User's Initial Setup

In order to use Apple Pay, a user must first add a credit card to their Apple device/service. Users can add credit cards to the service in any of three ways: through their iTunes accounts, by taking a photo of the card, or by entering the card information manually.

During initial setup, the user's card information is encrypted and sent to Apple's servers, where Apple decrypts the data and determines the card network or card issuer. Apple then re-encrypts the data with a key and issues a token called a Device Account Number (DAN). The device account number is received by the device and stored for future use.

Purchasing using Apple Pay

When a customer wants to make a payment with Apple Pay, they bring the phone to an NFC-enabled terminal. The phone asks the customer to authenticate the payment with TouchID. That authentication signals to the phone that it can transmit the Device Account Number and its accompanying dynamic security code to the merchant's terminal, and the transaction then proceeds as a normal credit card transaction would.

Payment Service Support for Apple Pay Integration

Radial's Payment Service provides APIs that can be used to integrate Apple Pay for both in-app mobile purchase integration and Apple Pay for the Web integration through the Safari browser. Two Radial APIs are involved in completing the integration.

Apple Pay Integration Single Request Flow

This is the data flow to complete an Apple Pay transaction. The sequence diagram below shows the series of system interactions in Apple Pay for the single request integration.

  1. In the merchant's iOS application, the user (customer) clicks the Checkout with Apple Pay button.
  2. The PassKit framework connects to the Apple server and receives encrypted payment data in JSON format
  3. The IOS Application creates a CreditCardAuth request including the AppleTransactionId, EphemeralPublicKey, PublicKeyHash, Signature, and Encrypted Token Value
  4. The iOS application calls Payment Service for CreditCardAuth.
  5. Payment Service uses the .cer file and the p12 file provided by the merchant, along with the ephemeral public key passed in the API call, to decrypt the payment data.
  6. Payment Service processes the request as a regular Card Not Present transaction and returns a success or failure response.
  7. The iOS application receives the success or failure response and prompts the user accordingly

APIs Used

Apple Pay integration uses the following API operations

  • Credit Card Auth API

Credit Card Auth API

Request Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CreditCardAuthRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567">
   <WalletPaymentInformation>
     <ApplePayTransactionId>84a7e17570c940f6a268d9121a4c090f1d2e22bab4da0f2054c7ba53035dc79a</ApplePayTransactionId>
     <EphemeralPublicKey>MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEAtpj8+ZI9S3gQ7QHCM/dLYTjdSgKdXlDDI/ezdwmHc4HosSYFdYYE/v8t2CcFwJHmceet/GNE1VRO57W3VxeAg==</EphemeralPublicKey>
     <PublicKeyHash>i3F+FlIbyhjfYqMqm3M/dpeWRO9tnD+U9BJng3tkkig=</PublicKeyHash>
     <Version>EC_v1</Version>
     <Data>GcUsL3ZgQVf9Raf7fBY+0AXsoO/5REeQWE6mROAJM4QvxJgOO6mxW1CuM1P7Ox9hQo1Qt1dg/VIS5fszNq7YhB0oQNgoEwAh7bTXEUBtmx0lzvN5EWxah0ScMbv/v+7CuakmRG6c6hO4xQlayCNGV6diFK1Ng6zNphSW53b1Di6vhqJcDnGs2tvu6wHyGfqIH6AeUmCNsiBvkHsaiiHbiWcL6BPpWuoW7y5bZK3mMxgygYgzZec/XnlV5lcJocpPDcL8ouuVU/oBMZn9ox/Ql3r9E8f3g7+uTdKZ+TEoyKIH52VQUb1/YXU3SZ2Fr2J/oidUPz9+fTvGZkFPQvSX4G+jzYWlCQmrx6qZ0cfTY/ZcGmITSSbzKcgy35kTTNJdqmL8wqmOzfr202R3sXeGBjS1BqAm5DNzbgWHGrOoc/I=</Data>
     <Signature>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</Signature>
   </WalletPaymentInformation>
   <OrderId>1</OrderId>
   <BillingFirstName>John</BillingFirstName>
   <BillingLastName>Smith</BillingLastName>
   <BillingPhoneNo>6101234567</BillingPhoneNo>
   <BillingAddress>
      <Line1>123 Main St</Line1>
      <Line2>Building 123</Line2>
      <Line3>4th Floor</Line3>
      <Line4>Apt 12</Line4>
      <City>Philadelphia</City>
      <MainDivision>PA</MainDivision>
      <CountryCode>US</CountryCode>
      <PostalCode>19019</PostalCode>
   </BillingAddress>
   <CustomerEmail>customer@sample.com</CustomerEmail>
   <CustomerIPAddress>208.247.73.130</CustomerIPAddress>
   <ShipToFirstName>John</ShipToFirstName>
   <ShipToLastName>Smith</ShipToLastName>
   <ShipToPhoneNo>6101234567</ShipToPhoneNo>
   <ShippingAddress>
      <Line1>123 Main St</Line1>
      <Line2>Building 123</Line2>
      <Line3>4th Floor</Line3>
      <Line4>Apt 12</Line4>
      <City>Philadelphia</City>
      <MainDivision>PA</MainDivision>
      <CountryCode>US</CountryCode>
      <PostalCode>19019</PostalCode>
   </ShippingAddress>
</CreditCardAuthRequest>

Request Elements

Element Required Description Type Restriction
CreditCardAuthRequest/WalletPaymentInformation Yes Digital Wallet Payment Information ComplexType
CreditCardAuthRequest/WalletPaymentInformation/
ApplePayTransactionId
Yes Transaction Identifier, generated on the device. String
CreditCardAuthRequest /WalletPaymentInformation/EphemeralPublicKey Yes Hash of the X.509 encoded public key bytes of the merchant's certificate. String
CreditCardAuthRequest/WalletPaymentInformation/
PublicKeyHash
Yes Compares the Signature to the Private/Public Key for validation. String
CreditCardAuthRequest/WalletPaymentInformation/
Version
Yes Signature of the Payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm. String
CreditCardAuthRequest/WalletPaymentInformation/
Data
Yes Encrypted Payment Data. A payment data dictionary, Base64 encoded as a string.
CreditCardAuthRequest/WalletPaymentInformation/
Signature
Yes Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm. Detached PKCS 37 signature, Base64 encoded as string.
CreditCardAuthRequest/OrderId Yes Unique identifier of the order. The client must ensure uniqueness of OrderIds across all orders that the client initiates with this service. String Min 1 character
Max 20 characters
CreditCardAuthRequest/BillingFirstName Yes First name of the person on the billing address of the credit card String
CreditCardAuthRequest/BillingLastName Yes Last name of the person on the billing address of the credit card String
CreditCardAuthRequest/BillingPhoneNo Yes Phone number of the person on the billing address of the credit card String
CreditCardAuthRequest/BillingAddress Yes (for AVS verification) Billing address of the credit card ComplexType
CreditCardAuthRequest/BillingAddress/Line1 Yes

Line# components of the street address and, if necessary, suite and building identifiers for the physical address. Line1 is required.

Line2, Line3, and Line4 are optional. Include them only if the data exists. A blank AddressLine element will fail validation.

String

1 to 70 characters.

CreditCardAuthRequest/BillingAddress/Line2 No

String

1 to 70 characters.

CreditCardAuthRequest/BillingAddress/Line3 No

String

1 to 70 characters.

CreditCardAuthRequest/BillingAddres/Line4 No

String

1 to 70 characters.

CreditCardAuthRequest/BillingAddress/City Yes Name of the city String Min 1 character
Max 40 characters
CreditCardAuthRequest/BillingAddress/MainDivision No Two- or three-digit postal abbreviation for the state or province. The ISO 3166-2 code is recommended, but not required. See http://en.wikipedia.org/wiki/ISO_3166-2. String Min 1 character
Max 35 characters
CreditCardAuthRequest/BillingAddress/CountryCode Yes Two digit ISO 3166 alpha 2 code country code. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 String Min 2 characters
Max 40 characters
CreditCardAuthRequest/BillingAddress/PostalCode No String of letters and/or numbers that specifies the delivery area more closely than the city alone (for example, US ZIP code) String Min 1 character
Max 15 characters
CreditCardAuthRequest/CustomerEmail Yes Email address of the customer who is making the purchase. Used for realtime fraud checking by our API and payment processors. String Min 1 character
Max 70 characters
CreditCardAuthRequest/CustomerIPAddress Yes IP address of the customer who is making the purchase. Used for realtime fraud checking by our API and payment processors. IPv4Address Valid dotted quad IPv4 Address
CreditCardAuthRequest/ShipToFirstName Yes First name of the person on the first/primary shipping address of the order. Used for realtime fraud checking by our API and payment processors. String
CreditCardAuthRequest/ShipToLastName Yes Last name of the person on the first/primary shipping address of the order. Used for realtime fraud checking by our API and payment processors. String
CreditCardAuthRequest/ShipToPhoneNo No Phone number of the person on the first/primary shipping address of the order. Used for realtime fraud checking by our API and payment processors. String
CreditCardAuthRequest/ShippingAddress Yes First/primary shipping address of the order. Used for realtime fraud checking by our API and payment processors. For orders that do not have a shipping address, pass the billing address as the shipping address. ComplexType
CreditCardAuthRequest/ShippingAddress/Line1 Yes

Line# components of the street address and, if necessary, suite and building identifiers for the physical address. Line1 is required.

Line2, Line3, and Line4 are optional. Include them only if the data exists. A blank AddressLine element will fail validation.

String

1 to 70 characters.

CreditCardAuthRequest /ShippingAddress/Line2 No

String

1 to 70 characters.

CreditCardAuthRequest/ShippingAddress/Line3 No

String

1 to 70 characters.

CreditCardAuthRequest/ShippingAddress/Line4 No

String

1 to 70 characters.

CreditCardAuthRequest/ShippingAddress/City Yes Name of the city String Min 1 character
Max 40 characters
CreditCardAuthRequest/ShippingAddress/MainDivision No

Two- or three-digit postal abbreviation for the state or province. The ISO 3166-2 code is recommended, but not required. See http://en.wikipedia.org/wiki/ISO_3166-2.

String Min 1 character
Max 35 characters
CreditCardAuthRequest/ShippingAddress/CountryCode Yes Two digit ISO 3166 alpha 2 code country code. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 String Min 2 characters
Max 40 characters
CreditCardAuthRequest/ShippingAddress/PostalCode No

String of letters and/or numbers that specifies the delivery area more closely than the city alone (for example, U.S. ZIP code)

String Min 1 character
Max 15 characters
SchemaVersion Yes

Although marked as optional in the the schema, this element must be passed at all times with a value of 1.2 or greater in order to receive elements like 'ResponseCode' and 'TenderType' in the Response message.

String

pattern = "([0-9]+\.)*[0-9]+".
Value Example: 1.1, 1.2

Reply Example

The response is a CreditCardAuthReply message.

<?xml version="1.0" encoding="UTF-8"?>
    <CreditCardAuthReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
       <PaymentContext>
          <OrderId>1</OrderId>
          <!-- You will receive a token in the response, which is a scrambled version of the Credit Card number.
             This token gets passed to the Order Service, not the original credit card number -->
          <PaymentAccountUniqueId isToken="true">4054131ImpMJ6965</PaymentAccountUniqueId>
       </PaymentContext>
       <AuthorizationResponseCode>APPROVED</AuthorizationResponseCode>
       <BankAuthorizationCode>614653</BankAuthorizationCode>
       <CVV2ResponseCode>0</CVV2ResponseCode>
       <AVSResponseCode>E</AVSResponseCode>
       <PhoneResponseCode></PhoneResponseCode> <!-- AmEX only -->
       <NameResponseCode></NameResponseCode> <!-- AmEX only -->
       <EmailResponseCode></EmailResponseCode> <!-- AmEX only -->
       <AmountAuthorized currencyCode="USD">14.99</AmountAuthorized>
       <TenderType>VC</TenderType>
    </CreditCardAuthReply>          

Response Elements

Element Required Description Type Restriction
CreditCardAuthReply/PaymentContext Yes

Unique identifier of the payment transaction for the order

ComplexType  
CreditCardAuthReply/PaymentContext/
OrderId
Yes Unique identifier of the order. The client must ensure uniqueness of OrderIds across all orders that the client initiates with this service. String Min 1 character
Max 20 characters
CreditCardAuthReply/PaymentContext/
PaymentAccountUniqueId
Yes

Token (scrambled version) of the PAN (payment account number such as a credit card number). When passing the PAN for the PaymentAuthCancelRequest and the PaymentSettlementRequest messages, always use the returned token, not the original PAN.

String Min 1 character
Max 22 characters
CreditCardAuthReply/PaymentContext/
PaymentAccountUniqueId/
@isToken
Yes Attribute that indicates whether the PAN is tokenized. In the CreditCardAuthReply message, this attribute is always set to true. String true
CreditCardAuthReply/ResponseCode No

Response code of the credit card authorization. Includes approved, timeout, and several decline codes. Only orders with an approved or timeout response code are submitted to the Order Service.

See Authorization Response Codes for a list of codes.

String

SchemaVersion in the Request Message has to be equal to or greater than 1.1 in order to receive this element

CreditCardAuthReply/
AuthorizationResponseCode
Yes

Response code of the credit card authorization. This includes approval, timeout, and several decline codes.

See Authorization Response Codes for a list of codes.

String
CreditCardAuthReply/BankAuthorizationCode Yes

Authorization code returned by the payment processor upon a successful credit card authorization.

Any order taken by the Order Service and paid by credit card MUST have this authorization code.

String
CreditCardAuthReply/CVV2ResponseCode Yes

Payment processor response code for the CVV2 (card verification value) check.

For most credit cards, you get an approval on the ResponseCode even if the CVV2ResponseCode returns a CVV2 failure. You CANNOT accept an order if the CVV2ResponseCode returns a CVV2 failure code.

See CVV2 Response Codes for a list of codes.

String
CreditCardAuthReply/AVSResponseCode Yes

Payment processor response for the Address Verification System (AVS) check.

For most credit cards, you get an approval on the ResponseCode even if the AVSResponseCode returns an AVS failure code. It is typically considered a significant fraud risk to accept an order if the AVSResponseCode returns an AVS failure code.

See AVS Response Codes for a list of codes.

String
CreditCardAuthReply/PhoneResponseCode No (Amex only)

Response code for customer phone number verification. Only applies to Amex authorizations.

To support downstream fraud processing, this data should be included in the OrderCreateRequest for orders paid with Amex.

String
CreditCardAuthReply/NameResponseCode No (Amex only)

Response code for customer name verification. Only applies to Amex authorizations.

To support downstream fraud processing, this data should be included in the OrderCreateRequest for orders paid with Amex.

String
CreditCardAuthReply/EmailResponseCode No (Amex only)

Response code for customer email verification. Only applies to Amex authorizations.

To support downstream fraud processing, this data should be included in the OrderCreateRequest for orders paid with Amex.

String
CreditCardAuthReply/AmountAuthorized Yes Currency amount authorized on the credit card String

Positive decimal, up to two decimal places(for example, 4.75)

CreditCardAuthReply/AmountAuthorized/
@currencyCode
Yes Type of currency used for the order String 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/wiki/ISO_4217.
CreditCardAuthReply/TenderType No (Always present for Digital Wallet transactions) This element identifies the tender type used for the transaction

*Note that this value might be corrected based on Bin Range identification

String Min 2 characters
Max 4 Characters

SchemaVersion in the Request Message has to be equal to or greater than 1.2 in order to receive this element

CreditCardAuthReply/Extension No This element indicates that future optional elements may show up in this location of the XML document in the responses returned from the service.

Configuration Setup

To be configured for Apple Pay, a webstore must complete a certificate setup process. For information on this process, see Apple Pay Web Integration.

When an Apple Pay user clicks to authorize a payment, the following sequence is initiated:

  1. iOS makes a Decrypt Request API call to decrypt the encrypted blob that Apple Server sends.
  2. Payment Service decrypts the encrypted blob using the .cer file, private key and the ephemeral public key and sends it back to the iOS application.
  3. iOS application uses the decrypted payment data to create a CreditCardAuthRequest.
  4. iOS application calls Payment Service for CreditCardAuth.
  5. Payment Service processes the request as a regular card not present transaction and returns a response.
  6. iOS application receives a success or failure response and prompts the user accordingly.