GuidesAPI ReferenceDiscussions

ApplePayDeposit

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.

Creating the ApplePay session

The first step is to create a session.
For the browser script to initiate the dialog with Apple this session needs to be created first, then passed back to Apple from the browser.

The following call with initiate a session and return a session key back to the browser.

API v4 request:

https://{{host}}/api/v4/merchants/{{merchant}}/shops/{{shop}}/appleSession?token={{v4-auth-token}}&validationUrl=https%3A%2F%2Fapple-pay-gateway-cert.apple.com%2Fpaymentservices%2FstartSession&domainName=api.test2.kalixa.com

API v4 response:

{
	"session": {
		"epochTimestamp": 1686043326753,
		"expiresAt": 1686046926753,
		"merchantSessionIdentifier": "SSHFC5FC375A03641CCBA6F560ED44DA3C7_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24",
		"nonce": "20ce53f9",
		"merchantIdentifier": "E811ABBDF20B25873C67AB93AFDB43F4812D5F67CF47D32E083594307798E9E8",
		"domainName": "api.test2.kalixa.com",
		"displayName": "Renegades",
		"signature": "308006092a864886f70d010702a0803080020101310d300b0609608648016503040201308006092a864886f70d0107010000a080308203e330820388a00302010202084c304149519d5436300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3139303531383031333235375a170d3234303531363031333235375a305f3125302306035504030c1c6563632d736d702d62726f6b65722d7369676e5f5543342d50524f4431143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004c21577edebd6c7b2218f68dd7090a1218dc7b0bd6f2c283d846095d94af4a5411b83420ed811f3407e83331f1c54c3f7eb3220d6bad5d4eff49289893e7c0f13a38202113082020d300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726c301d0603551d0e041604149457db6fd57481868989762f7e578507e79b5824300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d0403020349003046022100be09571fe71e1e735b55e5afacb4c72feb445f30185222c7251002b61ebd6f55022100d18b350a5dd6dd6eb1746035b11eb2ce87cfa3e6af6cbd8380890dc82cddaa63308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004f017118419d76485d51a5e25810776e880a2efde7bae4de08dfc4b93e13356d5665b35ae22d097760d224e7bba08fd7617ce88cb76bb6670bec8e82984ff5445a381f73081f4304606082b06010505070101043a3038303606082b06010505073001862a687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65726f6f7463616733301d0603551d0e0416041423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b300f0603551d130101ff040530030101ff301f0603551d23041830168014bbb0dea15833889aa48a99debebdebafdacb24ab30370603551d1f0430302e302ca02aa0288626687474703a2f2f63726c2e6170706c652e636f6d2f6170706c65726f6f74636167332e63726c300e0603551d0f0101ff0404030201063010060a2a864886f7636406020e04020500300a06082a8648ce3d040302036700306402303acf7283511699b186fb35c356ca62bff417edd90f754da28ebef19c815e42b789f898f79b599f98d5410d8f9de9c2fe0230322dd54421b0a305776c5df3383b9067fd177c2c216d964fc6726982126f54f87a7d1b99cb9b0989216106990f09921d00003182018830820184020101308186307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b300906035504061302555302084c304149519d5436300b0609608648016503040201a08193301806092a864886f70d010903310b06092a864886f70d010701301c06092a864886f70d010905310f170d3233303630363039323230365a302806092a864886f70d010934311b3019300b0609608648016503040201a10a06082a8648ce3d040302302f06092a864886f70d01090431220420df972d74dfb4099e365839221197cf427f17f913b024322a6245b0966fb60f1e300a06082a8648ce3d0403020447304502206cc88b5f9138e4ea853312a99ef246f0ad6928bcbaa163ec5062eafbb64fdaaa022100c0ea029a859fc8ba7ec967e00b5a520146b1de6ee179c1898f344d3818426742000000000000",
		"operationalAnalyticsIdentifier": "Renegades:E811ABBDF20B25873C67AB93AFDB43F4812D5F67CF47D32E083594307798E9E8",
		"retries": 0,
		"pspId": "E811ABBDF20B25873C67AB93AFDB43F4812D5F67CF47D32E083594307798E9E8"
	}
}

The following method ID is covered in this section:

IDNameCredit/Debit State
298AppleVisaDepositAuthorisedByProvider (13)
CapturedByProvider (27)
300AppleECMCDepositAuthorisedByProvider (13)
CapturedByProvider (27)
364AppleMaestroDepositAuthorisedByProvider (13)
CapturedByProvider (27)
391AppleDiscoverDepositAuthorisedByProvider (13)
CapturedByProvider (27)
397Apple AMEX DepositAuthorisedByProvider (13)
CapturedByProvider (27)

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

