Navbar
curl

Introduction

Welcome to the Tranzzo Payment API!

Through this docs the following variables will be used if format ${VARIABLE_NAME}:

Variable Meaning Example
POS_ID Point Of Sale identifier. Used to uniquely identify merchant in API. dc728de1-51ef-4ef1-80f7-3b44b07b5667
API_KEY Key used to merchant for authorization purposes. 2c2b91a3-9b73-4551-81ac-84e0d0360995
API_SECRET Secret used to merchant for authorization purposes in API and webhooks signing. ktMdTyollYMRkEfvgqbaWmvFiXPy1a80
ENDPOINTS_KEY Endpoints authorization key. Used to access the API. AIzaSyBiVfwG--8qIr4GOGuC2-XYoulwqqAAAAA

See Authentication for details.

Definitions

Term Definition
MCC Merchant Category Code - is a four-digit number listed in ISO 18245 for retail financial services. MCC is used to classify the business by the type of goods or services it provides.
3-D Secure 3-D Secure - is an additional authentication step for online payments.
ECI Electronic Commerce Indicator (ECI) - authentication result of credit card payment on 3D Secure

Available payment operations

Payment modes

Tranzzo defines two options for processing payments, a.k.a. modes:

Primary operations

Depending on merchant business there are different options for accepting payment. a.k.a. methods:

Secondary operations

Secondary operations are bound to primary.

Controlling 3D-Secure flow

3-D Secure could be controlled by order_3ds_bypass parameter in API. Valid parameters are:

API

API URL

In order to test whether host is reachable use https://cpay.tranzzo.com/health endpoint:

$ curl https://cpay.tranzzo.com/health

OK # Expected response

All requests to Tranzzo API should be sent to https://cpay.tranzzo.com host in JSON format.

Authentication

To test whether credentials and headers are correct, use the following request:

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

Expected response

[]

Tranzzo uses HTTP headers for authentication in the following format:

Header field name Value Example
X-API-AUTH CPAY ${API_KEY}:${API_SECRET} X-API-AUTH: CPAY 2c2b91a3-9b73-4551-81ac-84e0d0360995:ktMdTyollYMRkEfvgqbaWmvFiXPy1a80
X-API-KEY ${ENDPOINTS_KEY} X-API-KEY: AIzaSyBiVfwG--8qIr4GOGuC2-XYoulwqqAAAAA

Tranzzo expects these headers in all API requests sent to the server for both GET and POST requests.

Request signing

Requests to Tranzzo could be optionally signed, it is recommended. In this case, header X-API-AUTH should be replace with appropriate signing algorithm. See examples below.

OpenSSL HMAC-SHA1 signing example:

SECRET=changeme # replace with ${API_SECRET}
DATA='{"name":"Joe","age":20}' # replace with raw request
SIGNATURE=$(echo -n "$DATA" | openssl sha1 -hmac "$SECRET")
echo "$SIGNATURE"
# Expected signature
48731878acbb41e6ee70eac5f1e6f8b8031f9484

Recommended way to sign requests is HMAC-SHA1 algorithm. See an example on the right.

Authentication header: X-API-AUTH: CPAY-HMAC ${API_KEY}:${SIGNATURE}

SHA1

OpenSSL SHA1 signing example:

SECRET=changeme # replace with ${API_SECRET}
DATA='{"name":"Joe","age":20}' # replace with raw request
SIGNATURE=$(echo -n "$SECRET$DATA$SECRET" | openssl sha1)
echo "$SIGNATURE"
# Expected signature
8c8a2929897286196bb906216379f84c9ec17573

If merchant's system has no support for HMAC signing, requests could be simply signed with SHA1 algorithm. See an example on the right.

Authentication header: X-API-AUTH: CPAY-SHA1 ${API_KEY}:${SIGNATURE}

Data types

Type name Represented as Values Example
UUID String(36) "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9"
TIMESTAMP String(23) "2020-10-10T10:10:22.100"
MODE String(≤32) direct, hosted Payment modes
METHOD String(≤255) purchase, capture, auth, void Payment methods
URL String(≤2048) https://examle.com/some/path?with=query
IP String(7-45) "8.8.8.8" (IPv4), "FE80::0202:B3FF:FE1E:8329" (IPv6)
GW_ID String(≤1024) 4212523:GssqUUQa
BILLING_ID String(≤1024) 123125124
CURRENCY String(3) "UAH", "USD", "EUR", "RUB"
STATUS String(≤32) "success" (Transaction status)
STATUS_CODE String(4) "1000" (Tranzzo payment status code)
STATUS_DESCRIPTION String(≤1024) "Transaction is successful." (Tranzzo payment status code description)
ECI String(≤2) "7" (ECI)
MCC String(≤5) "3455" (MCC)
CC_NUMBER String(13-20) "4242424242424242"
CC_MASK String(13-20) "424242******4242"
CC_TOKEN String(≤255) "SDJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZq" (Tranzzo tokens)

Products

Example of product entity:

{
  "id": "1",
  "url": "https://example.com/products/tv",
  "category": "TV",
  "name": "Brand new TV",
  "description": "Brand new TV with awesome screen",
  "amount": 6600,
  "currency": "UAH",
  "price_type": "VAT",
  "vat": 6600,
  "qty": 1,
  "payload": "ref_no=1231; discount=false"
}

For each payment you can optionally pass array of products that are being paid for.

Parameter definitions (all parameters are optional):

Parameter Type Description
id String Product identifier in merchant's system
url String Product URL
category String Product category
name String Product name
description String Product description
amount Number Product price (does not influence total payment amount)
currency String Product price currency
price_type String Either VAT or NET
vat Number VAT price for the product
qty Number Product quantity
payload String Field for custom data. Max 4000 symbols.

API statuses

status field can contain the following values:

Status Description
init Transaction was created, but processing has not been started.
pending Transaction is being processed.
success Transaction is successful.
failure Unsuccessful transaction.

Create hosted payment

HTTP method: POST

Request parameters:

Request example:

$ curl -i "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "hosted",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'

Successful response with 303 HTTP status has Location header where customer should be redirected to proceed with payment:

HTTP/2 303
# .. other headers
Location: https://cpay.tranzzo.com/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE hosted
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
order_3ds_bypass String 3-D Secure flow option
products Array[Product] Array of products to be paid, empty array can be specified
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url URL Preflight request will be sent to this URL

Direct payments with card data

HTTP method: POST

Request parameters:

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "4242424242424242",
      "exp_month":        2,
      "exp_year":         24,
      "card_cvv":         "111",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
order_3ds_bypass String 3-D Secure flow option
cc_number CC_NUMBER Card number
exp_month Number Card expiration month field
exp_year Number Card expiration year field
card_cvv String Card CVV
products Array[Product] Array of products to be paid
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for merchant custom data. Max 4000 symbols.
validation_url String Preflight request will be sent to this URL

Response parameters:

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "https://ing.tranzzo.com/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}
Parameter Type Description
payment_id UUID Unique Tranzzo payment identifier
order_id String(≤256) Unique identifier of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique Tranzzo billing identifier
transaction_id UUID Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String(≤2048) Payment description
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description STATUS_DESCRIPTION Tranzzo payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
user_action_url URL If user_action_required is true then user should be redirected to this URL
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
cc_mask CC_MASK Card number mask
cc_token CC_TOKEN Tranzzo card token generated for this card
cc_token_expiration String Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_ip String Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String Field for custom data.

Direct payments using Privat24

HTTP method: POST

Request parameters:

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "payway":           "privat24",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
order_3ds_bypass String 3-D Secure flow option
payway String Optional payway. Use "privat24" for processing direct payments through Privat24
products Array[Product] Array of products to be paid
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for merchant custom data. Max 4000 symbols.
validation_url String Preflight request will be sent to this URL

Response parameters:

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "https://ing.tranzzo.com/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "payway":               "privat24",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}
Parameter Type Description
payment_id UUID Unique Tranzzo payment identifier
order_id String Unique identifier of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique Tranzzo billing identifier
transaction_id UUID Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description STATUS_DESCRIPTION Tranzzo payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
user_action_url URL If user_action_required is true then user should be redirected to this URL
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
payway String Optional payway. Use "privat24" for processing direct payments through Privat24
customer_id String Customer identifier in merchant's system
customer_ip String Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data.

Direct payments using Tranzzo tokens

HTTP method: POST

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_token":         "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'

Request parameters:

Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of order
cc_token CC_TOKEN Tranzzo card token, obtained from previous payments
order_3ds_bypass String 3-D Secure flow option
products Array[Product] Array of products to be paid
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url String Preflight request will be sent to this URL

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "https://ing.tranzzo.com/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}

Response parameters

Parameter Type Description
payment_id UUID Unique Tranzzo payment identifier
order_id String(≤256) Unique identifier of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique Tranzzo billing identifier
transaction_id UUID Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (auth or purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String(≤2048) Payment description
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description STATUS_DESCRIPTION Tranzzo payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
user_action_url URL If user_action_required is true then user should be redirected to this URL
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
cc_mask CC_MASK Card number mask
cc_token CC_TOKEN Tranzzo card token generated for this card
cc_token_expiration TIMESTAMP Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_ip IP Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data.

P2P payments

HTTP method: POST

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":              "${POS_ID}",
      "mode":                "direct",
      "method":              "p2p",
      "amount":              1,
      "currency":            "UAH",
      "description":         "P2P description",
      "order_id":            "123",
      "order_3ds_bypass":    "always",
      "cc_number":           "4242424242424242",
      "exp_month":           2,
      "exp_year":            24,
      "card_cvv":            "111",
      "recipient_cc_number": "5555555555554444",
      "server_url":          "https://callback.blackhole.com/callback",
      "result_url":          "https://example.com/result",
      "payload":             "sale=true"
    }'

Request parameters:

Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD p2p
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of transfer
cc_number CC_NUMBER Card number
exp_month Number Card expiration month field
exp_year Number Card expiration year field
card_cvv String Card CVV
recipient_cc_number String Recipient's card number
order_3ds_bypass String 3-D Secure flow option
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url URL Preflight request will be sent to this URL

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "p2p",
  "amount":               1,
  "currency":             "UAH",
  "description":          "P2P description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "https://ing.tranzzo.com/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}

Response parameters

Parameter Type Description
payment_id UUID Unique Tranzzo payment identifier
order_id String(≤256) Unique identifier of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique Tranzzo billing identifier
transaction_id UUID Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD p2p
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String(≤2048) Payment description
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description String Tranzzo payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
user_action_url URL If user_action_required is true then user should be redirected to this URL
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
cc_mask CC_MASK Card number mask
cc_token CC_TOKEN Tranzzo card token generated for this card
cc_token_expiration TIMESTAMP Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_ip IP Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data.

P2P payments using Tranzzo tokens

HTTP method: POST

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":              "${POS_ID}",
      "mode":                "direct",
      "method":              "p2p",
      "amount":              1,
      "currency":            "UAH",
      "description":         "P2P description",
      "order_id":            "123",
      "order_3ds_bypass":    "always",
      "cc_token":            "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "recipient_cc_number": "5555555555554444",
      "server_url":          "https://callback.blackhole.com/callback",
      "result_url":          "https://example.com/result",
      "payload":             "sale=true"
    }'

Request parameters:

Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD p2p
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of transfer
cc_token CC_TOKEN Tranzzo card token, obtained from previous payments
recipient_cc_number String Recipient's card number
order_3ds_bypass String 3-D Secure flow option
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url URL Preflight request will be sent to this URL

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "p2p",
  "amount":               1,
  "currency":             "UAH",
  "description":          "P2P description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "https://ing.tranzzo.com/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}

Response parameters

Parameter Type Description
payment_id UUID Unique Tranzzo payment identifier
order_id String(≤256) Unique identifier of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique Tranzzo billing identifier
transaction_id UUID Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode Mode direct
method Method p2p
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String(≤2048) Payment description
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description STATUS_DESCRIPTION Tranzzo payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
user_action_url URL If user_action_required is true then user should be redirected to this URL
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
cc_mask CC_MASK Card number mask
cc_token CC_TOKEN Tranzzo card token generated for this card
cc_token_expiration TIMESTAMP Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_ip String Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url String Customer will be redirected to this URL after payment.
created_at String Timestamp when transaction was created
processing_time String Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data.

Credit payments

HTTP method: POST

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":              "${POS_ID}",
      "mode":                "direct",
      "method":              "credit",
      "amount":              1,
      "currency":            "UAH",
      "description":         "Credit description",
      "order_id":            "123",
      "order_3ds_bypass":    "always",
      "cc_number":           "4242424242424242",
      "server_url":          "https://callback.blackhole.com/callback",
      "result_url":          "https://example.com/result",
      "payload":             "sale=true"
    }'

Request parameters:

Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD credit
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of transfer
cc_number CC_NUMBER Recipient's card number
order_3ds_bypass String 3-D Secure flow option
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url URL Preflight request will be sent to this URL

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "credit",
  "amount":               1,
  "currency":             "UAH",
  "description":          "P2P description",
  "status":               "success",
  "status_code":          "1000",
  "status_description":   "Transaction is successful.",
  "user_action_required": false,
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}

Response parameters

Parameter Type Description
payment_id UUID Unique Tranzzo payment identifier
order_id String(≤256) Unique identifier of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique Tranzzo billing identifier
transaction_id UUID Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD credit
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String(≤2048) Payment description
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description String Tranzzo payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
cc_mask CC_MASK Card number mask
cc_token CC_TOKEN Tranzzo card token generated for this card
cc_token_expiration TIMESTAMP Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_ip IP Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url URL Customer will be redirected to this URL after payment.
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data.

Credit payments using Tranzzo tokens

HTTP method: POST

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":              "${POS_ID}",
      "mode":                "direct",
      "method":              "credit",
      "amount":              1,
      "currency":            "UAH",
      "description":         "Credit description",
      "order_id":            "123",
      "order_3ds_bypass":    "always",
      "cc_token":            "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "server_url":          "https://callback.blackhole.com/callback",
      "result_url":          "https://example.com/result",
      "payload":             "sale=true"
    }'

Request parameters:

Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD credit
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identified of transfer
cc_token CC_TOKEN Tranzzo card token, obtained from previous payments
order_3ds_bypass String 3-D Secure flow option
customer_id String Customer identifier in merchant's system
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_ip String Customer IP address
customer_country String Customer country
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
merchant_mcc MCC MCC for this transaction
payload String Field for custom data. Max 4000 symbols.
validation_url URL Preflight request will be sent to this URL

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "credit",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Credit description",
  "status":               "success",
  "status_code":          "1000",
  "status_description":   "Transaction is successful.",
  "user_action_required": false,
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true"
}

Response parameters

Parameter Type Description
payment_id UUID Unique Tranzzo payment identifier
order_id String(≤256) Unique identifier of order
gateway_order_id GW_ID Unique order identifier in bank acquirer system.
billing_order_id BILLING_ID Unique Tranzzo billing identifier
transaction_id UUID Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode Mode direct
method Method credit
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String(≤2048) Payment description
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description STATUS_DESCRIPTION Tranzzo payment status code description
user_action_required Boolean Either customer action is required to proceed with payment
eci ECI Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc MCC MCC for this transaction
options_3ds String 3-D Secure flow option
cc_mask CC_MASK Card number mask
cc_token CC_TOKEN Tranzzo card token generated for this card
cc_token_expiration TIMESTAMP Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_ip String Customer IP address
customer_fname String Customer first name
customer_lname String Customer last name
customer_email String Customer email
customer_phone String Customer phone
customer_country String Customer country
result_url String Customer will be redirected to this URL after payment.
created_at String Timestamp when transaction was created
processing_time String Timestamp when transaction was updated last time
payload String(≤4096) Field for custom data.

Capture

HTTP method: POST

Request parameters:

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/capture" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
order_id String Merchant's order identifier to be captured (max length is 32 characters)
order_currency CURRENCY Currency of original order
server_url URL Webhook notification will be sent to this URL

Response parameters:

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000"
}
Parameter Type Description
operation_id UUID Unique Tranzzo capture identifier
payment_id UUID Tranzzo payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD capture
amount Number Actual captured amount
currency CURRENCY Transaction currency
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description STATUS_DESCRIPTION Tranzzo payment status code description
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time

Partial capture

HTTP method: POST

Request parameters:

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/capture" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "charge_amount":  80,
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
order_id String Merchant's order identifier to be captured (max length is 32 characters)
order_currency CURRENCY Currency of original order
charge_amount Number Optional amount to be captured
server_url URL Webhook notification will be sent to this URL

Response parameters:

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000"
}
Parameter Type Description
operation_id UUID Unique Tranzzo capture identifier
payment_id UUID Tranzzo payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD capture
amount Number Actual captured amount
currency CURRENCY Transaction currency
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description STATUS_DESCRIPTION Tranzzo payment status code description
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time

Void

HTTP method: POST

Request parameters:

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/void" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
order_id String Merchant's order identifier to be captured (max length is 32 characters)
order_currency CURRENCY Currency of original order
server_url URL Webhook notification will be sent to this URL

Response parameters:

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "void",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1009",
  "status_description":  "Reverse successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000"
}
Parameter Type Description
operation_id UUID Unique Tranzzo void identifier
payment_id UUID Tranzzo payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD void
amount Number Actual void amount
currency CURRENCY Transaction currency
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description STATUS_DESCRIPTION Tranzzo payment status code description
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time

Refund

HTTP method: POST

Request parameters:

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/refund" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
order_id String Merchant's order identifier to be captured (max length is 32 characters)
order_currency CURRENCY Currency of original order
server_url URL Webhook notification will be sent to this URL

Response parameters:

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000"
}
Parameter Type Description
operation_id UUID Unique Tranzzo refund identifier
payment_id UUID Tranzzo payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD refund
amount Number Actual refund amount
currency CURRENCY Transaction currency
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description STATUS_DESCRIPTION Tranzzo payment status code description
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time

Partial refund

HTTP method: POST

Request parameters:

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/refund" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":         "${POS_ID}",
      "order_id":       "123",
      "order_currency": "UAH",
      "refund_amount":  80,
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
order_id String Merchant's order identifier to be captured (max length is 32 characters)
order_currency CURRENCY Currency of original order
refund_amount Number Amount to be refunded
server_url URL Webhook notification will be sent to this URL

Response parameters:

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000"
}
Parameter Type Description
operation_id UUID Unique Tranzzo refund identifier
payment_id UUID Tranzzo payment identifier of primary operation
order_id String Merchant's order_id of primary operation (max length is 32 characters)
transaction_id UUID Unique Tranzzo transaction identifier
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD refund
amount Number Actual refund amount
currency CURRENCY Transaction currency
status STATUS Transaction status
status_code STATUS_CODE Tranzzo payment status code
status_description STATUS_DESCRIPTION Tranzzo payment status code description
created_at TIMESTAMP Timestamp when transaction was created
processing_time TIMESTAMP Timestamp when transaction was updated last time

Get order transactions

Request example:

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

Returns all transactions that are associated with order.

HTTP method: GET

Path parameters:

Parameter Type Required Description
POS_ID String Merchant's identifier (POS_ID)
ORDER_ID String Merchant's order identifier

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",
    "created_at":          "2018-10-10T10:10:10.100",
    "processing_time":     "2018-10-10T10:10:22.100",
    "payload":             ""
  },
  {
    "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.",
    "created_at":          "2018-10-10T10:11:11.100",
    "processing_time":     "2018-10-10T10:11:12.000"
  }
]

Response structure:

Response contains an Array of transactions associated with merchant's order_id.

Get transactions for period

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/pos/${POS_ID}/transactions?startDate=${startDate}&enddate=${enddate}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Returns all transactions for specified period.

HTTP method: GET

Path parameters:

Parameter Type Required Description
POS_ID UUID Merchant's identifier (POS_ID)

Query parameters:

Parameter Type Required Description
startDate Number Time from - UNIX timestamp
enddate Number Time to - UNIX timestamp

Response contains an Array of transactions for specified period.

Payment operation info

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

Returns specific operation for this ${ORDER_ID}.

HTTP method: GET

Parameter Type Required Description
POS_ID UUID Merchant's identifier (POS_ID)
ORDER_ID String Merchant's order identifier
OPERATION String Payment method, e.g. purchase, void, etc.

Resend webhook for operation

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}"

Returns specific operation for this ${ORDER_ID} and sends webhook to server_url specified in request.

HTTP method: GET

Parameter Type Required Description
POS_ID UUID Merchant's identifier (POS_ID)
ORDER_ID String Merchant's order identifier
OPERATION String Payment method, e.g. purchase, void, etc.

Query parameters:

Parameter Type Required Description
callback Boolean true

Payload

Example of Base64-encoded payload

{
  "...": "...",
  "payload": "eyJ0aGlzIGlzIjogInBhc2hhbG9jaGthIn0K"
}

Most of requests have optional payload field. It can contain custom merchant data. Maximum length to be passed is 4,000 symbols.

If you would like to store structured data, like JSON or XML, simply encode it with Base64 to avoid JSON-specific symbols in body.

Integration Checklist

GENERAL

HOSTED METHOD

DIRECT METHOD

CALLBACKS/WEBHOOKS

Preflight requests

Preflight request - is a special requests that is sent right before primary transaction processing. For example, it could be used to ensure that goods are available on payment submission.

Format of Preflight request is the same as in webhooks.

Typical flow:

  1. Merchant creates hosted payment
  2. User is redirected to Checkout page
  3. User submits card data
  4. Tranzzo sends Preflight request to validation_url if it was defined
  5. If endpoint responses with 200 OK and content is PROCEED, then Tranzzo starts the transaction. Otherwise, payment is cancelled and webhook with failure status is sent to server_url

Webhooks

Tranzzo has an option to notify merchant with every payment status update.

Webhook structure

Example of webhook

data=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A
signature=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A

Webhook is sent with POST HTTP method with Content-Type: application/x-www-form-urlencoded (form data)

Form parameters:

Parameter Type Description
data String Base64Url-encoded JSON
signature String data signed with ${SECRET_KEY}

Webhook source IP

Tranzzo sends webhooks to merchant from the following IP addresses:

Webhook verification

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 '_-' '/+'                   

Signature calculation algorithm: signature=base64url_encode(sha1($API_SECRET + base64url_encode($data) + $API_SECRET))

Signature length: 28 characters

Primary operation webhook parameters

Primary operation webhook structure

{
  "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",
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":     "2018-10-10T10:10:22.100",
  "payload":             ""
}
Parameter Type Required Description
payment_id String Unique Tranzzo payment identifier
order_id String Unique identifier of order
gateway_order_id String Unique order identifier in bank acquirer system.
billing_order_id String Unique Tranzzo billing identifier
transaction_id String Unique Tranzzo transaction identifier
pos_id String Merchant's identifier (POS_ID)
mode String Payment mode
method String Payment method
amount Number Transaction amount
currency String Transaction currency
payway String Optional payway
eci String Electronic Commerce Indicator (ECI) - authentication result of credit card payment on 3D Secure
status String Transaction status
status_code String Tranzzo payment status code
status_description String Tranzzo payment status code description
cc_mask String Card number mask
cc_token String Tranzzo card token
cc_token_expiration String Token expiration timestamp
customer_id String Customer identifier in merchant's system
customer_phone String Customer phone
created_at String Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time
payload String Payment request payload

Secondary operation webhook parameters

Capture webhook

Capture webhook structure:

{
  "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.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000"
}

Capture webhook parameters:

Parameter Type Required Description
operation_id String Unique Tranzzo capture identifier
payment_id String Tranzzo payment identifier of primary operation
order_id String Merchant's order_id of primary operation
transaction_id String Unique Tranzzo transaction identifier
pos_id String Merchant's identifier (POS_ID)
mode String direct
method String capture
amount Number Actual capture amount
currency String Transaction currency
status String Transaction status
status_code String Tranzzo payment status code
status_description String Tranzzo payment status code description
created_at String Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time

Void webhook

Void webhook structure:

{
  "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.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000"
}

Void webhook parameters:

Parameter Type Required Description
operation_id String Unique Tranzzo void identifier
payment_id String Tranzzo payment identifier of primary operation
order_id String Merchant's order_id of primary operation
transaction_id String Unique Tranzzo transaction identifier
pos_id String Merchant's identifier (POS_ID)
mode String direct
method String void
amount Number Actual void amount
currency String Transaction currency
status String Transaction status
status_code String Tranzzo payment status code
status_description String Tranzzo payment status code description
created_at String Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time

Refund webhook

Refund webhook structure:

{
  "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.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000"
}

Refund webhook parameters:

Parameter Type Required Description
operation_id String Unique Tranzzo refund identifier
payment_id String Tranzzo payment identifier of primary operation
order_id String Merchant's order_id of primary operation
transaction_id String Unique Tranzzo transaction identifier
pos_id String Merchant's identifier (POS_ID)
mode String direct
method String refund
amount Number Actual refund amount
currency String Transaction currency
status String Transaction status
status_code String Tranzzo payment status code
status_description String Tranzzo payment status code description
created_at String Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time

Tranzzo card tokens

Tranzzo card token - is a special random string that could be used in card payments. Mostly used for recurring payments. Merchant is not required to be PCI-DSS compliant in order to use Tranzzo card tokens.

Use tokens to implement recurring payments.

Status codes

Tranzzo uses special codes in order to unify gateway transaction statuses.

Successful codes

Code Status Description
0 success Test transaction
1000 success Transaction successful
1001 success Transaction is successful, it will be transferred in daily settlement
1002 success Protected transaction. Charging is successful, waiting for receipt of goods confirmation
1003 success Funds are reserved to make a refund according to a refund request
1004 success Refund successful
1005 success Subscription successful
1006 success Unsubscribed successfully
1007 success Amount was successfully blocked on the sender's account
1009 success Reverse successful

Pending codes

Code Status Description
1008 pending Amount is charged successfully but the store is still not verified. Store need to be activated within 90 days, otherwise transaction will be automatically cancelled.
2000 pending Pending
2001 pending Pending
2002 pending Pending
2010 pending Capture required
2100 pending 3DS verification is required to finish the transaction.
2101 pending CVV is required
2102 pending OTP confirmation is required. OTP is sent to a customer phone number.
2103 pending Receiver info required
2104 pending Sender info required
2105 pending Missed payout method data
2106 pending Waiting for verification via captcha
2107 pending Waiting for verification via IVR call
2108 pending Waiting for verification via Privat24
2109 pending Waiting for customer's phone number verification
2110 pending Waiting for customer's pin-code verification
2111 pending Waiting for verification via SENDER app
2112 pending Waiting for verification via QR code
2113 pending Waiting for transaction verification via Privat24/SENDER application
2114 pending Waiting for transaction complete in Privat24
2115 pending Waiting for transaction complete in MasterPass
2116 pending Waiting for cash transaction at Self-Service Machine
2119 pending Transaction is processing
2120 pending Authorization required
4018 pending PIN tries exceeded. Capture is required.
4019 pending Card expired
4100 pending User not found
4101 pending Failed to send sms
4102 pending Wrong sms password
6000 pending Transaction is on antifraud check

Failure codes

Code Status Description
2003 failure Wrong PIN
2004 failure Wrong amount
2005 failure Wrong authorization code
2006 failure Wrong CAVV
2007 failure Wrong CVV2
2008 failure Internal error. Please try again.
2009 failure Wrong account number
2121 failure Card verification is required.
4000 failure Invalid data. Missed required input fields
4001 failure Payment card expired
4002 failure Incorrect refund sum or currency
4003 failure Payment card has invalid status
4004 failure Wrong data used at Info input.
4005 failure Internal error
4006 failure Internal error
4007 failure Internal error. Please try again.
4008 failure Wrong card number
4009 failure Insufficient funds
4010 failure Transaction limit exceeded. Try another card.
4011 failure Internal error
4012 failure Transaction amount limit exceeded. Try another card.
4013 failure Internal error
4014 failure Internal error
4015 failure Internal error
4016 failure Internal error
4017 failure Internal error
4020 failure Payment card has constraints
4103 failure Card not found in wallet for receiving payments.
4104 failure This card payment system is not supported. Please enter another card.
4105 failure Invalid card type.
4106 failure This country is not supported. Please enter another card.
4107 failure Amount of transaction is more or less than the limit.
4108 failure Amount of transaction is more or less than the limit.
4109 failure Transaction amount limit is exceeded.
4110 failure Please, enter sender's another card.
4111 failure No discount found for the transaction.
4112 failure Failed to load the wallet.
4113 failure Invalid verification code.
4114 failure Additional information is pending. Please, try later.
4115 failure Split amount is not equal to transaction amount.
4116 failure Transaction is not recurring.
4117 failure Transaction currency does not match with debit currency.
4118 failure Capture amount cannot be more than the transaction amount.
4119 failure Such order_id already exists in the system.
4120 failure Parameter is empty.
4121 failure Phone parameter is empty.
4122 failure Parameter is not transferred.
4123 failure Invalid parameter.
4124 failure Invalid currency. Please use: USD, UAH, RUB, EUR.
4125 failure Invalid phone number.
4126 failure Invalid card number.
4127 failure Card bin is not found.
4128 failure Currency exchange rate is not found.
4129 failure Invalid recipient name.
4130 failure Daily card usage limit reached.
4131 failure Such order_id already exists in the system.
4132 failure Transaction for this country are forbidden.
4133 failure Expired card.
4134 failure Invalid card number
4135 failure Card does not support such transaction type.
4136 failure Card does not support such transaction type.
4137 failure Insufficient funds.
4138 failure Transaction amount limit is exceeded.
4139 failure Invalid transaction amount.
4140 failure Transaction is declined. Please check if the card details are correct.
4141 failure OTP confirmation timeout
4142 failure Transaction amount limit is exceeded.
4143 failure Transaction amount limit is exceeded.
4144 failure Invalid card data
4145 failure Privat24 confirmation timeout
4146 failure SenderApp confirmation timeout
4147 failure 3-D Secure verification timeout
5000 failure Invalid operation
5001 failure The transaction has incorrect attributes or this operation is prohibited.
5002 failure Payment rejected. Please contact support.
5003 failure Internal error
5004 failure Transaction is not supported by provider
5005 failure Internal error
5009 failure Internal error
5010 failure Internal error
5014 failure Authorization error. Please contact support.
5015 failure Internal error
5019 failure Internal error
5020 failure Internal error
5021 failure Authorization error. Contact issuer bank
5022 failure This card type is not supported
5023 failure Timeout
5024 failure Internal error
5025 failure Internal error
5026 failure Internal error
5027 failure Internal error
5028 failure Internal error
5029 failure Transaction is not supported. Please contact customer support service
5030 failure Internal error
5102 failure Transaction cache data timeout
5103 failure Store is blocked
5104 failure Store is not active
5105 failure Wrong request signature
5106 failure Order_id is empty
5107 failure You are not the agent of the specified store
5108 failure User doesn't have a card with such token.
5109 failure Invalid request url.
5110 failure Transaction cannot be processed
5111 failure Receiver didn't set the card to receive transactions.
5112 failure Invalid transaction status.
5113 failure Public_key is not found.
5114 failure Transaction is not found.
5115 failure Access error
5116 failure Access to account is blocked.
5117 failure Terminal is not found.
5118 failure Fee is not found.
5119 failure Failed to create transaction.
5120 failure Failed to verify a card.
5121 failure Currency is prohibited.
5122 failure Failed to finish the transaction.
5123 failure Failed to finish the transaction
5124 failure Invalid transaction type.
5125 failure Transaction currency is prohibited.
5126 failure Invalid transaction request signature.
5127 failure Action parameter is not sent in request.
5128 failure Callback parameter is not transferred.
5129 failure This merchant is restricted to call API from this IP.
5130 failure Card does not support 3-D Secure.
5131 failure General error during processing.
5132 failure Token doesn't belong to this merchant.
5133 failure Received token is inactive.
5134 failure Token reached the maximum purchase amount.
5135 failure Token transactions' limit exceeded.
5136 failure Card not supported.
5137 failure Merchant is not allowed preauth.
5138 failure Acquirer does not support 3-D Secure.
5139 failure This token does not exist.
5140 failure Reached the limit of attempts for this IP.
5141 failure Session expired.
5142 failure Card branch is blocked.
5143 failure Card branch daily limit reached.
5144 failure Temporarily closed the P2P transactions from PB cards to foreign banks' cards.
5145 failure Completion limit reached.
5146 failure Transaction is declined. Please, try again later.
5147 failure Transaction is declined. Bank did not approve the transaction. Please, contact the bank.
5148 failure Bank did not approve the transaction. Please, contact the bank.
5149 failure Invalid parameters or transaction is not allowed.
5150 failure Merchant is not allowed for making recurring transactions.
5151 failure Transaction is canceled by payer.
5152 failure Authorization error. Contact issuer bank.
5156 failure ACS Service Unavailable.
6003 failure The transaction is declined by bank's anti-fraud system.
6001 failure The limit for the amount or number of customer payments has been exceeded. Amount or transaction limit has been exceeded.
6002 failure The transaction is rejected by bank's anti-fraud rules.
6004 failure Payment card is lost or stolen

Init codes

Code Status Description
2117 init Invoice is created successfully, waiting for a transaction.
2118 init Transaction is created successfully, waiting for sender to complete.

Error handling

HTTP statuses

Status Description Hint
400 Bad Request Request is invalid.
401 Unauthorized Either POS_ID, API_KEY, API_SECRET or ENDPOINTS_KEY is invalid.
404 Not Found Payment or endpoint not found.
405 Method Not Allowed Usage of request HTTP method is not allowed.
406 Not Acceptable All POST requests should have application/json content type.
429 Too Many Requests Too high request rate.
500 Internal Server Error Internal error occurred on Tranzzo side. Please, contact technical support with specified request and response.
503 Service Unavailable Tranzzo server was unreachable. Please, contact technical support with specified request and response.

Client-side errors (4XX HTTP statuses)

Example of response body returned in case of unsuccessful HTTP status:

{
  "message": "Invalid pos_id field or credentials",
  "args": {
    "code": "S-403"
  }
}

Example of response body for unsuccessful requests due to technical or configuration issues.

Field Type Required
message String(512)
args JSON
args.code String(16)

Server-side errors (5XX HTTP statuses)

For 5XX statuses there is an extra "error_id" field:

