Skip to main content

Apple Pay Direct Payment Request

PayTabs Technical Portal provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages.

Be Aware Of
Be aware that Apple Pay MUST be enabled in your PayTabs profile in order to perform any payments using it, so kindly make sure to contact customercare@paytabs.com or your account manager requesting to enable Apple Pay.

This guide is dedicated to the clarification of how you can integrate with Apple Pay wallet directly to be used on your own mobile application or even our Managed Form and Own Form. There are multiple ways to use Apple Pay, for easy-to-use integration, and even more easy implementation for developers.

Tip
For a better understanding, you can checkHow to integrate the ApplePay Payment Method?this is a highly recommended step.

The Endpoint and Related Postman Collection​

In this tutorial, we will rely on the ApplePay API Endpoint, mentioned on PayTabs API endpoints postman collection, which you can access fromPayTabs Postman APIs Collection. The endpoint will need to be accessed with a POST request on the below-mentioned URL

POST{{domain}}/payment/request
Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

https://secure.paytabs.sa/payment/request

Request Parameters​

To initiate a direct payment request using this endpoint, there are minimum required parameters that need to be passed with valid information. The specification of both required parameters and all the other optional parameters/features that can be used are clarified below:

ParameterData TypeMinMaxRequired
profile_id
INTAccept only valid profile number✔
The merchant Profile ID you can get from your PayTabs dashboard. For more information please check ourHow to get your account information from PT2 Dashboard?tutorial article.
To know more about this parameter pleaseclick here.
{
    "profile_id": 987654
}
tran_type
STRING

Valid string from this enum list:

sale authvoid release capture refundregister		✔
the identification of the type of the transaction. To know more about these types please check ourWhat is the "tran_type" (transaction type)?solution article.
To know more about this parameter pleaseclick here.
{
    "tran_type": "sale"
}
tran_class
STRING

Valid string from this list

ecom recurringmoto		✔
the identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check ourWhat is the "tran_class" (transaction class)?solution article.
To know more about this parameter pleaseclick here.
{
     "tran_class": "ecom"
}
cart_id
STRING
1
64
✔
Indicates the cart/order id at the merchant end to easily relate the transaction to.
To know more about this parameter pleaseclick here.
{
     "cart_id": "CART#10001"
}
cart_description
STRING
1
128
✔
Indicates the cart/order description at the merchant end to easily relate the transaction to.
To know more about this parameter pleaseclick here.
{
     "cart_description": "Description of the items/services"
}
cart_currency
STRINGValid string from the following list: SAR AED BHDEGP EUR GBP HKD IDRINR IQD JOD JPY KWDMAD OMR PKR QAR USD
Accepts both upper- and lower-case characters		✔
Indicates the transaction currency, which the customer will be charged with.
To know more about this parameter pleaseclick here.
{
     "cart_currency": "SAR"
}
cart_amount
DECIMAL
0.01
9999999999.99
✔
Indicates the amount of the transaction the customer is about to be charged Both min and max values are subjected to the merchant transaction limits.
To know more about this parameter pleaseclick here.
{
     "cart_amount": 500
}
apple_pay_token
OBJECT
N/A
✔
An object that contains the user's payment credentials.
"apple_pay_token": {
    .
    .
    .
    }
apple_pay_token.paymentMethod
OBJECT
N/A
✔
Information about the card used in the transaction.
"paymentMethod": {
        "network": "Visa",
        "type": "Debit",
        "displayName": "Visa 4228"
    }
apple_pay_token.paymentMethod.network
STRING
N/A
✔
A string, suitable for display, that is the name of the payment network backing the card.
"paymentMethod": {
        "network": "Visa"
    }
apple_pay_token.paymentMethod.type
STRING
N/A
✔
A string, suitable for display, that is the name of the payment network backing the card.
"paymentMethod": {
        "type": "Debit"
    }
apple_pay_token.paymentMethod.displayName
STRING
N/A
✔
A string, suitable for display, that describes the card.
"paymentMethod": {
        "displayName": "Visa 4228"
    }
