Skip to main content

Structure of webhooks

General information

Tranzzo uses webhooks to promptly notify you of any changes in payment statuses in real-time.

It's important to note that in specific circumstances (such as network or server-side delays), webhook notifications may be duplicated.

We send webhooks using the POST HTTP method and the following content type: Content-Type:application/x-www-form-urlencoded.

Webhook parameters:

ParameterTypeDescription
dataStringBase64Url-encoded JSON
signatureStringdata signed with ${SECRET_KEY}

Webhook example:

data=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A
signature=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A

Tranzzo uses the following IP addresses to send webhooks:

  • 35.187.74.148
tip

Note: typically we send webhooks to 443 and 8443 ports. However, if you require webhooks to be sent to other ports, please inform Tranzzo Support.

Verification of webhooks

Webhook verification requires forming a signature using the following method: signature=base64url_encode(sha1($API_SECRET + base64url_encode($data) + $API_SECRET))

The sha1 function returns raw bytes rather than a hex-encoded string, and the signature is 28 characters in length.

Signature calculation example:

raw_data='{"name":"Joe","age":20}'       # {"name":"Joe","age":20}
data='eyJuYW1lIjoiSm9lIiwiYWdlIjoyMH0=' # base64url_encode(raw_data)
secret='changeme' # should be changed to ${API_SECRET}

signature='Bcj3hb-h00HrEMIoJ5nPW5ZHlVQ=' # base64url_encode(sha1($secret + $data + secret))

# Bash one-liner:
# 1. calculate sha1 as raw bytes
# 2. encode raw bytes with base64
# 3. replace [+]->[-],[/]->[_]
echo -n 'changemeeyJuYW1lIjoiSm9lIiwiYWdlIjoyMH0=changeme' | \
openssl dgst -binary -sha1 | \
base64 | \
tr '/+' '_-'

Webhooks parameters

Webhooks contain different sets of parameters depending on whether they are primary or secondary operations.

The parameters for webhooks of primary transactions including purchase, auth, credit, p2p, and lookup, are as follows:

ParameterTypeRequiredDescription
payment_idStringUnique Tranzzo payment identifier
order_idStringUnique identifier of order
gateway_order_idStringUnique order identifier in bank acquirer system.
billing_order_idStringUnique Tranzzo billing identifier
transaction_idStringUnique Tranzzo transaction identifier
pos_idStringMerchant's identifier (POS_ID)
modeStringPayment mode
methodStringPayment method
amountNumberTransaction amount
currencyStringTransaction currency
paywayStringOptional payway
eciStringElectronic Commerce Indicator (ECI) - authentication result of credit card payment on 3D Secure
statusStringTransaction status
status_codeStringTranzzo payment status code
status_descriptionStringTranzzo payment status code description
cc_maskStringCard number mask
cc_tokenStringTranzzo card token
cc_token_expirationStringToken expiration timestamp
customer_idStringCustomer identifier in merchant's system
customer_phoneStringCustomer phone
feeObjectAmount and currency of commission
fixed_feeObjectAmount and currency of fixed commission (fee), which constitutes a portion of the total commission (fee)
percent_feeObjectAmount and currency representing the interest commission (fee), which constitutes a portion of the total commission (fee)
created_atStringTimestamp when transaction was created
processed_atStringTimestamp when transaction was updated last time
payloadStringPayment request payload

Here is an example of a webhook for the auth primary transactions:

{
"payment_id": "c4939398-1dad-4b92-1c34-7f6802379180",
"order_id": "111999991",
"gateway_order_id": "6320ac9a-aaaa-4912-adb3-5bca2dd560fe",
"billing_order_id": "123",
"transaction_id": "4f98dc46-ffff-4ba7-a267-286fe7669894",
"pos_id": "6eb070d5-7fbe-1176-9488-c152b60dd346",
"mode": "direct",
"method": "auth",
"amount": 0.28,
"currency": "UAH",
"payway": "privat24",
"eci": "7",
"status": "success",
"status_code": "1000",
"status_description": "Transaction is successful.",
"cc_mask": "424242******4242",
"cc_token": "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
"cc_token_expiration": "2020-10-10T10:10:22",
"customer_id": "123",
"customer_phone": "+380999999999",
"fee": {
"amount": 136,
"currency": "UAH"
},
"percent_fee": {
"amount": 126,
"currency": "UAH"
},
"fixed_fee": {
"amount": 10,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:22.100",
"payload": ""
}

When utilizing certain alternative payment methods, there may be instances where the payer can make partial payments, leading to changeable transaction amounts. In such scenarios, the webhook will also include the following parameters:

ParameterTypeDescription
processed_amountNumberThe amount that was actually paid by the customer and processed by the payment system. It applies to payments where the final payment amount can be changed by the payer.
processed_currencyString(≤256)Actual currency of payment with processed_amount. It applies to payments where the final payment amount can be changed by the payer.

Webhook example for the purchase transaction with changeable amount:

{
"payment_id": "c4939398-1dad-4b92-1c34-7f6802379180",
"order_id": "111999991",
"gateway_order_id": "6320ac9a-aaaa-4912-adb3-5bca2dd560fe",
"billing_order_id": "123",
"transaction_id": "4f98dc46-ffff-4ba7-a267-286fe7669894",
"pos_id": "6eb070d5-7fbe-1176-9488-c152b60dd346",
"mode": "direct",
"method": "purchase",
"amount": 1000,
"currency": "UAH",
"payway": "privat24",
"eci": "7",
"status": "success",
"status_code": "1000",
"status_description": "Transaction is successful.",
"cc_mask": "424242******4242",
"cc_token": "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
"cc_token_expiration": "2020-10-10T10:10:22",
"customer_id": "123",
"customer_phone": "+380999999999",
"fee": {
"amount": 136,
"currency": "UAH"
},
"percent_fee": {
"amount": 126,
"currency": "UAH"
},
"fixed_fee": {
"amount": 10,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:22.100",
"processed_amount": 980,
"processed_currency": "UAH",
"payload": ""
}

The parameters of webhooks for secondary transactions vary based on the transaction type.

The parameters for webhooks of a Capture transaction are as follows:

ParameterTypeRequiredDescription
operation_idStringUnique Tranzzo capture identifier
payment_idStringTranzzo payment identifier of primary operation
order_idStringMerchant's order_id of primary operation
transaction_idStringUnique Tranzzo transaction identifier
pos_idStringMerchant's identifier (POS_ID)
modeStringdirect
methodStringcapture
amountNumberActual capture amount
currencyStringTransaction currency
statusStringTransaction status
status_codeStringTranzzo payment status code
status_descriptionStringTranzzo payment status code description
feeObjectAmount and currency of commission
created_atStringTimestamp when transaction was created
processed_atStringTimestamp when transaction was updated last time

Example:

{
"operation_id": "edf7605c-99a8-43be-a1a5-2e96ebac8512",
"payment_id": "c4939398-1dad-4b92-1c34-7f6802379180",
"order_id": "123",
"transaction_id": "4f98dc46-ffff-4ba7-a267-286fe7669894",
"pos_id": "6eb070d5-7fbe-1176-9488-c152b60dd346",
"mode": "direct",
"method": "capture",
"amount": 100,
"currency": "UAH",
"status": "success",
"status_code": "1000",
"status_description": "Transaction is successful.",
"fee": {
"amount": 1.0,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:12.000"
}

The parameters for webhooks of a Void transaction are as follows:

ParameterTypeRequiredDescription
operation_idStringUnique Tranzzo void identifier
payment_idStringTranzzo payment identifier of primary operation
order_idStringMerchant's order_id of primary operation
transaction_idStringUnique Tranzzo transaction identifier
pos_idStringMerchant's identifier (POS_ID)
modeStringdirect
methodStringvoid
amountNumberActual void amount
currencyStringTransaction currency
statusStringTransaction status
status_codeStringTranzzo payment status code
status_descriptionStringTranzzo payment status code description
feeObjectAmount and currency of commission
created_atStringTimestamp when transaction was created
processed_atStringTimestamp when transaction was updated last time

Example:

{
"operation_id": "edf7605c-99a8-43be-a1a5-2e96ebac8512",
"payment_id": "c4939398-1dad-4b92-1c34-7f6802379180",
"order_id": "123",
"transaction_id": "4f98dc46-ffff-4ba7-a267-286fe7669894",
"pos_id": "6eb070d5-7fbe-1176-9488-c152b60dd346",
"mode": "direct",
"method": "void",
"amount": 100,
"currency": "UAH",
"status": "success",
"status_code": "1000",
"status_description": "Transaction is successful.",
"fee": {
"amount": 1.0,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:12.000"
}

The parameters for webhooks of a refund transaction are as follows:

ParameterTypeRequiredDescription
operation_idStringUnique Tranzzo refund identifier
payment_idStringTranzzo payment identifier of primary operation
order_idStringMerchant's order_id of primary operation
transaction_idStringUnique Tranzzo transaction identifier
pos_idStringMerchant's identifier (POS_ID)
modeStringdirect
methodStringrefund
amountNumberActual refund amount
currencyStringTransaction currency
statusStringTransaction status
status_codeStringTranzzo payment status code
status_descriptionStringTranzzo payment status code description
feeObjectAmount and currency of commission
created_atStringTimestamp when transaction was created
processed_atStringTimestamp when transaction was updated last time

Example:

{
"operation_id": "edf7605c-99a8-43be-a1a5-2e96ebac8512",
"payment_id": "c4939398-1dad-4b92-1c34-7f6802379180",
"order_id": "123",
"transaction_id": "4f98dc46-ffff-4ba7-a267-286fe7669894",
"pos_id": "6eb070d5-7fbe-1176-9488-c152b60dd346",
"mode": "direct",
"method": "refund",
"amount": 100,
"currency": "UAH",
"status": "success",
"status_code": "1000",
"status_description": "Transaction is successful.",
"fee": {
"amount": 1.0,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:12.000"
}

Re-sending webhooks for operations

Receiving a webhook notification multiple times for a specific transaction can be done by sending a request using the GET HTTP method.

Request parameters:

ParameterTypeRequiredDescription
POS_IDUUIDMerchant's identifier (POS_ID)
ORDER_IDStringMerchant's order identifier
OPERATIONStringPayment method, e.g. purchase, void, etc.

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/pos/${POS_ID}/orders/${ORDER_ID}/${OPERATION}?callback=true" \
-H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
-H "X-API-KEY: ${ENDPOINTS_KEY}"

Query parameters:

ParameterTypeRequiredDescription
callbackBooleantrue
info

It's important to note that webhooks may include additional information beyond the parameters listed above. If you need to configure the transmission of these additional parameters or learn about what they are, please contact Tranzzo Support.

Re-sending webhooks for recurring payments

To receive a repeated webhook for recurring payments, send a GET request to the /api/v1/pos/:posId/orders/:orderId/purchase?callback=true&transactionId=:paymentId endpoint, where the posId is an ID of merchant’s project, the orderId is an order ID, and the transactionId is an ID of a specific transaction.

Request example:

curl "https://cpay.tranzzo.com/api/v1/pos/${POS_ID}/orders/${ORDER_ID}/purchase?callback=true" \
-H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
-H "X-API-KEY: ${ENDPOINTS_KEY}"

Optional query parameters:

ParameterTypeRequiredDescription
callbackBooleantrue
transactionIdStringAn identifier for one of the transactions within the corresponding recurring payment

If the request lacks the transactionId query parameter, the response will provide information on the latest transaction associated with the corresponding subscription.

Request example for specific transaction:

curl "https://cpay.tranzzo.com/api/v1/pos/${POS_ID}/orders/${ORDER_ID}/purchase?callback=true&transactionId=${TRANSACTION_ID}" \
-H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
-H "X-API-KEY: ${ENDPOINTS_KEY}"

Response example:

{
"payment_id": "c4939398-1dad-4b92-1c34-7f6802379180",
"order_id": "111999991",
"gateway_order_id": "6320ac9a-aaaa-4912-adb3-5bca2dd560fe",
"billing_order_id": "123",
"transaction_id": "4f98dc46-ffff-4ba7-a267-286fe7669894",
"pos_id": "6eb070d5-7fbe-1176-9488-c152b60dd346",
"mode": "direct",
"method": "auth",
"amount": 0.28,
"currency": "UAH",
"payway": "privat24",
"eci": "7",
"status": "success",
"status_code": "1000",
"status_description": "Transaction is successful.",
"cc_mask": "424242******4242",
"cc_token": "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
"cc_token_expiration": "2020-10-10T10:10:22",
"customer_id": "123",
"customer_phone": "+380999999999",
"fee": {
"amount": 1.0,
"currency": "UAH"
},
"created_at": "2018-10-10T10:10:10.100",
"processed_at": "2018-10-10T10:10:22.100",
"payload": "",
"recurring": {
"id": "n9W9kyytX2q62jBg7fu7V",
"status": "active"
}
}