{
  "message": "Internal error occurred",
  "args": {
    "error_id": "NYdKYdA4Zv3iOJSw"
  }
}

If you faced 5XX error, please contact Tranzzo technical support.

Field Type Required
message String(512)
args Object
args.error_id String(16)

FAQ on errors returned from Tranzzo API:

Error message Hints
API key not valid. Please pass a valid API key. Check ENDPOINTS_KEY value
Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API. Check if header X-API-KEY was passed

CMS plugins

Available plugins

CMS Plugin
Magento magento-plugin
OpenCart wordpress-plugin
WordPress drupal-plugin
Joomla joomla-plugin
1C Bitrix bitrix-plugin

Contact maintainers

If you found a type or some information is missing in this documentation feel free to contact API maintainers

Google Pay

Google Pay™ Integration Guide

About Google Pay

Google Pay is a fast and simple payment method that allows you to make card payments without entering card details for each payment. The card data is safely stored by Google. This payment method is available for all devices (mobile phones and computers), regardless of the operating system and web browser.

Tranzzo gives you a way to easily add it on your checkout page, making it more convenient for your clients to pay on your website.

As a merchant, you can use one of two ways, available at Tranzzo, to incorporate Google Pay into your payment page:

Integration

Integration via Tranzzo checkout page

Before you start

Instruction

This is the easiest way to add Google Pay payment to your payment options - you don’t have to make significant changes to your website or use heavy coding to process payments. Also, you as a merchant don’t have to be PCI DSS compliant - we at Tranzzo have got you covered on this.

You just need to use hosted payment option Tranzzo offers, in order to redirect your clients to Tranzzo payment page. Instruction on configuring correct request for this method is specified at Tranzzo documentation page. In this case Google Pay button will be displayed at Tranzzo checkout.

Connection with Google Pay API

Before you start

Instruction

Firstly please review the following documentation in order to get familiar with the integration process:

The gateway parameter in the script should have the constant value of tranzzo, according to the example on the right:

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'tranzzo',
    'gatewayMerchantId': '[Point of Sale Id (pos_id)]'
  }
};

const allowedCardNetworks = ['MASTERCARD', 'VISA'];
const allowedCardAuthMethods = ['PAN_ONLY', 'CRYPTOGRAM_3DS'];

The value of the gatewayMerchantId parameter should be the identifier of the payment point where the order is made.

In response, Google shall return the PaymentData item, and the field paymentMethodData.tokenizationData.token shall contain a safely encrypted Google Pay Token (a string of characters).

{
    "signature": "MEUCIQDY3wBQyHB4sZcktRoJXKxm+OLcjHzCvdDeGn23oX0kkwIgKznRFZZL+sDMv1b5cuD+YurXMZraYBsr9hbravVY5Ro\u003d",
    "protocolVersion": "ECv1",
    "signedMessage": "{\"encryptedMessage\":\"cI87tLqzqTGyCFnMMCVWcTHw3xhYIK+CEnuQ74K+nlLpCgOlfpScib9jds4sxDtN6CunCqCSMfd/3yHeeRy6aCx1yyqcT4ey6NueeBznprJpkmVVgI1JHWLQt4hzAXMUAcYASYLOabKP9fUZvHkOBDytD531jpzNXa+Spc/zrpGzFKx2C4VU9sC95q9i+ey+kr7ZMNVCOFJPWXu7lKZ105IOOqozJ6/70MKmxP3jM89eeq+/19QnyHjQLXfnQPvQjiUJKGCcRKDLlrb3XoY5ZUUzGfN5eZCLzCVg0hWEbwU+6J7KWYJyW+Wr1r8bagN9zWsrMKhDpsQbHfyzb+yBzFUoxeUgL4a7FeVvEllIcHtqsvTCf6FENV20aF5VLDv5qzUkV+PzTAIbFEuabA0God9UbVCVVv7nM8QFzvRPhzYYFVFTn4JHvL2qZ4pAR9lE+w\\u003d\\u003d\",\"ephemeralPublicKey\":\"BPHLC4sBHpenY1M0ixmiDMuWJTaTJOqggRUwtgBJMcBp28VsxHD7zPI7985x4F5EjMP5y8j/cuUzbe/cGPjOKGk\\u003d\",\"tag\":\"RaXrPOUuc5iw3oxDa0C2MOjaKxgxIRQvwOspmtFV0zU\\u003d\"}"
}

Charging

To charge the payment card stored under Google Pay, in the direct method request fill in payway and cc_token with the following values:

Further processing of the request is subject to the standard payment process.

Please note that it may be necessary to handle a redirect of the request to the 3D Secure authentication page.

Sandbox

The Google Pay payment method is available also under the Sandbox environment – during the integration process, openly indicate the test environment:

var paymentsClient = new google.payments.api.PaymentsClient({environment: 'TEST'});

Widget Checkout

Widget checkout is used for smooth integration with merchant's websites.

Integration

Include script tag into your website: <script src="https://gcdn.tranzzo.com/widget.js" async></script>

The script is loaded asynchronously.

init() method receive parameters:

let initParams = {
 /* API token issued by Tranzzo */
 key: 'hQ8aqcm/RG1RF7MaImmzZUsThYhAVDG6R7kazf9+r7zuoWo6',
 /* Optional amount */
 amount: 350.5,
 /* Currently, only 'inline' mode is supported */
 mode: 'inline',
 /* Optional user language */
 lang: 'uk',
 /* Optional predefined custom style */
 style: 'dark',
 /* Optional widget type */
 type: 'full_card',
 /* Identifier of HTML element (for 'inline' mode only) */
 selector: 'widget-checkout',
 /* Handler for receiving token data */
 onToken: function(tokenData) {
   /*
     It is guaranteed that`tokenData` will have the following fields:
     {
       "token": "String(<=128)",
       "expires_at": "ISO-8601 DateTime",
       "card_mask": "String(13-19)"
     }
   */
 }
};

