Skip to main content

Callback Notification

Checkout service sends the callback on the merchant notification_URL as a result of an operation.

Content Type:    application/x-www-form-urlencoded
Method:          POST
caution

With all Payment Platform POST requests at Callback Notification URL, merchant must return

  • the HTTP Status Code "200 - OK" in case of notification successfully received OR
  • string "ERROR".

Merchant can receive the callback for the below operation types:

  • SALE
  • 3DS
  • REDIRECT
  • REFUND
  • VOID
  • RECURRING
  • CHARGEBACK
Notification Frequency
  • Real Time - right after transaction is completed
  • After 15 minutes of transaction completion if TESS did not receive 200 - OK for 1st attempt
  • After 30 minutes of transaction completion if TESS did not receive 200 - OK for 2nd attempt
  • After 45 minutes of transaction completion if TESS received 200 - OK for 3rd attempt

Possible Transaction Statuses​

StatusOperation typeDescription
SUCCESSsale, 3ds, redirect, refund, void, recurring, chargebackTransaction is successfully completed in Payment Platform
FAILsale, refund, void, recurringTransaction has the errors and is not validated by Payment Platform
WAITINGsale, refund, void, recurringTransaction is being processed by Payment Platform
danger

The successful transaction does not mean successful final status for payment.

Example:

  • Payment is not completed if transaction has status = success and type = redirect/waiting/3ds etc.
  • Payment is successfully completed if transaction has status = success and type = sale.

Callback parameters​

Callback includes the following data:

ParameterTypeMandatory, LimitationsDescription
idStringRequiredTransaction ID
Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
order_numberStringRequired Up to 255 charactersOrder ID
Example: order-1234
order_amountFloatRequired Format: XX.XX, without leading zeroesProduct price
Example: 0.19
order_currencyStringRequired Up to 3 charactersCurrency (3-characters code)
Example: QAR
order_descriptionStringRequired Up to 1024 charactersProduct description
Example: Important gift
typeStringRequired Up to 36 charactersOperation type: sale, 3ds, redirect, refund, void, chargeback
Example: sale
statusStringRequired Up to 20 charactersTransaction status: success, fail, waiting
Example: success
reasonStringOptional Up to 1024 charactersDecline or error reason (for "sale" and "refund" operation types only). It displays only if the transaction has FAIL status
Example: The operation was rejected. Please contact the site support
rrnStringOptionalRetrieval Reference Number value from the acquirer system
approval_codeStringOptionalApproval code value from the acquirer system
cardStringOptional
Format: ХХХХХХ****ХХХХ		Card number mask
Example: 411111******1111
card_expiration_dateStringOptionalCard expiration date
Example: 12/2022
card_tokenStringOptionalCard token. It is available if the parameter req_token was enabled
Example: VjFRaUxDSmhiR2NpT2lKU1V6STFO
customer_nameStringOptionalCustomer's first and last name
Example: John Rickher
customer_emailStringOptional Format: example@mail.comCustomer's email address
Example: fdfd@dfsds.ds
customer_countryStringOptional Up to 3 charactersCustomer's country
Example: US
customer_stateStringOptional Up to 32 charactersCustomer's state
Example: California
customer_cityStringOptionalCustomer's city
Example: Los Angeles
customer_addressStringOptional Up to 32 charactersCustomer's address
Example: 123 Sample Street
customer_ipStringRequiredCustomer's IP
Example: 255.41.45.57
dateDateOptional Format: YYYY-MM-DD hh:mm:ss (UTC+0 Format)Transaction date
Example: 2020-08-05 07:41:10
recurring_init_trans_idStringOptionalReference to the first transaction that initializes the recurring (provided if recurring was initialized)
Example: dc66cdd8-d702-11ea-9a2f-0242c0a87099
recurring_tokenStringOptionalRecurring token (provided if recurring was initialized)
Example: e5f60b35485e
schedule_idStringOptionalIt is available if schedule is used for recurring sale
hashStringRequiredSpecial signature, used to validate callback.
For details, click here

Examples​

Merchant successful sale callback
{
  id=f0a51dfa-fc43-11ec-8128-0242ac120004
  order_number=order-1234
  order_amount=3.01
  order_currency=QAR
  order_description=bloodline
  type=sale
  status=success
  card=411111****1111
  card_expiration_date=12/2022
  schedule_id=4e46866c-f84b-11ec-8b4c-0242ac120007
  recurring_init_trans_id=f0a51dfa-fc43-11ec-8128-0242ac120004
  recurring_token=f0e24964-fc43-11ec-a7e0-0242ac120004
  date=2022-07-05 09:22:09
  hash=6d8d440e25bdfc5288616ce567496948d2562852
  customer_name=D D
  customer_email=success@gmail.com
  customer_country=US
  customer_state=California
  customer_city=Los Angeles
  customer_address=Moor Building 35274 State ST Fremont. U.S.A
  customer_ip=10.10.10.2
}
Merchant successful refund callback
{
  id=f0a51dfa-fc43-11ec-8128-0242ac120004
  order_number=order-1234
  order_amount=3.01
  order_currency=QAR
  order_description=bloodline
  type=refund
  status=success
  card=411111****1111
  card_expiration_date=12/2022
  schedule_id=4e46866c-f84b-11ec-8b4c-0242ac120007
  date=2022-07-05 09:28:01
  hash=6d8d440e25bdfc5288616ce567496948d2562852
  customer_name=D D
  customer_email=success@gmail.com
  customer_country=US
  customer_state=California
  customer_city=Los Angeles
  customer_address=Moor Building 35274 State ST Fremont. U.S.A
  customer_ip=10.10.10.2
}
Merchant unsuccessful sale callback
{
  id=1f34f446-fc45-11ec-a50f-0242ac120004
  order_number=order-1234
  order_amount=3.01
  order_currency=QAR
  order_description=bloodline
  type=sale
  status=fail
  card=411111****1111
  card_expiration_date=12/2022
  reason=Declined by processing.
  date=2022-07-05 09:30:35
  hash=7f15d178e9b2c8507dea57f8ed1efddb9573fa6b
  customer_name=D D
  customer_email=success@gmail.com
  customer_country=US
  customer_state=California
  customer_city=Los Angeles
  customer_address=Moor Building 35274 State ST Fremont. U.S.A
  customer_ip=10.10.10.2
}
Merchant unsuccessful refund callback
{
  id=ba290c62-fc45-11ec-9e91-0242ac120004
  order_number=order-1234
  order_amount=3.01
  order_currency=QAR
  order_description=bloodline
  type=refund
  status=fail
  card=411111****1111
  card_expiration_date=12/2022
  reason=Declined by processing.
  schedule_id=4e46866c-f84b-11ec-8b4c-0242ac120007
  recurring_init_trans_id=ba290c62-fc45-11ec-9e91-0242ac120004
  recurring_token=ba51844e-fc45-11ec-932c-0242ac120004
  date=2022-07-05 09:38:00
  hash=bcd78ff8b8e6b75aa1743910641217be6edc3a43
  customer_name=D D
  customer_email=success@gmail.com
  customer_country=US
  customer_state=California
  customer_city=Los Angeles
  customer_address=Moor Building 35274 State ST Fremont. U.S.A
  customer_ip=10.10.10.2
}