apple_pay_token.transactionIdentifier
STRING
N/A
✔
A unique identifier for this payment.
"paymentMethod": "D32A2C43FCC4314A668FFDBXXXXF38D0BEF0B2FXXXX569CC433607BAXXXX5301"
apple_pay_token.paymentData
OBJECT
N/A
✔
An object containing the encrypted payment data.
"paymentData": {
.
.
.
}
apple_pay_token.paymentData.data
STRING
N/A
✔
Encrypted payment data
You may need to check theApple's Payment Data Keysfor the decrypted payment data keys and values.
"data": "P\/l0iLnWAj393LZyMjdblyJHo8zUrAv2.........LDCFkIHhOlu8g=",
apple_pay_token.paymentData.signature
STRING
N/A
✔
Signature of the payment and header data
The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.
"signature": "MIAGCSqGSIb3DQEHA......0EAwIwejEuMCwGA1U==",
apple_pay_token.paymentData.header
OBJECT
N/A
✔
Additional version-dependent information you use to decrypt and verify the payment
You may need to checkApple's Payment Data Keys.
"header": {
    .
    .
    .
 }
apple_pay_token.paymentData.header.publicKeyHash
STRING
N/A
✔
Hash of the X.509 encoded public key bytes of the merchant’s certificate.
"header": {
    "publicKeyHash": "dQ1T3uh4uMRK7OAynypjLF7V9NWdL49JVKIHU+jDsww=",
 }
apple_pay_token.paymentData.header.ephemeralPublicKey
STRING
N/A
✔
Ephemeral public key bytes
EC_v1 ONLY.
"header": {
"ephemeralPublicKey": "MFkwEwYHKoZIz........u4HT92GNy5efMcinrAyev2Mwy+zg==",
 }
apple_pay_token.paymentData.header.transactionId
STRING
N/A
✔
Transaction identifier, generated on the device.
"header": {
"transactionId": "d32a2c43fcc4314.....433607ba51d25301"
 }
apple_pay_token.paymentData.version
STRING
N/A
✔
Version information about the payment token
The token uses EC_v1 for ECC-encrypted data and RSA_v1 for RSA-encrypted data.
"version": "EC_v1"
customer_details
OBJECT
-
-
✔
Indicates the customer details for this payment. If provided, the payment page will be prefilled with the provided data.
To know more about this parameter pleaseclick here. 
{
    "customer_details": {
        "name": "first last",
        "email": "email@domain.com",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "du",
        "country": "AE",
        "zip": "12345"
    }
}
customer_details.name
STRING
3
128
✔
{
    "customer_details": {
        "name": "first last",
    }
}
customer_details.email
STRING
Valid email format
✔
{
    "customer_details": {
        "email": "email@domain.com",
    }
}
customer_details.phone
STRING
Valid number + country code prefix
✔
{
    "customer_details": {
        "phone": "0522222222",
    }
}
customer_details.street1
STRING
3
128
✔
{
    "customer_details": {
        "street1": "address street",
    }
}
customer_details.city
STRING
3
128
✔
{
    "customer_details": {
        "city": "Riyadh",
    }
}
customer_details.state
STRING
2
2
✔
{
    "customer_details": {
        "state": "SA",
    }
}
customer_details.country
STRING
ISO 3166-1 alpha-2 codes (two-letter country codes)
✔
{
    "customer_details": {
        "country": "SA",
    }
}
customer_details.zip
STRING
Valid zip code
✔
{
    "customer_details": {
        "zip": "12345"
    }
}

Request & Response Payload Samples​

This section is dedicated give you a sample API request payload using the above mentioned required parameters, along with showing you the response payload received upon using the request payload.

