Token-Based Transactions - Get Token Status

you should know

You should know that This step can be used and will behave the same in the following integration types:(Hosted Payment Page, Managed Form, Own Form).

Tokenization involves safeguarding sensitive data by substituting it with a number generated by an algorithm, known as a token. This process enables returning customers to make purchases without needing to re-enter their credit card information, such as for monthly subscription fees.

A Query Token is a REST API request that retrieves the payment and customer details associated with a specific token, along with the original transaction ID that was used to generate the token. In this manual, we will guide you through the steps to query a specific token and obtain its details.

---

The Endpoint and Related Postman Collection

In this manual, we will rely on the PayTabs Hosted Payment Page 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/token

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.

KSA

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

UAE

https://secure.paytabs.com/payment/token

Egypt

https://secure-egypt.paytabs.com/payment/token

Oman

https://secure-oman.paytabs.com/payment/token

Jordan

https://secure-jordan.paytabs.com/payment/token

Kuwait

https://secure-kuwait.paytabs.com/payment/token

Global

https://secure-global.paytabs.com/payment/token

---

The Required Parameters

To query payment tokens, certain required parameters must be provided with valid information. The details of these required parameters are outlined below:

• Profile ID
• token




Parameter	profile_id
Description	The merchant Profile ID you can get from your PayTabs 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.
Data Type	INT
Required	✔
Validation Rules	Accept only valid profile number.
Sample	{ "profile_id": 987654 }

Parameter	token
Description	To know more about this parameter please click here.
Data Type	STRING
Required	✘
Sample	{ "token": "2C4652BD67A3EF30C6B390F9668175B9" }

---

Request & Response Payloads Samples

As This endpoint act the same for all integration types ( hosted, managed , invoice ) so here is the request/response for all.

Request Sample Payload

{  
"profile_id": "profile_id",
"token": "2C4651BF67A3EC34C6B691F8638B75BC"
}

Response Sample Payload

{
  "tran_ref": "TST2111000149684",
  "payment_info": {
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111"
},
  "customer_details": {
    "name": "first last",
    "email": "[email protected]",
    "phone": "0522222222",
    "street1": "address street",
    "city": "dubai",
    "state": "DU",
    "country": "AE",
    "ip": "196.219.145.121"
}

---

Expected Payment Flow Behavior

1. In this endpoint, you already tokenized your card and have the token,but you only check for the status of the token.


2. You only share the required parameters ( profile_id , token )


3. Then, you will receive a response including the card details and the customer details as in the response payload in the previous section.