let widget = Tranzzo.init(initParams)

Tranzzo#init parameters:

Parameter Type Required Description
key String API token issued by Tranzzo.
mode String Should be equal to inline.
selector String Identifier of HTML element (e.g. div id={payform-holder}) where the widget will be mounted (for inline mode).
onToken Function Callback to invoke when the checkout process is complete.
amount Number Optional amount to be shown in widget for UX purposes.
locale Object Locale customization
lang String Preferred widget localization. Currently supported languages: ru, en, uk.
style String Optional predefined custom style
type String Optional widget type. Available options: full_card(default) - collect all card credentials (payments), pan_only - tokenize only card number (payouts).
template String Optional custom template. Currently supported templates: line

locale :

{
  "ru": {
    "cardNumber": "Номер карты",
    "expiryDate": "Срок действия",
    "cvv": "CVV",
    "submit": "Оплатить",
    "yy": "ГГ",
    "mm": "ММ",
    "hints": {
      "cvvHint": "Код расположен на обратной стороне карты"
    },
    "errors": {
      "cardnumber": "Неверный номер карты",
      "expiryDate": "Cрок карты истек",
      "cvv": "Некорректний CVV/CVC2 код"
    }
  }
}

#onToken parameters:

Parameter Type Required Description
token String(≤128) Token issued by Tranzzo. Acceptable for payments via direct mode.
expires_at String(26) ISO-8601 timestamp (yyyy-mm-ddThh:mm:ss). End of token life. Example: 2099-12-31T00:00:00.
card_mask String(13-19) Mask of tokenized card. Example: 424242******4242.

Widget API

Tranzzo#init return special control object with the following API methods:

Method Parameter Description
widget.open() none Render widget
widget.close() none Force close widget

Integration examples

Eager widget loading:

// Eagerly initialize widget
function __onWidgetReady() {
  let widget = Tranzzo.init({
                    key: 'hQ8aqcm/RG1RF7MaImmzZUsThYhAVDG6R7kazf9+r7zuoWo6',
                    amount: 350.5,
                    mode: 'inline',
                    lang: 'uk',
                    selector: 'widget-checkout',
                    /* Handler for receiving token data */
                    onToken: function(tokenData) {
                      /* Handle token data. For example, create direct payment or add card to wallet */
                      backend.submitPayment(orderId, tokenData);
                    }
                  });
}

const payButton = document.getElementById('btn-pay');

// Open widget on action
payButton.addEventListener('click', function(e) {
  e.preventDefault();

  widget.open();
});

After internal form submission, Tranzzo token token will be sent in response to onToken function.

If script was loaded asynchronously, you should wrap init() method in function wrapper: __onWidgetReady

Lazy widget loading

// Create widget entity on button click (for example, radio button option)
function __onWidgetReady() {
  document
    .getElementById('btn-pay')
    .addEventListener('click', function(e) {
        e.preventDefault();
        Tranzzo
          .init({
            key: 'hQ8aqcm/RG1RF7MaImmzZUsThYhAVDG6R7kazf9+r7zuoWo6',
            amount: 350.5,
            mode: 'inline',
            lang: 'uk',
            selector: 'widget-checkout',
            /* Handler for receiving token data */
            onToken: function(tokenData) {
              // Handle token data. For example, create direct payment or add card to wallet.
              backend.submitToken(orderId, tokenData);
            }
          })
          .open();
      }
    );
}

Initialize and open widget instantly

  function __onWidgetReady() {
    Tranzzo.init({ ... }).open();
  }

Widget Events

Example usage:

    document.addEventListener('widget-init-ready', () => {
      widget.open();
    })
    document.addEventListener('widget-init-error', (e) => {
      console.error('error', e.detail.id, e.detail.message)
    });

After widget is successfully initiated, widget-init-ready event is dispatched. Otherwise, in case of error, widget will dispatch widget-init-error error. You can add event listener to this events.

Widget style

Example of custom style:

/* Change widget style */
.trz-widget .card {
  max-width: 320px;
  box-shadow: 0 8px 50px -6px rgba(84, 84, 120, .26);
  border-radius: 5px;
  padding: 10px 8px;
  border: 1px solid #eee;
  margin: 10px 20px;
}

/* Change submit button background */
.trz-widget .btn-submit {
  background: #3572b0
}

There is an option to customize widget style. You can provide your own CSS style for widget and it will be available for usage as style option.

Enrichment API

Enrichment API is used to obtain information about BIN and IP address location.

BIN info

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/enrichments/${POS_ID}/bins/${BIN}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Obtain information about BIN.

HTTP method: GET

Parameter Type Required Description
POS_ID UUID Merchant's identifier (POS_ID)
BIN Number BIN identifier

Response example:

{
  "card": {
    "bin": 424242,
    "payment_system": "VISA",
    "card_type": "CREDIT",
    "card_variant": "UNDEFINED"
  },
  "country": {
    "country": "UNITED KINGDOM",
    "country_digit_code": "826",
    "iso_a2_code": "GB",
    "iso_a3_code": "GBR",
    "region": "Europe"
  },
  "bank": {
    "bank": "UNDEFINED",
    "bank_website": "UNDEFINED",
    "bank_phone": "UNDEFINED"
  },
  "risk_level": "UNDEFINED"
}

Return status 404 if no BIN information.

IP info

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/enrichments/${POS_ID}/ips/${IP}" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Obtain information about IPv4/IPv6 address location.

HTTP method: GET

Parameter Type Required Description
POS_ID UUID Merchant's identifier (POS_ID)
IP String IP address

Response example:

{
    "continent": "Asia",
    "country": "China",
    "stateprov": "Guangdong province",
    "city": "Guangzhou",
    "latitude": "23.1291",
    "longitude": "113.2644"
}

Return status 400 if IP address has invalid format.

Return status 404 if no IP address location information.