State Diagram

Redirect Integration

Currently not supported.

Backend2Backend Integration

The following table contains the fields to be sent in specificPaymentData section of the request:

key (value type, account type, required)value
PaymentDescription
(string, required)		Text describing the deposit method
PaymentDescriptionLanguageCode
(string, required)		Two letter language: ex. "en"
ThreeDSecureCheckResult
(int, required)		Always provide "4" in the request
ThreeDSecureCAVV
(string, required)		ThreeD secure data, provided in the Applepay (PaymentData.OnlinePaymentCryptogram) or Googlepay (paymentMethodDetails.cryptogram) payloads after decryption
ThreeDSecureECI
(string, required)		ThreeD secure data, provided from the Applepay payloads (PaymentData.EciIndicator) or the Googlepay payloads (paymentMethodDetails.eciIndicator) after decryption, if present.

The following table contains the fields to be sent in specificPaymentAccountData section of the request:

key (value type, account type, required)value
CardNumber
(string, requried)		DPAN number from the ApplePay payload (applicationPrimaryAccountNumber) or GooglePay payload (paymentMethodDetails.pan)
ExpiryMonth
(int, requried)		Card expiry month from the ApplePay payload (applicationExpirationDate(extracted month)) or from the GooglePay payload (paymentMethodDetails.expirationMonth)
ExpiryYear
(int, requried)		Card expiry year from the ApplePay payload (applicationExpirationDate(extracted year)) or from the GooglePay payload (paymentMethodDetails.expirationYear)

📘

Sample values

Please note that the ThreeDSecureCAVV and ThreeDSecureECI values in the samples below are only examples. Check the description above to extract the correct values from the ApplePay or GooglePay payload.

Example initiatePaymentRequest (AppleVisaDeposit):

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>KalixaAcceptDEMO</merchantID>
    <shopID>KalixaAcceptDEMO</shopID>
    <merchantTransactionID>9d9f2bd1-bdc0-4746-b1ac-j5gessd23</merchantTransactionID>
    <paymentMethodID>298</paymentMethodID>
    <amount currencyCode="EUR">10</amount>
    <userID>usertsani</userID>
    <userIP>127.0.0.1</userIP>
    <userSessionID>af1d6858-aab5-4ff2-875f-203c785fc9df</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>VISA Payment</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescriptionLanguageCode</key>
            <value>en</value>
        </data>
        <data xsi:type="keyIntValuePair">
            <key>ThreeDSecureCheckResult</key>
            <value>4</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ThreeDSecureCAVV</key>
            <value>jLRabyR3C2QaABEAAFHSuWJ7w5g=</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ThreeDSecureECI</key>
            <value>05</value>
        </data>
    </specificPaymentData>
    <paymentAccount>
        <specificPaymentAccountData>
            <data xsi:type="keyStringValuePair">
                <key>CardNumber</key>
                <value>4111111111111111</value>
            </data>
            <data xsi:type="keyIntValuePair">
                <key>ExpiryMonth</key>
                <value>1</value>
            </data>
            <data xsi:type="keyIntValuePair">
                <key>ExpiryYear</key>
                <value>2020</value>
            </data>
        </specificPaymentAccountData>
    </paymentAccount>
</initiatePaymentRequest>

Example initiatePaymentResponse (AppleVisaDeposit):

<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>298</key>
            <value>AppleVisaDeposit</value>
        </paymentMethod>
        <merchantTransactionID>9d9f2bd1-bdc0-4746-b1ac-j5gessd23</merchantTransactionID>
        <paymentID>64bd669b-85f8-4cc7-82f2-47a732aa38bc</paymentID>
        <userID>usertsani</userID>
        <paymentProvider>
            <key>92</key>
            <value>CQRUK</value>
        </paymentProvider>
        <amount currencyCode="EUR">10</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>302f5f44-1af6-47a0-836f-5ef919020aa8</id>
            <definition>
                <key>13</key>
                <value>AuthorisedByProvider</value>
            </definition>
            <createdOn>2019-03-05T09:05:00.7401631Z</createdOn>
            <description>Approved or completed successfully</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>0</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ApprovalCode</key>
                    <value>131185</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">10</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>AccountBalanceCurrencyCode</key>
                <value>EUR</value>
            </detail>
            <detail xsi:type="keyDecimalValuePair">
                <key>AccountBalanceAmount</key>
                <value>150.01</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>11339795</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>cdf92860-4c93-4fbb-8c42-532fed695f26</paymentAccountID>
            <details>
                <detail xsi:type="keyStringValuePair">
                    <key>MaskedNumber</key>
                    <value>************1111</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>AccountOwnerToken</key>
                    <value>214d8a0e-a34d-45fb-86fd-c3a93a6f9f9e</value>
                </detail>
                <detail xsi:type="keyIntValuePair">
                    <key>ExpiryMonth</key>
                    <value>1</value>
                </detail>
                <detail xsi:type="keyIntValuePair">
                    <key>ExpiryYear</key>
                    <value>2020</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>HolderName</key>
                    <value>TEST1</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>CardType</key>
                    <value>Visa</value>
                </detail>
            </details>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

Example initiatePaymentRequest (AppleECMCDeposit):

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>KalixaAcceptDEMO</merchantID>
    <shopID>KalixaAcceptDEMO</shopID>
    <merchantTransactionID>9d9f2bd1-bdc0-4746-b1ac-gh34hywas</merchantTransactionID>
    <paymentMethodID>300</paymentMethodID>
    <amount currencyCode="EUR">10</amount>
    <userID>usertsani</userID>
    <userIP>127.0.0.1</userIP>
    <userSessionID>af1d6858-aab5-4ff2-875f-203c785fc9df</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>hi</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescriptionLanguageCode</key>
            <value>en</value>
        </data>
        <data xsi:type="keyIntValuePair">
            <key>ThreeDSecureCheckResult</key>
            <value>4</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ThreeDSecureCAVV</key>
            <value>jLRabyR3C2QaABEAAFHSuWJ7w5g=</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ThreeDSecureECI</key>
            <value>02</value>
        </data>
    </specificPaymentData>
    <paymentAccount>
        <specificPaymentAccountData>
            <data xsi:type="keyStringValuePair">
                <key>CardNumber</key>
                <value>5472509295772840</value>
            </data>
            <data xsi:type="keyIntValuePair">
                <key>ExpiryMonth</key>
                <value>1</value>
            </data>
            <data xsi:type="keyIntValuePair">
                <key>ExpiryYear</key>
                <value>2020</value>
            </data>
        </specificPaymentAccountData>
    </paymentAccount>
</initiatePaymentRequest>

Example initiatePaymentResponse (AppleECMCDeposit):

<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>300</key>
            <value>AppleECMCDeposit</value>
        </paymentMethod>
        <merchantTransactionID>9d9f2bd1-bdc0-4746-b1ac-gh34hywas</merchantTransactionID>
        <paymentID>2ed50134-3e97-4201-bb9d-8d6b3a5dbb15</paymentID>
        <userID>usertsani</userID>
        <paymentProvider>
            <key>92</key>
            <value>CQRUK</value>
        </paymentProvider>
        <amount currencyCode="EUR">10</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>9b762bd0-e719-4e2c-ae06-2aed647459cd</id>
            <definition>
                <key>13</key>
                <value>AuthorisedByProvider</value>
            </definition>
            <createdOn>2019-03-05T09:06:40.6181652Z</createdOn>
            <description>Approved or completed successfully</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>0</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ApprovalCode</key>
                    <value>947103</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">10</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>AccountBalanceCurrencyCode</key>
                <value>EUR</value>
            </detail>
            <detail xsi:type="keyDecimalValuePair">
                <key>AccountBalanceAmount</key>
                <value>150.01</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>11339815</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>a5915277-2aac-4d34-98d3-5363baa32f59</paymentAccountID>
            <details>
                <detail xsi:type="keyStringValuePair">
                    <key>MaskedNumber</key>
                    <value>************2840</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>AccountOwnerToken</key>
                    <value>d61b3c8d-9c70-415d-b2c5-5bc927a4b52e</value>
                </detail>
                <detail xsi:type="keyIntValuePair">
                    <key>ExpiryMonth</key>
                    <value>1</value>
                </detail>
                <detail xsi:type="keyIntValuePair">
                    <key>ExpiryYear</key>
                    <value>2020</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>HolderName</key>
                    <value>TEST1</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>CardType</key>
                    <value>Mastercard</value>
                </detail>
            </details>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

Notifications

The notifications are sent according the card payment methods' integration manual. (see Card Payments)

Provider status codes

https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/apple_pay_status_codes

Updated 2 months ago