GuidesAPI ReferenceDiscussions

Apple Pay Deposit (Browser-based flow)

Suggest Edits

ApplePay is a secure, easy way to make payments for physical goods and services within iOS and watchOS. Websites can also accept ApplePay – it is available in Safari for iPhone, iPad, and Mac. Users authorize payments and provide shipping and contact information, using securely stored credentials on an iPhone, an iPad, or a MacBook Pro with Touch ID. On other Macs, the purchase is confirmed with the user's nearby iPhone or Apple Watch that has ApplePay enabled.

The following method ID is covered in this section:

IDNameCredit/Debit State
292AppleCardDepositN/A

Payment method interaction type: Synchronous Execution (see Interaction Types)

State Diagram

859

Redirect Integration

Currently not supported.

Backend2Backend Integration

ApplePay integration in PXP Financial PaymentService requires 2 operations:

1. Initiate new ApplePay session - a secured signed request is performed (using Merchant Identity certificate) against Аpple API and a new ApplePay session is triggered.

To initiate an ApplePay deposit the initiatePayment web method should be invoked. The following table contains the fields to be sent in specificPaymentData section of the request:

key (value type, account type, required)value
UrlTarget
(string, required)		Validation url for ApplePay session. This is the url passed on the client side inside onvalidatemerchant callback.
DomainName
(string, requried)		Merchant's domain name registered for applePay with Apple.
PaymentDescription
(string, requried)		Text describing the deposit method
PaymentDescriptionLanguageCode
(string, requried)		Two letter language: ex. "en"

Example initiatePaymentRequest:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
      <merchantID>KalixaAcceptDEMO</merchantID>
      <shopID>KalixaAcceptDEMO</shopID>
      <merchantTransactionID>1e62343431-4545-4h1236fg1-6bc364812da5i19y</merchantTransactionID>
      <paymentMethodID>292</paymentMethodID> <!-- AppleCardDeposit -->
      <amount currencyCode="EUR">10.00</amount>
      <userID>ABC</userID>
      <userSessionID>df07248d-b65f-450c-a018-64f12e9d62fc</userSessionID>
      <creationTypeID>1</creationTypeID>
      <specificPaymentData>
         <data xsi:type="keyStringValuePair">
            <key>UrlTarget</key>
            <!--https://url-from-client-side-applePaySession.onvalidatemerchant-callback -->
            <value>https://api.test.kalixa.com/WebMockProviders/api/applepayapi/validateMerchant</value>
         </data>
         <data xsi:type="keyStringValuePair">
            <key>DomainName</key>
            <!--##Registered apple pay domain name##-->
            <value>merchant.com</value>
         </data>
          <data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>Apple visa deposit</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescriptionLanguageCode</key>
			<value>en</value>
		</data>
      </specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse:

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>KalixaAcceptDEMO</merchantID>
        <shopID>KalixaAcceptDEMO</shopID>
        <paymentMethod>
            <key>292</key>
            <value>AppleCardDeposit</value>
        </paymentMethod>
        <merchantTransactionID>1e62343431-4545-4h1236fg1-6bc364812da5i19y</merchantTransactionID>
        <paymentID>59a91b94-4627-4712-b55d-1f83ac431c57</paymentID>
        <userID>ABC</userID>
        <paymentProvider>
            <key>160</key>
            <value>Apple</value>
        </paymentProvider>
        <amount currencyCode="EUR">10.00</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <state>
            <id>4aa3a5ad-b5f8-4d02-9d87-90fa44f20bd8</id>
            <definition>
                <key>3</key>
                <value>InitiatedByProvider</value>
            </definition>
            <createdOn>2018-06-05T13:44:54.1877768Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">10</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>DeviceFingerprintingSessionID</key>
                <values>{"epochTimestamp":1614077012905,"expiresAt":1614080612905,"merchantSessionIdentifier":"SSH96EBC9A7FC144B7AA27D57B0DC0F5769_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24","nonce":"fb527e70","merchantIdentifier":"E811A56DF20B25873C67AB93AFDB43F4812D5F67CF47D32E083594307798E9E8","domainName":"api.test.kalixa.com","displayName":"DisplayName","signature":"3080......","operationalAnalyticsIdentifier":"DisplayName:E811ABBDF20B25873C67AB93AFDB43F4812D5F67CF47D32E083594307798E9E8","retries":0}</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