The below sample request payload will show you how you can pass the above-mentioned required parameter/s, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.
{
    "profile_id": 47125,
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "cart_88888",
    "cart_description": "Sample Payment",
    "cart_currency": "{{currency}}",
    "cart_amount": "1",
    "return": "none",
    "customer_details": {
        "name": "John Smith",
        "email": "jsmith@gmail.com",
        "street1": "404, 11th st, void",
        "city": "Dubai",
        "country": "AE",
        "phone": "97333333101",
        "ip": "99.99.00.00"
    },
    "apple_pay_token": {
        "paymentMethod": {
        "network": "Visa",
        "type": "Debit",
        "displayName": "Visa 4228"
    },
    "transactionIdentifier": "D32A2C43FCC4314A668FFDB95B0F38D0BEF0B2F6AC8569CC433607BA51D25301",
    "paymentData": {
        "data": "P\/l0iLnWAj393LZyMjdblyJHo8zUrAv2i73tcSnFkLDCFkuk35oh5+CCA7G6rBFXD0O6iu3kS3cE+yW3uhS88vI7jqMMG4bnJ0GdJUckJ6P7o++IurHG0bIHhOlu8gqL\/1Bd73sHAKp4eK8GRQ0muRQGPwpTUf82J6mvntA\/QhQ3b4Bd2ycn0N5T31XA8okVdNi++8TBuFgflz+61arcrtd7cIQ2lHmqOSk65qV\/EdxpOGAzEjnexgk640cvvfp0rufusssFsgNeW\/0sWniqWqmF64XeA3W2W6rlFThtYOjivbkjeB5fpZaa+fVYKehOF9v4z0\/XENOmVzLFVUqS\/Ba2NKeuMeBt3uporjg4o7rWaguCubz73qYkxSs+KxULy9b+yn692RvarmlNiE92dQ6XIAX1ASUAtMktYNU9nPg=",
        "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCCA4ugAwIBAgIIaGD2mdnMpw8wCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE2MDYwMzE4MTY0MFoXDTIxMDYwMjE4MTY0MFowYjEoMCYGA1UEAwwfZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtU0FOREJPWDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgjD9q8Oc914gLFDZm0US5jfiqQHdbLPgsc1LUmeY+M9OvegaJajCHkwz3c6OKpbC9q+hkwNFxOh6RCbOlRsSlaOCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwHQYDVR0OBBYEFAIkMAua7u1GMZekplopnkJxghxFMAwGA1UdEwEB\/wQCMAAwHwYDVR0jBBgwFoAUI\/JJxE+T5O8n5sT2KGw\/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB\/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB\/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQDaHGOui+X2T44R6GVpN7m2nEcr6T6sMjOhZ5NuSo1egwIhAL1a+\/hp88DKJ0sv3eT3FxWcs71xmbLKD\/QJ3mWagrJNMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN\/EuT4TNW1WZbNa4i0Jd2DSJOe7oI\/XYXzojLdrtmcL7I6CmE\/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu\/0uSzAPBgNVHRMBAf8EBTADAQH\/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966\/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK\/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjDCCAYgCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghoYPaZ2cynDzANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yMDA2MTYwOTQ5MDlaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEILdZb7ICrNx5ZgvQt3OlTdlF57svjNEbx7YslS+w4DPyMAoGCCqGSM49BAMCBEcwRQIgZFY0mdI63DwtrciRA3xRWPCL+QD2KXPWPUC8b2azEKkCIQCb90ECiwGTt4TOm194OCo9wusSNlZipzmy1XBPohv8sAAAAAAAAA==",
        "header": {
            "publicKeyHash": "dQ1T3uh4uMRK7OAynypjLF7V9NWdL49JVKIHU+jDsww=",
            "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEcPy\/H\/285E6ruf9Y4Yn3D41MdtLFRqdGVPoXr6wWpWk\/cBr31AZSVWCorIu4HT92GNy5efMcinrAyev2Mwy+zg==",
            "transactionId": "d32a2c43fcc4314a668ffdb95b0f38d0bef0b2f6ac8569cc433607ba51d25301"
        },
        "version": "EC_v1"
    }
}
}

The Payment Flow Experience​

Reaching this point, you are now able to initiate an ApplePay payment via the direct API request, the payment flow would vary than the normal payment flow you would be used to so here’s how it works:

  1. Triggering Apple Pay Wallet: When the customer clicks the Apple Pay “PAY” button, the Apple Pay wallet will pop up on the operating system.

  2. Selecting a Card: The customer must select one of the saved cards in the wallet to initiate the payment.

  3. Generating Apple Pay Token: Upon card selection, a request is sent to Apple Pay, which returns the necessary token parts required by the PayTabs Apple Pay Payment request endpoint.

  4. Initiating Payment: The payment is initiated using the token sent from the merchant’s server to the PayTabs server.
Tip
For a detailed understanding of the flow, refer to the Apple Pay documentation.

As a Summary of Payment Flow:

  1. The Apple Pay button triggers the Wallet Screen to pop up.

  2. Selecting a card returns an applepay_token.

  3. The applepay_token is sent to the merchant’s server side.

  4. The merchant’s server makes the Apple Pay payment request.

Tip
Please note that requesting the token and Apple Pay details from the Apple Pay side is beyond the scope of PayTabs. However, we recommend referring to the following documentation for guidance on the Apple side: