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


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:

  1. The Apple Pay button would trigger the Wallet Screen to Popup.
  2. Choosing a card would return an applepay_token.
  3. The applepay_token would be sent to the merchant server-side.
  4. 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. 


For this request, the transaction type could be either "sale" or "auth"

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.   
Both min and max values are subjected to the merchant transaction limits
.


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. 


Learn more about the callback URL Parameter

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. 

Learn more about Token Management

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.


Learn more about The Custom Parameters

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