📘

DeviceFingerprintingSessionID

The detail DeviceFingerprintingSessionID is needed for the client to initiate client side ApplePaySession.completeMerchantValidation(ApplePaySessionObjectValue) against Apple API. Value is a JSON object string.

2. Process ApplePay token - after the user authorizes the payment a payment payload with encrypted token is received from Apple. Here 4 sub-operations are performed:

  • Check the validity of the token (signature validation and other security aspects);
  • Decrypt (using Payment Processing Certificate’s private key) device specific payment card information;
  • Map AppleCardDeposit payment method to PXP Financial specific card payment method - AppleVisa Deposit, AppleECMCDeposit, etc.
  • Authorize the actual card payment - in this operation an actual card payment like AppleVisa Deposit, AppleECMCDeposit etc. is created.

🚧

The initial payment method AppleCardDeposit is changed

  • NOTE: The initial payment method AppleCardDeposit is changed to the actual card payment method after operation 2 is finalized. New card payment methods are created specifically for ApplePay for existing card deposits like:
    Visa Deposit - AppleVisaDeposit (Payment Method ID 298)
    ECMC Deposit - AppleECMCDeposit (Payment Method ID 300)
    Maestro Deposit - AppleMaestroDeposit (Payment Method ID 364)
    Discover Deposit - AppleDiscoverDeposit (Payment Method ID 391)
    Amex Deposit - Apple AMEX Deposit (Payment Method ID 397)

The new payment method replaced AppleCardDeposit after processing the token. The card payment method has the same flow as the standard card deposit payment methods - authorization, capturing and settlement.

For this operation the executePaymentAction web method should be invoked.
The following table contains executePaymentActionRequest fields:

field (type, required)description
actionID
(string, required)		Action that is executed - Process (fixed value 260307)
ApplePayTokenPayload
(string, required)		Key from actionData key-value collection which is used for transporting the ApplePay Token Payload. The Payload is encoded as Base64.

Example executePaymentActionRequest:

<?xml version="1.0" encoding="utf-8"?>
<executePaymentActionRequest 
  xmlns="http://www.cqrpayments.com/PaymentProcessing"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<merchantID>KalixaAcceptDEMO</merchantID>
	<shopID>KalixaAcceptDEMO</shopID>
	<paymentID>59a91b94-4627-4712-b55d-1f83ac431c57</paymentID>
	<actionID>260307</actionID> <!-- Process -->
	<actionData>
		<data xsi:type="keyStringValuePair">
    			<key>ApplePayTokenPayload</key>
		        <value>  
		      	  <!-- UTF8 JSON  ApplePay payload string encoded as Base64  -->
		        </value>
    		</data>
	</actionData>
</executePaymentActionRequest>

Example executePaymentActionResponse:

<?xml version="1.0" encoding="utf-8"?>
<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<statusCode>0</statusCode>
	<actionResults>
		<result xsi:type="keyStringValuePair">
			<key>PaymentMethodID</key>
			<value><!-- ID of an actual card deposit that will be used for ApplePay --></value>  		
		</result>
		<result xsi:type="keyStringValuePair">
			<key>PaymentProviderID</key>
			<value>92</value>
		</result>
		<result>
			<key>IsExecuted</key>
			<value>true</value>
		</result>
		<result >
			<key>PaymentAccountID</key>
			<value>3e27c7d9-e3d5-45df-8033-a78e66ab319e</value>
		</result>
		<result xsi:type="keyStringValuePair">
			<key>lastStateDefinition</key>
			<value>13</value>
		</result>
        <result xsi:type="keyStringValuePair">
            <key>MaskedPAN</key>
            <value>411111******1111</value>
        </result>
	</actionResults>
</executePaymentActionResponse>

State Diagram after the change of the payment method:

826

Notifications

No notification are sent until the payment is with payment method ApplePay Deposit. After changing the payment method the notifications are sent according the card payment methods' integration manual. (see Card Payments Notifications)

Provider status codes

[Apple Status code] (https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/apple_pay_status_codes)

Links

Apple JavaScript documentation

Updated about 2 years ago