Paytabs provides you with a collection of API endpoints which used to process all payments, regardless of whether they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages.
There are multiple ways to use Apple Pay, for easy-to-use integration, and even more easy implementation for developers.
For a better understanding, you can check How to integrate the ApplePay Payment Method? this is a highly recommended step.In this article you will learn about:
- The Endpoint and Related Postman Collection
- Payment Flow
- The Minimum Required Parameters
- The Available Optional Parameters
- The Request payload
- The Response payload
The Endpoint and Related Postman Collection
In this tutorial, we will rely on the API Endpoint, mentioned on the PayTabs API endpoints postman collection, which you can access from here. The endpoint will need to be accessed with a POST request on the below-mentioned URL
| Post | {{domain}}/payment/request |
Please note that not using the proper endpoint URI {{domain}} will lead to authentication issues within your responses. To find your proper domain you can read our What Is My (Region)/(endpoint URL)? solution article.Payment Flow
Once the customer clicks on the Apple Pay "PAY" button, he would trigger the Apple Pay wallet on the OS to pop up. After that, the customer will have to choose one of the saved cards in the wallet to initiate the payment using it.
A request would be sent to Apple Pay once the customer selects the card, which will return the Apple Pay token parts that are required by the Paytabs Apple Pay Payment request endpoint. This would allow the payment to be initiated using the token sent from the merchant server side to the Paytabs side. Check the ApplePay documentation for a better understanding of the flow.
In other words, the payment flow of this endpoint is summarized as shown below:
- The Apple Pay button would trigger the Wallet Screen to Popup.
- Choosing a card would return an applepay_token.
- The applepay_token would be sent to the merchant server-side.
- Merchant's server-side would make the Apple Pay payment request.
Noting note that requesting the token and Apple Pay details from Apple Pay side is out of Paytabs scope, However We would suggest following the below documentation for Apple side:
- Displaying Apple Pay Buttons Using JavaScript
- Choosing an API for Implementing Apple Pay on Your Website
- ApplePayPaymentRequest
- ApplePayPayment The result of authorizing a payment request that contains payment information.
The Minimum Required Parameters
To initiate a payment request using this integration type, there are minimum required parameters that need to be passed with valid information. The specification of these required parameters is clarified below.
Parameter | Required | Purpose |
✔ | The merchant Profile ID you can get from your PayTavs dashboard. For more information please check our How to get your account information from PT2 Dashboard? solution article. To know more about this parameter please click here. | |
✔ | The identification of the type of transaction. To know more about these types please check our What is the "tran_type" (transaction type)? solution article.
To know more about this parameter please click here. | |
✔ | The identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check our What is the "tran_class" (transaction class)? solution article For this request, the transaction class MUST be "ecom". To know more about this parameter please click here. | |
✔ | Indicates the cart/order id at the merchant end to easily relate the transaction to To know more about this parameter please click here. | |
✔ | Indicates the cart/order description at the merchant end to easily relate the transaction to To know more about this parameter please click here. | |
✔ | Indicates the transaction currency, which the customer will be charged with To know more about this parameter please click here. | |
✔ | Indicates the amount the customer is about to be charged. To know more about this parameter please click here. |
Now, In order to create a payment request through Apple Pay, you need - in addition to the above general required parameters - to include new parameters required. Find below the Additional required parameters for Apple:
Parameter | Required | Purpose |
apple_pay_token | ✔ | |
apple_pay_token.paymentMethod | ✔ | |
apple_pay_token.paymentMethod.network | ✔ | |
apple_pay_token.paymentMethod.type | ✔ | |
apple_pay_token.paymentMethod.displayName | ✔ | |
apple_pay_token.transactionIdentifier | ✔ | |
apple_pay_token.paymentData | ✔ | |
apple_pay_token.paymentData.data | ✔ | |
apple_pay_token.paymentData.signature | ✔ | |
apple_pay_token.paymentData.header | ✔ | |
apple_pay_token.paymentData.header.publicKeyHash | ✔ | |
apple_pay_token.paymentData.header.ephemeralPublicKey | ✔ | |
apple_pay_token.paymentData.header.transactionId | ✔ | |
apple_pay_token.paymentData.version | ✔ | |
✔ | Indicates the customer details for this payment. To know more about this parameter please click here. | |
customer_details.name | ✔ | |
customer_details.email | ✔ | |
customer_details.phone | ✔ | |
customer_details.street1 | ✔ | |
customer_details.city | ✔ | |
customer_details.state | ✔ | |
customer_details.country | ✔ | |
customer_details.zip | ✔ | |
customer_details.ip | ✔ |
The Available Optional Parameters
Besides the above-mentioned required parameters, PayTabs provides you with several optional parameters, each of which empowers you with a different feature and the ability to customize your payment request as much as possible it could be. The specification of these optional parameters is clarified below:
Parameter | Required | Purpose |
callback | ❌ | The callback response is a server-to-server POST response that is sent (to a pre-defined HTTPS URL) with the full detailed transaction information once the payment process has ended (whether the customer cancels, paid, or failed to pay). It does not depend on the customer's actions; the response will be sent anyway.
|
shipping_details | ❌ | Indicates the shipping details for this payment. If provided, the payment page will be prefilled with the provided data. Learn more about The Shipping Details |
shipping_details.name | ❌ | |
shipping_details.email | ❌ | |
shipping_details.phone | ❌ | |
shipping_details.street1 | ❌ | |
shipping_details.city | ❌ | |
shipping_details.state | ❌ | |
shipping_details.country | ❌ | |
shipping_details.zip | ❌ | |
tokenise | ❌ | The tokenization format the generated token should follow. |
user_defined | ❌ | For more customizations, you can pass to the Transaction API request your own "user-defined fields" up to 9 fields, and accordingly, you would receive those fields in the callback response.
|
user_defined.udf1 | ❌ | |
user_defined.udf2 | ❌ | |
user_defined.udf3 | ❌ | |
user_defined.udf4 | ❌ | |
user_defined.udf5 | ❌ | |
user_defined.udf6 | ❌ | |
user_defined.udf7 | ❌ | |
user_defined.udf8 | ❌ | |
user_defined.udf9 | ❌ |
The Request payload
As the payment page is on your side (merchant side), you must send a payment request using the transaction API after receiving the card details from your payment page. You will need to include the customer details in the payment request.
{
"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": "[email protected]",
"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 Response payload
Once the managed form request is validated and initiated, you will receive the following response.
{
"tran_ref": "TST2222801314561",
"merchant_id": 31237,
"profile_id": 47125,
"cart_id": "cart_88888",
"cart_description": "Sample Payment",
"cart_currency": "EGP",
"cart_amount": "1",
"tran_currency": "EGP",
"tran_total": "133.00",
"tran_type": "Sale",
"customer_details": {
"name": "John Smith",
"email": "[email protected]",
"street1": "404, 11th st, void",
"city": "Dubai",
"country": "AE",
"phone": "97333333101",
"ip": "99.99.00.00"
},
"payment_result": {
"response_status": "A",
"response_code": "G43489",
"response_message": "Authorised",
"acquirer_message": "00:Approved",
"acquirer_rrn": "220210096025",
"transaction_time": "2022-08-16T09:51:29Z"
},
"payment_info": {
"payment_method": "ApplePay",
"card_type": "Debit",
"card_scheme": "Visa",
"payment_description": "Visa 4228",
"expiryMonth": 12,
"expiryYear": 2023
},
"serviceId": 2
}
You can notice that the payment is already made, A transaction has been created, and you are already receiving the payment results