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:

Order Id uniqueness

This uniqueness doesn’t depend on status of previous transaction done using this order_id. For example, if previous transaction was a failure, when attempt to create new reusing same order_id will be rejected anyway. This also means that for same pos_id secondary operations should reuse order_id of corresponding primary operation.

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 replaced 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"
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.

Browser fingerprint

For each direct or p2p payment you can optionally pass browser fingerprint data.

Example of browser fingerprint:

"browser_fingerprint": {
  "browserColorDepth":       "24",
  "browserScreenHeight":     "860",
  "browserScreenWidth":      "1600",
  "browserJavaEnabled":      "false",
  "browserLanguage":         "uk-UA",
  "browserTimeZone":         "Europe/Kiev",
  "browserTimeZoneOffset":   "-120",
  "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
  "browserIpAddress":        "127.0.0.1",
  "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
}

Allowed properties for browser fingerprint

Parameter Type Description
browserColorDepth String Browser's color depth
browserScreenHeight String Browser's screen height
browserScreenWidth String Browser's screen width
browserJavaEnabled String Browser's java enabled
browserLanguage String Browser's language
browserTimeZone String Browser's timezone
browserTimeZoneOffset String Browser's timezone offset
browserAcceptHeader String Browser's accept header
browserIpAddress String Browser's IP address
browserUserAgent String Browser's user agent

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 identifier 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_lang String Checkout language. Supported values.
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
equivalent_amount Number Transaction amount in equivalent currency
equivalent_currency CURRENCY Transaction equivalent currency (ISO_4217). Use this parameter together with equivalent_amount to show customers the approximate equivalent of the payment amount in another currency on the checkout.

Create QR code payment

HTTP method: POST

Request parameters

Request example:

$ curl -i "https://cpay.tranzzo.com/api/v1/payment?qr=true" \
    -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"
    }'

Response example:

{
  "qr_link": "https://cpay.tranzzo.com/api/v1/checkout/baf1592f-d7e8-4c28-9b86-43499bc54904/qr"
}
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 identifier 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_lang String Checkout language. Supported values.
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",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'
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 identifier 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
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
cryptogram Json Cryptogram parameters.
customer_referrer URL Page customer is redirected from.

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":      "http://secure.secure3d.net/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",
  "bank_short_name":      "Bank name"
}
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
bank_short_name String Bank short name.

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 identifier 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":      "http://secure.secure3d.net/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",
  "bank_short_name":      "Bank name"
}
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
bank_short_name String Bank short name.

Direct payments using Privat Payment by Parts

Payment by Parts from Privat is a cost-effective loan, given to a customer according to a credit limit set in case of payment for a product/service in trade and service enterprises and/or online stores. Could be paid only by Privat bank card. Details are here: Details are here: https://privatbank.ua/kredity/oplata-chastyami

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":           300,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "payway":           "privat_payparts",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "properties":       {
        "part_counts": 2
      },
      "products":         [
        {
          "name"    : "Apple",
          "amount"  : 100,
          "currency": UAH,
          "qty"     : 2
        },
        {
          "name"    : "Pineapple",
          "amount"  : 100,
          "currency": UAH,
          "qty"     : 1
        }
      ]
    }'
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 (must be > 300 UAH)
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identifier of order
order_3ds_bypass String 3-D Secure flow option
payway String Optional payway. Use "privat_payparts" for processing direct payments through Privat Payment by Parts
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
properties.parts_count String The number of parts into which the payment amount is divided (must be > 1 and <= 25)

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":               300,
  "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":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "payway":               "privat_payparts",
  "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",
  "bank_short_name":      "Bank name"
}
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 "privat_payparts" for processing direct payments through Privat Payment by Parts
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
bank_short_name String Bank short name.

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",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

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 identifier 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
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
customer_referrer URL Page customer is redirected from.

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":      "http://secure.secure3d.net/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",
  "rnn":                  "014681438245",
  "authcode":             "442413",
  "bank_short_name":      "Bank name"
}

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.
rnn String Transaction unique bank identifier
authcode String Transaction authentication code
bank_short_name String Bank short name

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",
      "external_fee":        0.05,
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

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 identifier 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
external_fee Number Transaction external fee. Note: usage of the parameter requires an approval
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.

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":      "http://secure.secure3d.net/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",
      "external_fee":        0.05,
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

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 identifier of transfer
cc_token CC_TOKEN Tranzzo card token, obtained from previous payments
recipient_cc_token CC_TOKEN Tranzzo card token, obtained from previous payments. Note: you can use recipient_cc_number instead
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
external_fee Number Transaction external fee. Note: usage of the parameter requires an approval
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.

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":      "http://secure.secure3d.net/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.

Lookup

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":           "lookup",
      "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 or hosted
method METHOD Payment method (lookup)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identifier 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":               "lookup",
  "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":      "http://secure.secure3d.net/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 (lookup)
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.

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 identifier of transfer
cc_number CC_NUMBER Recipient's card number
order_3ds_bypass String 3-D Secure flow option
customer_id String Customer's identifier in merchant's system
customer_fname String Customer's first name
customer_lname String Customer's last name
customer_email String Customer's email
customer_phone String Customer's phone
customer_ip String Customer's IP address
customer_country String Customer's country (ISO_3166-2)
customer_city String Customer's city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
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
properties JSON Additional specific parameters for integrations

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",
  "customer_city":        "Ivano-Frankivsk",
  "customer_birthday":    "1999-04-02",
  "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",
  "properties": {
     "recipient_first_name":"Petro",
     "recipient_last_name":"Petrenko",
     "recipient_middle_name":"Petrovych",
     "recipient_doc_number":"1234567890",
     "recipient_doc_issue_date":"2015-08-12",
     "recipient_doc_issued_by":"Kyiv RV UMVS",
     "recipient_phone":"380999999999",
     "recipient_birth_date":"2000-01-01",
     "recipient_birth_place":"Kyiv",
     "recipient_country":"UA",
     "recipient_city":"Kyiv",
     "recipient_address":"Kyiv City, Akademika Yangelia St. 18/1, ap. 309",
     "recipient_postcode":"03056",
     "wallet_number":"12345678900987"
  }
}

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's identifier in merchant's system
customer_ip IP Customer's IP address
customer_fname String Customer's first name
customer_lname String Customer's last name
customer_email String Customer's email
customer_phone String Customer's phone
customer_country String Customer's country (ISO_3166-2)
customer_city String Customer's city
customer_birthday Date Customer's birthday
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.
properties JSON Additional specific parameters for integrations

Allowed properties for credit payment request/response

Parameter Type Description
recipient_first_name String Recipient's first name
recipient_middle_name String Recipient's middle name
recipient_last_name String Recipient's last name
recipient_doc_number String Recipient's document number
recipient_doc_issue_date Date Recipient's document issue date (format: yyyy-MM-dd)
recipient_doc_issued_by String Recipient's place that issued his/her document
recipient_phone String Recipient's phone
recipient_birth_date Date Recipient's birth date (format: yyyy-MM-dd)
recipient_birth_place String Recipient's birth place
recipient_country String Recipient's citizenship (ISO_3166-2)
recipient_city String Recipient's city
recipient_address String Recipient's address
recipient_postcode String Recipient's postcode
wallet_number String Wallet number

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 identifier 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's identifier in merchant's system
customer_fname String Customer's first name
customer_lname String Customer's last name
customer_email String Customer's email
customer_phone String Customer's phone
customer_ip String Customer's IP address
customer_country String Customer's country (ISO_3166-2)
customer_city String Customer's city
customer_birthday Date Customer's birthday (format: yyyy-MM-dd)
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
properties JSON Additional specific parameters for integrations

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",
  "customer_city":        "Ivano-Frankivsk",
  "customer_birthday":    "1999-04-02",
  "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",
  "properties": {
     "recipient_first_name":"Petro",
     "recipient_last_name":"Petrenko",
     "recipient_middle_name":"Petrovych",
     "recipient_doc_number":"1234567890",
     "recipient_doc_issue_date":"2015-08-12",
     "recipient_doc_issued_by":"Kyiv RV UMVS",
     "recipient_phone":"380999999999",
     "recipient_birth_date":"2000-01-01",
     "recipient_birth_place":"Kyiv",
     "recipient_country":"UA",
     "recipient_city":"Kyiv",
     "recipient_address":"Kyiv City, Akademika Yangelia St. 18/1, ap. 309",
     "recipient_postcode":"03056",
     "wallet_number":"12345678900987"
  }
}

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's identifier in merchant's system
customer_ip String Customer's IP address
customer_fname String Customer's first name
customer_lname String Customer's last name
customer_email String Customer's email
customer_phone String Customer's phone
customer_country String Customer's country (ISO_3166-2)
customer_city String Customer's city
customer_birthday Date Customer's birthday
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.
properties JSON Additional specific parameters for integrations

Allowed properties for credit payment using Tranzzo tokens request/response

Parameter Type Description
recipient_first_name String Recipient's first name
recipient_middle_name String Recipient's middle name
recipient_last_name String Recipient's last name
recipient_doc_number String Recipient's document number
recipient_doc_issue_date Date Recipient's document issue date (format: yyyy-MM-dd)
recipient_doc_issued_by String Recipient's place that issued his/her document
recipient_phone String Recipient's phone
recipient_birth_date Date Recipient's birth date (format: yyyy-MM-dd)
recipient_birth_place String Recipient's birth place
recipient_country String Recipient's citizenship (ISO_3166-2)
recipient_city String Recipient's city
recipient_address String Recipient's address
recipient_postcode String Recipient's postcode
wallet_number String Wallet number

Cryptogram

In case you have a decrypted applepay or gpay token, you can pass the cryptogram together with card data from the token.

Parameter Type Required Description
type String applepay or gpay
cryptogram String Cryptogram value from the token.
eci String ECI value from the token.

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",
      "comment":        "10101",
      "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
comment String Capture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
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",
  "fee":                 null,
  "comment":             "10101"
}
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
fee Object Amount and currency of commission
comment String Capture comment

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,
      "comment":        "10101",
      "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
comment String Capture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
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",
  "fee":                 null,
  "comment":             "10101"
}
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
fee Object Amount and currency of commission
comment String Capture comment

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",
      "comment":        "10101",
      "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 voided (max length is 32 characters)
order_currency CURRENCY Currency of original order
comment String Void comment. Can be used for describing reasons of void or for passing another data about operation (max length is 2048 characters)
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",
  "fee":                 null,
  "comment":             "10101"
}
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
fee Object Amount and currency of commission
comment String Void comment

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",
      "comment":        "10101",
      "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 refunded (max length is 32 characters)
order_currency CURRENCY Currency of original order
comment String Refund comment. Can be used for describing reasons of refund or for passing another data about operation (max length is 2048 characters)
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",
  "fee":                 null,
  "comment":             "10101"
}
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
fee Object Amount and currency of commission
comment String Refund comment

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,
      "comment":        "10101",
      "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 refunded (max length is 32 characters)
order_currency CURRENCY Currency of original order
refund_amount Number Amount to be refunded
comment String Refund comment. Can be used for describing reasons of refund or for passing another data about operation (max length is 2048 characters)
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",
  "fee":                 null,
  "comment":             "10101"
}
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
fee Object Amount and currency of commission
comment String Refund comment

P2P Credit

HTTP method: POST

Request parameters

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/p2p-credit" \
    -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",
      "description":    "description_1",
      "cc_number":      "4242424242424242",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/p2p-credit"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
order_id String Merchant's order identifier to be credited (max length is 32 characters)
order_currency CURRENCY Currency of original order
description CURRENCY Currency of original order
cc_number CC_NUMBER Card number
comment String P2p comment. Can be used for describing reasons of p2p or for passing another data about operation (max length is 2048 characters)
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":              "credit",
  "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:15.200",
  "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b"
  "fee":                 null,
  "comment":             "10101"
}
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 credit
amount Number Actual p2p credit 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_at TIMESTAMP Timestamp when transaction was updated last time
registry_ref_no String Gateway transaction identifier
fee Object Amount and currency of commission
comment String P2p comment

P2P Credit using Tranzzo tokens

HTTP method: POST

Request parameters

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/p2p-credit" \
    -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",
      "description":    "description_1",
      "cc_token":       "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/p2p-credit"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
order_id String Merchant's order identifier to be credited (max length is 32 characters)
order_currency CURRENCY Currency of original order
description CURRENCY Currency of original order
cc_token CC_TOKEN Tranzzo card token generated for this card
comment String P2p comment. Can be used for describing reasons of p2p or for passing another data about operation (max length is 2048 characters)
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":              "credit",
  "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:15.200",
  "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b"
  "fee":                 null,
  "comment":             "10101"
}
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 credit
amount Number Actual p2p credit 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_at TIMESTAMP Timestamp when transaction was updated last time
registry_ref_no String Gateway transaction identifier
fee Object Amount and currency of commission
comment String P2p comment

Partial P2P Credit

HTTP method: POST

Request parameters

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/p2p-credit" \
    -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",
      "credit_amount":  25,
      "description":    "description_1",
      "cc_number":      "4242424242424242",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/p2p-credit"
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
order_id String Merchant's order identifier to be credited (max length is 32 characters)
order_currency CURRENCY Currency of original order
credit_amount Number Amount to be credited
description CURRENCY Currency of original order
cc_number CC_NUMBER Card number
comment String P2p comment. Can be used for describing reasons of p2p or for passing another data about operation (max length is 2048 characters)
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":              "credit",
  "amount":              25,
  "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:15.200",
  "registry_ref_no":     "9e62565c-ef89-4b7e-bcbd-a96f76af303b"
  "fee":                 null,
  "comment":             "10101"
}
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 credit
amount Number Actual p2p credit 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_at TIMESTAMP Timestamp when transaction was updated last time
registry_ref_no String Gateway transaction identifier
fee Object Amount and currency of commission
comment String P2p comment

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":             "",
    "bank_short_name":     "Bank name"
  },
  {
    "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.

Get transactions in JSON format

Request example:

$ curl --location --request POST 'https://api.tranzzo.com/streaming-report/start' \
--header 'X-API-Auth:CPAY 28e957dc-aff7-4575-bd0f-739ec9bc77ee:UnE2Tmc4N0FnVm1JMmxHcGRIdmJ4aHZq' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "064ec3f8-8abb-414b-9eb3-49d977213967",
    "start_date": "2022-09-01T12:00:03.007+00:00",
    "end_date": "2022-09-30T23:58:03.007+00:00",
    "statuses": [ "success", "pending", "failure", "init" ],
    "methods": [
        "purchase",
        "auth",
        "capture",
        "void",
        "p2p",
        "credit",
        "lookup",
        "refund",
        "dispute"
        ],
    "transaction_details": [
       "projectId",
       "orderId",
       "paymentId",
       "amount",
       "currency",
       "method",
       "status",
       "dateTime",
       "cardMask",
       "payway",
       "entityName",
       "projectName",
       "originalAmount",
       "exchangeAmount",
       "exchangeCurrency",
       "exchangeRate",
       "tokenizationKind",
       "authCode",
       "rrnCode",
       "description",
       "payload",
       "customerFee",
       "merchantFee",
       "paymentSystem",
       "recipientCardMask"
    ]
}'

GET Report ID

First, you need to send a request to generate a report that will contain transactions that can be filtered by the following parameters:

Parameter Required Description
project_id Merchant's identifier (POS_ID)
start_date The start date of the period for which the data is required
end_date Period end date. The maximum period is 31 days
statuses Array of Transaction status
methods Payment methods (auth, purchase, capture, void, p2p, credit, lookup, refund, dispute, recurrent)
transaction_details Array field with the parameters that are received for each of the transactions in report

List of transaction details parameters

Additionally, you can specify a list of parameters in the array transaction_details array that you want to receive for each of the transactions in this report. List of available options:

Parameter Default Description
orderId Merchant's order identifier to be captured
paymentId Tranzzo payment identifier of primary operation
amount Transaction amount with fees applied
currency Transaction currency
method Payment methods
status Transaction status
dateTime Transaction date
cardMask Сard mask
payway Payway name
customerFee Customer fee
merchantFee Merchant fee
entityName Entity name
projectName Project name
originalAmount Transaction amount with no fees applied
exchangeAmount Exchange amount
exchangeCurrency Exchange currency
exchangeRate Exchange rate
tokenizationKind Tokenization kind
authCode Transaction authentication code
rrnCode RRN code
description Transaction description
payload Field for custom data
paymentSystem Payment system
recipientCardMask Recipient's card mask
reserveAmount Rolling reserve amount
receiverName Name of sub merchant in split transaction
receiverAmount Amount paid to sub merchant in split transaction
receiverFee Fee amount paid by sub merchant in split transaction

If you does not set transaction_details with a list of parameters, you will receive those marked default.

Response example:

{"report_id":"57e79df2-b374-4998-9b0e-ac7848760bed","count":384}

Example of response body returned in case of report is not ready. Code 202:

{
  "message": "Report not ready",
  "code": "report_not_ready"
}

Response parameters

Parameter Description
report_id JSON file identifier
count number of records (transactions)

Get JSON by report_id

Request example:

$ curl --location --request GET 'https://api.tranzzo.com/streaming-report/fetch/57e79df2-b374-4998-9b0e-ac7848760bed'
--header 'X-API-Auth:CPAY 28e957dc-aff7-4575-bd0f-739ec9bc77ee:UnE2Tmc4N0FnVm1JMmxHcGRIdmJ4aHZq'

To get a list of all transactions (the number of which is specified in count), you need to send a request with a specific report_id.

Response example:

{"projectId":"064ec3f8-8abb-414b-9eb1-49d977213999","orderId":"1456649508235","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb58","amount":"3","currency":"UAH","method":"void","status":"success","dateTime":1662033684016,"cardMask":"414141******2284","payway":"applepay","entityName":"","projectName":"Project","originalAmount":"3","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"description","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}
{"projectId":"064ec3f8-8abb-414b-9eb1-49d977213988","orderId":"1456649508236","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb51","amount":"2","currency":"UAH","method":"auth","status":"success","dateTime":1662033684916,"cardMask":"537541******2284","payway":"gpay","entityName":"","projectName":"Project","originalAmount":"2","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"description","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}
{"projectId":"064ec3f8-8abb-414b-9eb2-49d977213967","orderId":"1456649508238","paymentId":"b2dc0fb9-2de4-4a30-9447-088ce415fb50","amount":"1","currency":"UAH","method":"purchase","status":"success","dateTime":1662033680916,"cardMask":"537541******1184","payway":"cc","entityName":"","projectName":"Test Project","originalAmount":"1","exchangeAmount":"0.00","exchangeCurrency":"","exchangeRate":"0.00","tokenizationKind":"","authCode":"238530","rrnCode":"003561423521","description":"test qa","payload":"","customerFee":"0.00","merchantFee":"0.00","paymentSystem":"MASTERCARD","recipientCardMask":""}

The response will contain JSON with the number of records equal to count. Each record will have the set of parameters that was specified when creating the report.

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.

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

DCC

In cases of payment with DCC response will contain dcc_rates field with exchange rates for current request.

This is applicable only to purchase method (see primary operations for details) and to currencies other than the UAH.

N.B. The terminal must be pre-configured to return exchange rates. To do this, please contact support at support@tranzzo.com.

Field Type Example Description
amount Number 3.5984 Amount of payment in alternative currency
currency CURRENCY "USD" Alternative currency
rate Number 27.7905 Conversion rate
commission Number 0.0 Commission on payment in alternative currency
{
  "dcc_rates": [{
      "amount":     3.5984,
      "rate":       27.7905,
      "commission": 0.0,
      "currency":   "USD"
  }]
}

Split payment

Split payment is a single charge of the whole amount from the payer’s card and payouts for multiple merchants.

Hosted split payment

See more information about hosted payments

HTTP method: POST

Request parameters

Request example:

$ curl -i "https://cpay.tranzzo.com/api/v1/split/purchase" \
    -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":           100,
      "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",
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]  
    }'

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 (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identifier 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_lang String Checkout language. Supported values.
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
split Array[SplitPayment] Split payment properties

Direct split payment

See more information about direct payments

HTTP method: POST

Request parameters

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/split/purchase" \
    -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":           100,
      "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",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      },
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]      
    }'
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
description String Payment description
order_id String Unique identifier 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
browser_fingerprint Json Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
split Array[SplitPayment] Split payment properties

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":               100,
  "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":      "http://secure.secure3d.net/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",
  "bank_short_name":      "Bank name"
}
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 (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
bank_short_name String Bank short name.
split_fee Object Amount and currency of commission by marketplace and sub-merchants

Capture split payment

HTTP method: POST

Request parameters

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/split/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",
      "charge_amount":  100,
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture",
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]        
    }'
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)
charge_amount Number Total amount to be captured
order_currency CURRENCY Currency of original order
comment String Capture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
server_url URL Webhook notification will be sent to this URL
split Array[SplitPayment] Split payment properties

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",
  "fee":                 null,
  "comment":             "10101"
}
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
fee Object Amount and currency of commission
comment String Capture comment
split_fee Object Amount and currency of commission by marketplace and sub-merchants

Refund split payment

HTTP method: POST

Request parameters

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/split/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",
      "refund_amount":  100,
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture",
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]      
    }'
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)
refund_amount Number Total amount to be refunded
order_currency CURRENCY Currency of original order
comment String Refund comment. Can be used for describing reasons of refund or for passing another data about operation (max length is 2048 characters)
server_url URL Webhook notification will be sent to this URL
split Array[SplitPayment] Split payment properties

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",
  "fee":                 null,
  "comment":             "10101"
}
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
fee Object Amount and currency of commission
comment String Refund comment
split_fee Object Amount and currency of commission by marketplace and sub-merchants

Split payment properties

Parameter Type Required Description
amount Number Transaction amount
sub_merchant_id UUID Unique Sub merchant identifier (to get the identifier, please contact support at support@tranzzo.com)

Alternative Payment Methods

Regional

Asia

India

Wallet (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":           "$POS_ID",
    "mode":             "direct",
    "amount":           12,
    "Method":           "purchase",
    "currency":         "INR",
    "payway":           "WL",
    "customer_email":   "name@mail.com",
    "customer_phone":   "7259955534",
    "customet_fname":   "John",
    "customer_lname":   "Doe",
    "customer_ip":      "0.0.0.0",
    "order_3ds_bypass": "supported",
    "description":      "Test description for '$ORDER_ID'# payment",
    "order_id":         "$ORDER_ID",
    "server_url":       "https://callback.blackhole.com/callback",
    "result_url":       "https://example.com/result",
    "properties": {
        "mop_type": "102"
    }
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_email String payer’s email address
customer_phone String payer’s phone number
customer_fname String payer’s first name
customer_lname String payer’s last name
properties.mop_type String type of wallet
customer_ip String payer’s IP


NetBanking (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":             "’$POS_ID’",
    "mode":               "direct",
    "amount":             12,
    "method":             "purchase",
    "currency":           "INR",
    "payway":             "NB",
    "customer_email":     "name@mail.com",
    "customer_phone":     "7259955534",
    "customet_fname":     "John",
    "customer_lname":     "Doe",
    "customer_birthday":  "1990-04-01",
    "customer_city":      "Kale",
    "order_3ds_bypass":   "supported",
    "description":        "Test description for '$ORDER_ID'# payment",
    "order_id":           "$ORDER_ID",
    "server_url":         "https://callback.blackhole.com/callback",
    "result_url":         "https://example.com/result",
    "properties": {
        "mop_type": "1005",
        "address":   "Kale, Gözcü Sk. No:2",
        "post_code": "01323001"
    }
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address
customer_phone String payer’s phone number
properties.mop_type String type of wallet
customer_city String payer’s city
customer_birthday Date payer’s birthday (format: yyyy-MM-dd)
properties.address String payer’s address
properties.post_code String payer’s postcode


Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "amount":              12,
    "method":             "credit",
    "currency":           "INR",
    "payway":             "NB",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "customer_city":      "Kale",
    "customer_birthday": "1990-04-01"
    "customer_phone":     "7259955534"
    "customer_email":     "name@mail.com",
    "order_3ds_bypass":   "supported",
    "description":        "Test description for '$ORDER_ID'# payment",
    "order_id":           "'$ORDER_ID'",
    "server_url":         "https://callback.blackhole.com/callback",
    "result_url":         "https://example.com/result",
    "properties": {
        "bank_account":         "19721080000000",
        "ifsc":                 "HDFC0000000",
        "recipient_phone":      "7259955534",
        "recipient_email":      "name@mail.com",
        "recipient_first_name": "John Doe",
        "state":                "Chennai",
        "post_code":            "12345"
    }
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
customer_email String recipient’s email address
customer_phone String recipient’s phone number
customer_city String recipient’s city
customer_birthday Date recipient’s birthday (format: yyyy-MM-dd)
properties.state String recipient’s regional features
properties.recipient_email String recipient’s email address
This parameter is the alternative to the customer_email
properties.recipient_phone String recipient’s phone number
This parameter is the alternative to the customer_phone
properties.recipient_first_name String recipient's first and last name
This parameter is the alternative to the customer_fname and customer_lname
properties.bank_account String recipient’s account number
properties.ifsc String recipient’s Indian Financial System Code
UPI (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":          "'$POS_ID'",
    "mode":            "direct",
    "amount":          12,
    "method":          "purchase",
    "currency":        "INR",
    "payway":          "UP",
    "order_3ds_bypass": "supported",
    "customer_fname": "John",
    "customer_lname": "Doe",
    "customer_phone": "7259955534",
    "customer_email": "name@mail.com",
    "customer_ip":    "1.2.3.4",
    "description":    "Test description for '$ORDER_ID'# payment",
    "order_id":       "'$ORDER_ID'",
    "server_url":     "https://callback.blackhole.com/callback",
    "result_url":     "https://example.com/result",
    "properties": {
        "mop_type":   "507",
        "upi_number": "9971100000@hdfcbank",
        "trusted":    true,
    }
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address
customer_phone String payer’s phone number
customer_ip String payer’s IP
properties.upi_number String UPI address of the payer
properties.mop_type String type of wallet
properties.trusted Boolean whether the trusted payer


Pay Out

Request Example:

{
  "pos_id":                     "'$POS_ID'",
  "mode":                       "direct",
  "method":                     "credit",
  "amount":                     1,      
  "payway":                     "upi",
  "currency":                   "INR",
  "order_id":                   "'$ORDER_ID'",
    "description":              "Description",
    "customer_fname":           "John",
    "customer_lname":           "Doe",
    "customer_email":           "name@mail.com",
    "customer_phone":           "380991111111",
    "customer_ip":              "1.2.3.4",
    "order_3ds_bypass":         "supported",
    "properties": {
        "recipient_address":    "Nizamabad",
        "recipient_email":      "name@mail.com",
        "recipient_first_name": "John Doe",
        "recipient_phone":      "380991111111",
        "upi_number":           "name@hdfcbank",
        "trusted":              true
    },
    "server_url":               "http://callback-stub:9000/consume",
    "result_url":               "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
customer_email String recipient’s email address
customer_phone String recipient’s phone number
customer_ip String recipient’s IP
properties.recipient_address String recipient’s address
properties.recipient_email String recipient’s email address
This parameter is the alternative to the customer_email
properties.recipient_first_name String recipient's first and last name
This parameter is the alternative to the customer_fname and customer_lname
properties.recipient_phone String recipient’s phone number <br/< This parameter is the alternative to the customer_phone
properties.upi_number String UPI address of the payer
properties.trusted Boolean whether the trusted payer
Paytm (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "paytm",
    "currency":         "INR",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "customer_email":   "name@mail.com",
    "customer_phone":   "380991111111",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "properties": {
        "trusted": true
    },
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address
customer_phone String payer’s phone number
customer_ip String payer’s IP
properties.trusted Boolean whether the trusted payer


Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "method":             "credit",
    "amount":             1,
    "payway":             "paytm",
    "currency":           "INR",
    "order_id":           "'$ORDER_ID'",
    "description":        "Description",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "customer_email":     "name@mail.com",
    "customer_phone":     "380991111111",
    "customer_ip":        "1.2.3.4",
    "order_3ds_bypass":   "supported",
    "properties": {
        "trusted":        true,
        "account_number": "1234567890"
    },
    "server_url":         "http://callback-stub:9000/consume",
    "result_url":         "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
customer_email String recipient’s email address
customer_phone String recipient’s phone number
customer_ip String recipient’s IP
properties.account_number String PayTM wallet or phone number (always 10 digits)
properties.trusted Boolean whether the trusted payer


IMPS (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "imps",
    "currency":         "INR",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "customer_email":   "name@mail.com",
    "customer_phone":   "380991111111",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "properties": {
        "trusted":      true
    },
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address
customer_phone String payer’s phone number
customer_ip String payer’s IP
properties.trusted Boolean whether the trusted payer


Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "method":             "credit",
    "amount":             1,
    "payway":             "imps",
    "currency":           "INR",
    "order_id":           "'$ORDER_ID'",
    "description":        "Description",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "customer_email":     "name@mail.com",
    "customer_phone":     "380991111111",
    "customer_ip":        "1.2.3.4",
    "order_3ds_bypass":   "supported",
    "properties": {
        "account_number": "1234567890",
        "account_name":   "John Doe",
        "ifsc":           "SHFD0000",
        "bank_name":      "Bank of India",
        "trusted":        true
    },
    "server_url":         "http://callback-stub:9000/consume",
    "result_url":         "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
customer_email String recipient’s email address
customer_phone String recipient’s phone number
customer_ip String recipient’s IP
properties.account_name String recipient’s IMPS account name
properties.account_number String recipient’s IMPS account number
properties.ifsc String recipient's Indian Financial System Code
properties.bank_name String bank name
properties.trusted Boolean whether the trusted payer


PhonePE (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":         "'$POS_ID'",
    "mode":           "direct",
    "method":         "purchase",
    "amount":         1000,
    "payway":         "phonepe",
    "currency":       "INR",
    "order_id":       "'$ORDER_ID'",
    "customer_fname": "John",
    "customer_lname": "Doe",
    "description":    "Description",
    "customer_email": "0000000000@mail.com",
    "order_3ds_bypass":"supported",
    "server_url":     "http://callback-stub:9000/consume",
    "result_url":     "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address


GPay (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "gpaywallet",
    "currency":         "INR",
    "order_id":         "'$ORDER_ID'",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "description":      "Description",
    "customer_email":   "0000000000@freecharge",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address


Indonesia

Online banking in Indonesia
Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "banking",
    "currency":         "IDR",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "properties": {
        "pay_method":   "513"
    },
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
properties.pay_method String bank ID
customer_ip String payer’s IP


Pay Out

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "credit",
    "payway":           "banking",
    "amount":           100,
    "currency":         "IDR",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "customer_ip":      "1.2.3.4",
    "description":      "Test payment",
    "order_id":         "'$ORDER_ID'",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "http://www.google.com/"
    "properties": {
        "payment_type": "onlineBanking",
        "pay_method":   "513",
        "bank_account": "12345678"
    }
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
properties.payment_type String payment type
properties.pay_method String bank ID
properties.bank_account String recipient’s bank account number
customer_ip String recipient’s IP


Malaysia

Online banking in Malaysia
Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "banking",
    "currency":         "MYR",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "properties": {
        "pay_method":   "513"
    },
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
properties.pay_method String bank ID
customer_ip String payer’s IP


Pay Out

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "credit",
    "payway":           "banking",
    "amount":           100,
    "currency":         "MYR",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "customer_ip":      "1.2.3.4",
    "description":      "Test payment",
    "order_id":         "'$ORDER_ID'",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "http://www.google.com/",
    "properties": {
        "payment_type": "onlineBanking",
        "pay_method":   "513",
        "bank_account": "12345678"
    }
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
properties.payment_type String payment type
properties.pay_method String bank ID
properties.bank_account String recipient’s bank account number
customer_ip String recipient’s IP


Philippines

Online banking in the Philippines
Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "method":             "credit",
    "payway":             "banking",
    "amount":             100,
    "currency":           "PHP",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "customer_ip":        "1.2.3.4",
    "description":        "Test payment",
    "order_id":           "'$ORDER_ID'",
    "order_3ds_bypass":   "supported",
    "server_url":         "http://callback-stub:9000/consume",
    "result_url":         "http://www.google.com/"
    "properties": {
        "payment_type":   "philippinesWallet",
        "pay_method":     "coinsph",
        "account_number": "12345678"
    }
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
properties.payment_type String payment type
properties.pay_method String bank ID
properties.account_number String recipient’s bank account number
customer_ip String recipient’s IP


South Korea

P2P in South Korea
Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "banking",
    "currency":         "KRW",
    "customer_email":   "name@mail.com",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_ip String payer’s IP


Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "method":             "credit",
    "payway":             "banking",
    "amount":             100,
    "currency":           "KRW",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "customer_ip":        "1.2.3.4",
    "description":        "Test payment",
    "order_id":           "'$ORDER_ID'",
    "order_3ds_bypass":   "supported",
    "server_url":         "http://callback-stub:9000/consume",
    "result_url":         "http://www.google.com/"
    "properties": {
        "pay_method":     "1376",
        "account_number": "1234567890"
    }
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
properties.pay_method String bank ID
properties.account_number String recipient’s account number
customer_ip String recipient’s IP


Vietnam

Nganluong (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "gpaywallet",
    "currency":         "VND",
    "order_id":         "'$ORDER_ID'",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "description":      "Description",
    "customer_email":   "0000000000@freecharge",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address


Online banking in Vietnam
Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "banking",
    "currency":         "VND",
    "order_id":         "'$ORDER_ID'",
    "description":      "Description",
    "customer_ip":      "1.2.3.4",
    "order_3ds_bypass": "supported",
    "properties": {
        "pay_method":   "513"
    },
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
properties.pay_method String bank ID
customer_ip String payer’s IP


Pay Out

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "credit",
    "payway":           "banking",
    "amount":           100,
    "currency":         "VND",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "customer_ip":      "1.2.3.4",
    "description":      "Test payment",
    "order_id":         "'$ORDER_ID'",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "http://www.google.com/"
    "properties": {
        "payment_type": "onlineBanking",
        "pay_method":   "513",
        "bank_account": "12345678"
    }
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
properties.payment_type String payment type
properties.pay_method String bank ID
properties.bank_account String recipient’s account number
customer_ip String recipient’s IP


Vietnamese bank transfers
Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "method":           "purchase",
    "amount":           1,
    "payway":           "wallet",
    "currency":         "VND",
    "order_id":         "'$ORDER_ID'",
    "customer_fname":   "John",
    "customer_lname":   "Doe",
    "description":      "Description",
    "customer_email":   "0000000000@freecharge",
    "order_3ds_bypass": "supported",
    "server_url":       "http://callback-stub:9000/consume",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address


Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "method":             "credit",
    "payway":             "wallet",
    "amount":             100,
    "currency":           "VND",
    "customer_fname":     "John",
    "customer_lname":     "Doe",
    "description":        "Test payment",
    "order_id":           "'$ORDER_ID'",
    "order_3ds_bypass":   "supported",
    "server_url":         "http://callback-stub:9000/consume",
    "result_url":         "http://www.google.com/"
    "properties": {
        "payment_type":   "onlineBanking",
        "account_number": "12345678"
    }
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
properties.payment_type String payment type
properties.account_number String recipient’s account number


Latin America

Brazil

PicPay (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":           "'$POS_ID'",
    "mode":             "direct",
    "amount":           5,
    "method":           "purchase",
    "currency":         "BRL",
    "payway":           "pic",
    "order_3ds_bypass": "supported",
    "customer_lname":    "Doe",
    "customer_fname":    "John",
    "customer_email":    "name@mail.com",
    "customer_phone":    "1234567890",
    "description":       "Test description",
    "order_id":          "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CPF",
        "post_code":     "88040-230"
    },
    "server_url":       "https://callback.blackhole.com/callback",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address
customer_phone String payer’s phone number
properties.document_type String payer’s document type
properties.document_id String payer’s document ID
properties.post_code String payer’s postal code

Validation

The "properties.document_type" parameter is not mandatory for creating a payment, since it is not always used in requests for PS. The parameter is informative for the merchant. It needs to be transmitted.


Boleto (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "amount":             5,
    "method":             "purchase",
    "currency":           "BRL",
    "payway":             "boleto",
    "order_3ds_bypass":   "supported",
    "customer_lname":     "Doe",
    "customer_fname":     "John",
    "customer_email":     "name@mail.com",
    "customer_phone":     "1234567890",
    "description":        "Test description",
    "order_id":           "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CNPJ",
        "post_code":     "88040-230"
    },
    "server_url":       "https://callback.blackhole.com/callback",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address
customer_phone String payer’s phone number
properties.document_type String payer’s document type
properties.document_id String payer’s document ID
properties.post_code String payer’s postal code


Deposit Express (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":            "'$POS_ID'",
    "mode":              "direct",
    "amount":            5,
    "method":            "purchase",
    "currency":          "BRL",
    "payway":            "deposit",
    "order_3ds_bypass":  "supported",
    "customer_lname":    "Doe",
    "customer_fname":    "John",
    "customer_email":    "name@mail.com",
    "customer_phone":    "1234567890",
    "description":       "Test description",
    "order_id":          "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CNPJ",
        "post_code":     "88040-230",
        "pay_method":    "bradesco"
    },
    "server_url":       "https://callback.blackhole.com/callback",
    "result_url":       "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address
customer_phone String payer’s phone number
properties.document_type String payer’s document type
properties.document_id String payer’s document ID
properties.post_code String payer’s postal code
properties.pay_method String payer’s bank name


Pay Out

Request Example:

{
    "pos_id":                "'$POS_ID'",
    "mode":                  "direct",
    "method":                "credit",
    "amount":                1,
    "currency":              "BRL",
    "order_3ds_bypass":      "supported",
    "order_id":              "'$ORDER_ID'",
    "description":           "Test description",
    "payway":                "banking",
    "customer_lname":        "Doe",
    "customer_fname":        "John",
    "properties": {
        "document_id":       "0000000000",
        "document_type":     "CPF",
        "bank_account_type": "CHECKING",
        "bank_account":      "12345678",
        "bank_account_digit":"2",
        "bank_account_code": "260",
        "branch_code":       "0001"
    },
    "server_url":           "https://callback.blackhole.com/callback",
    "result_url":           "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
properties.document_id String recipient’s document ID
properties.document_type String recipient’s document type
properties.bank_account_type String recipient’s account type
properties.bank_account String recipient’s account number
properties.bank_account_digit String bank account digit
properties.bank_account_code String bank account code
properties.branch_code String bank regional code

Validation

The parameter "properties.document_type" is optional for creating a payment, it is always passed in requests to the "CPF" PS. The parameter is informative for the merchant.


Lotopay (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":            "'$POS_ID'",
    "mode":              "direct",
    "amount":            5,
    "method":            "purchase",
    "currency":          "BRL",
    "payway":            "lotopay",
    "order_3ds_bypass":  "supported",
    "customer_lname":    "Doe",
    "customer_fname":    "John",
    "customer_email":    "name@mail.com",
    "customer_phone":    "1234567890",
    "description":       "Test description",
    "order_id":          "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CNPJ",
        "post_code":     "88040-230"
    },
    "server_url":        "https://callback.blackhole.com/callback",
    "result_url":        "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address
customer_phone String payer’s phone number
properties.document_type String payer’s document type
properties.document_id String payer’s document ID
properties.post_code String payer’s postal code


PIX QR (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "amount":             5,
    "method":             "purchase",
    "currency":           "BRL",
    "payway":             "pix",
    "order_3ds_bypass":   "supported",
    "customer_lname":     "Doe",
    "customer_fname":     "John",
    "customer_email":     "name@mail.com",
    "customer_phone":     "1234567890",
    "description":        "Test description",
    "order_id":           "'$ORDER_ID'",
    "properties": {
        "document_id":    "50284414727",
        "document_type":  "CNPJ",
        "post_code":      "88040-230"
    },
    "server_url":         "https://callback.blackhole.com/callback",
    "result_url":         "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address
customer_phone String payer’s phone number
properties.document_type String payer’s document type
properties.document_id String payer’s document ID
properties.post_code String payer’s postal code


Pay Out

Request Example:

{
    "pos_id":             "'$POS_ID'",
    "mode":               "direct",
    "amount":             5,
    "method":             "credit",
    "currency":           "BRL",
    "payway":             "pix",
    "order_3ds_bypass":   "supported",
    "customer_lname":     "Doe",
    "customer_fname":     "John",
    "customer_email":     "name@mail.com",
    "customer_phone":     "1234567890",
    "description":        "Test description",
    "order_id":           "'$ORDER_ID'",
    "properties": {
        "document_id":    "50284414727",
        "document_type":  "CPF",
        "account_type":   "CPF",
        "account_number": "50284414727"
    },
    "server_url":         "https://callback.blackhole.com/callback",
    "result_url":         "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String recipient’s first name
customer_lname String recipient’s last name
properties.document_id String recipient’s document ID
properties.document_type String recipient’s document type
properties.account_type String recipient’s account type
properties.account_number String recipient’s pix key


PIX (Digital Wallet)
Pay In

Request Example:

{
    "pos_id":            "'$POS_ID'",
    "mode":              "direct",
    "amount":            5,
    "method":            "purchase",
    "currency":          "BRL",
    "payway":            "pix",
    "order_3ds_bypass":  "supported",
    "customer_lname":    "Doe",
    "customer_fname":    "John",
    "customer_email":    "name@mail.com",
    "customer_phone":    "1234567890",
    "description":       "Test description",
    "order_id":          "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CPF"
    },
    "server_url":        "https://callback.blackhole.com/callback",
    "result_url":        "https://example.com/result"
}
Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
mode MODE direct
method METHOD Payment method (purchase)
amount Number Transaction amount
currency CURRENCY Transaction currency (ISO_4217)
order_3ds_bypass String 3-D Secure flow option
order_id String Unique identifier of order
description String Payment description
payway String Payway name
server_url URL Webhook notification will be sent to this URL
result_url URL Customer will be redirected to this URL after payment.
customer_fname String payer’s first name
customer_lname String payer’s last name
customer_email String payer’s email address
customer_phone String payer’s phone number
properties.document_type String payer’s document type
properties.document_id String payer’s document ID


Pay Out

Request Example:

{
    "pos_id":            "'$POS_ID'",
    "mode":              "direct",
    "amount":            5,
    "method":            "credit",
    "currency":          "BRL",
    "payway":            "pix",
    "order_3ds_bypass":  "supported",
    "customer_lname":    "Doe",
    "customer_fname":    "John",
    "customer_email":    "name@mail.com",
    "customer_phone":    "1234567890",
    "description":       "Test description",
    "order_id":          "'$ORDER_ID'",
    "properties": {
        "document_id":   "50284414727",
        "document_type": "CPF"
    },
    "server_url":        "https://callback.blackhole.com/callback",
    "result_url":        "https://example.com/result"
}
Parameter Type Required Description
customer_fname String recipient’s first name
customer_lname String recipient’s last name
customer_email String recipient’s email address
customer_phone String recipient’s phone number
properties.document_id String recipient’s document ID
properties.document_type String recipient’s document type

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",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "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
fee Object Amount and currency of commission
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.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "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
fee Object Amount and currency of commission
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.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "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
fee Object Amount and currency of commission
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.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "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
fee Object Amount and currency of commission
created_at String Timestamp when transaction was created
processed_at String Timestamp when transaction was updated last time

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

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
2012 pending Transaction is on anti-fraud check
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
2122 pending 3DS verification is required
2123 pending Waiting for redirect to the checkout page
2124 pending Waiting for redirect to continue payment
2201 pending Waiting for clarification
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
9000 pending Unknown error. Please, contact technical support.

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, 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
4148 failure Timeout
4149 failure Session expired
4150 failure Invalid operation
4151 failure Invalid input fields
4152 failure Invalid configuration. Please, contact technical support.
4153 failure Transaction rejected
4154 failure Transaction is rejected by anti-fraud
4155 failure Transaction was declined by blacklist
4156 failure Card not supported
4160 failure Failed to create transaction
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
6005 failure Transaction was declined by internal blacklist.

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 opencart-plugin
WordPress wordpress-plugin
Joomla joomla-plugin
Drupal drupal-plugin
Netcat netcat-plugin
PrestaShop prestashop-plugin
MODX Shopkeeper modx-shopkeeper

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

const posId = '9ff7fa91-9823-4087-874d-a27fdb96c51a'

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

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'tranzzo',
    'gatewayMerchantId': posId
  }
};

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

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.

The value of the gatewayMerchantId parameter should be the identifier of the payment point (pos_id) 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).

Charging

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

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

const posId = '9ff7fa91-9823-4087-874d-a27fdb96c51a'

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

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'tranzzo',
    'gatewayMerchantId': posId
  }
};

The Google Pay payment method is available also under the Sandbox environment. To get credentials for test environment, please contact support at support@tranzzo.com.

The gateway parameter in the script should have the constant value of tranzzo.

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

Apple Pay

Apple Pay™ Integration Guide

About Apple Pay

Apple Pay is a mobile payment and digital wallet service by Apple Inc. that allows users to make payments in iOS apps, and on the web without having to enter their payment details each time. It is supported on the iPhone, Apple Watch, iPad and Mac.

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

Before you start

Integration

Integration via Tranzzo checkout page

Request example:

$ curl -v 'https://cpay.tranzzo.com/api/v1/payment' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H "X-API-Auth:CPAY $API_KEY:$API_SECRET" \
    -H "X-API-Key:$ENDPOINTS_KEY" \
    -H 'X-Requested-With: *' \
    --data-raw '{
      "pos_id":           "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
      "order_id":         "123",
      "description":      "Goods 123",
      "payway":           "applepay",
      "mode":             "hosted",
      "method":           "auth",
      "amount":           1.5,
      "currency":         "UAH",
      "order_3ds_bypass": "never",
      "products":         []
    }'

With this method, there is no need for additional integrations. To redirect your clients to the Tranzzo payment page, use hosted payment option we offer. The instruction on configuring a correct request is specified at the Tranzzo documentation page. In this case Apple Pay button will be rendered at the Tranzzo checkout.

Connection with Apple Pay API

To add the Apple Pay entitlement to your website or mobile application, you need to have:

Step 1: Create your merchant identifier

  1. Log in to your Apple Developer account
  2. Go to «Certificates, Identifiers & Profiles» tab
  3. At the section «Identifiers» choose «Merchant IDs»
  4. Add a new Merchant ID by clicking “+” at the top right corner of the page
  5. Fill the requested fields and click «Continue»
  6. Tap «Register» to confirm the data.

Step 2: Create a merchant identity certificate

  1. In «Certificates, Identifiers & Profiles», select Identifiers from the sidebar, then select Merchant IDs from the pop-up menu on the top right.
  2. On the right, select your merchant identifier.
  3. Under Apple Pay Merchant Identity Certificate, click Create Certificate.
  4. Create a certificate signing request on your Mac, and click Continue.
  5. Click Choose File.
  6. In the dialog that appears, select the certificate request file (a file with a .certSigningRequest file extension), then click Choose.
  7. Click Continue.
  8. Click Download.
  9. The certificate file (a file with a .cer file extension) appears in your Downloads folder.

Step 3: Register your merchant domain

This step is only required when you want to enable Apple Pay on the web.

  1. Log in to your Apple Developer account.
  2. In «Certificates, Identifiers & Profiles», select Identifiers from the sidebar, then select Merchant IDs from the pop-up menu on the top right (make sure you select the merchant identifier you created in Step 1).
  3. On the right, select your merchant identifier.
  4. Under Merchant Domains, click Add Domain.
  5. Enter the fully qualified domain name, then click Save.
  6. Click Download, place the downloaded file in the specified location, then click Verify.
  7. Click Done.

Step 4: Verify your merchant domain

  1. Log in to your Apple Developer account.
  2. In «Certificates, Identifiers & Profiles», select Identifiers from the sidebar, then select Merchant IDs from the pop-up menu on the top right (make sure you select the merchant identifier you created in Step 1).
  3. On the right, select your merchant identifier.
  4. Under Merchant Domains, click Verify next to the domain, then follow the instructions.

For information about server requirements for Apple Pay on the web, refer to the Apple Developer portal.

Technical integration to mobile application

1. Technical integration via Apple Pay API To integrate Apple Pay to your mobile application, follow the instruction

2. Technical integration via Tranzzo API Send the payment data to Tranzzo API. Use the request parameters from Tranzzo documentation

Technical integration to web

Technical integration via Apple Pay API

Verify your device or browser supports Apple Pay:

if (window.ApplePaySession) {
  console.log("The Apple Pay JS API is available.");

  const canMakePayments = ApplePaySession.canMakePayments();
  console.log("canMakePayments: " + JSON.stringify(canMakePayments));

  const merchantIdentifier = {MERCHANT_IDENTIFIER};
  ApplePaySession
    .canMakePaymentsWithActiveCard(merchantIdentifier);
    .then(canMakePayments => {
      console.log("canMakePayments: " + canMakePayments);
      if (canMakePayments) {...}
    }
}     

To integrate Apple Pay to your website, follow the instruction Check your payment ability with Apple Pay.

1. Verify your device or browser supports Apple Pay.

Make a payment structure for the session:

document.getElementById("apple-pay-button").onclick = event => {
  var paymentRequest = {
    currencyCode: 'UAH',
    countryCode: 'UA',
    total: {
      label: {PRODUCT_NAME},
      amount: {PAYMENT_AMOUNT}
    },
    merchantCapabilities: ['supports3DS'],
    supportedNetworks: ['masterCard', 'visa']
  }

var applePaySession = new ApplePaySession(3, paymentRequest);

2. Make a payment structure for the session.

Validate the merchant:

session.onvalidatemerchant = event => {
  validateMerchant(event.validationURL);
    .then(merchantSession => session.completeMerchantValidation(merchantSession));
}

const validateMerchant = validationURL => {
  const headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  };

  var options = = {
    'POST',
    headers,
    body: JSON.stringify({validation_url: validationURL}),
    credentials: 'same-origin'
  };
  return fetch("https://{MERCHANT_VALIDATION_ENDPOINT}", options)
    .then(resp => resp.json())
};

3. Validate the merchant.

Start the session and process your payment:

applePaySession.onpaymentauthorized = event => {
  const token = JSON.stringify(event.payment.token.paymentData);
  console.log("ApplePayPayment token: " + token);
  // submit token to Tranzzo API
  session.completePayment(ApplePaySession.STATUS_SUCCESS);
}

applePaySession.begin();

4. Start the session and process your payment.

An example of a dataset returned from Apple Pay:

{
  "version":              "EC_v1",
  "data":                 "zTMZDPumdE7h8oY/+31VMZd60dMaxB...",
  "signature":            "MIAGCSqGSIb3DQEHA...",
  "header": {
    "ephemeralPublicKey": "MFkwEwYHKoZIzj0C...",
    "publicKeyHash":      "3AKqH/wPWdQIBpGIv1PC4uDTbGouPgWbmUlFGiHopig=",
    "transactionId":      "d6e63976191fdf051f7cb95e0e5da70a19c99a5576ececbfc0fd65ad2a7f2f74"
  }
}

5. Send the payment data to Tranzzo API. (chapter “Charging”).

Charging

Request example:

curl -v 'https://cpay.tranzzo.com/api/v1/payment' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "X-API-Auth:CPAY $API_KEY:$API_SECRET" \
-H "X-API-Key:$ENDPOINTS_KEY" \
-H 'X-Requested-With: *' \
--data-raw '{
     "pos_id":           "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
     "order_id":         "123",
     "description":      "Goods 123",
     "method":           "auth",
     "amount":           1.50,
     "currency":         "UAH",
     "mode":             "direct",
     "payway":           "applepay",
     "cc_token":         "applepay:eyJ2ZXJzaW9uIjoiRUNfdjEiLC...",
     "order_3ds_bypass": "supported",
     "products":         []
    }'

To charge the payment card stored under Apple 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. You can find the request parameters by the link.

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",
  "payway":               "applepay",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "success",
  "status_code":          "1000",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "applepay:eyJ2ZXJzaW9uIjoiRUNfdjEiLC...",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "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",
  "bank_short_name":      "Bank name"
}

Invalid Applepay token response example:

{
  "message":  "Invalid ApplePay token",
  "args":{    
              "code":     "A-400",
              "error_id": "KcJYneJ1owLPeRL5"
  }
}

Telegram Pay

Telegram™ Pay Integration Guide

About Telegram Pay

If you are owning Telegram Bot you can start accepting payment in several clicks by using Bot Payments API. Find more about Telegram @ Tranzzo here.

Telegram Integration

Test mode

Using Tranzzo Test Bot as a Payment provider is the easiest way to add payment option to your bot. You can do it by yourself and don’t even have to contact Tranzzo team. Follow these steps to make your bot process payments:

From technical point of view you will need to implement the following Telegram API methods:

Most of the libraries provide built-in implementations, e.g.

Language Library
PHP php-telegram-bot
Python python-telegram-bot
.NET Telegram.Bot
Java TelegramBots
Scala bot4s
Golang telegram-bot-api

Production mode

If you have successfully tested payment with Tranzzo Test provider than you are ready to switch to production. All that you need is to create Tranzzo account and reach out our sales.

Custom description

{
    "provider_data": {
        "desc": "Custom description"
    }
}

If you would like to use custom description in Tranzzo you can set it in provider_data parameter in sendInvoice method.

mVisa

mVisa™ Integration Guide

About mVisa

mVisa is the new transformative way to pay with your mobile phone. There's no need to carry cash. Just scan the QR code to make your payments. The mVisa QR Code is a form of a bar code that has the merchant's information (merchant name & account number) required for the payment. You will just need to scan this QR code with the scanner built in the mVisa app to start the payment process.

Before you start

mVisa QR generation

HTTP method: POST

Request example:

$ curl -i "https://cpay.tranzzo.com/api/v1/mvisa?type=${QR_TYPE}" \
    -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}'",
      "amount": 100,
      "currency": "UAH",
      "merchant_pan": "4111111111111111",
      "mcc": "1234",
      "country_code": "UA",
      "merchant_name": "TRANZZO",
      "merchant_city": "Kyiv"
}'

Query parameters

Parameter Type Required Description
type String mVisa QR code type

Generation of mVisa QR code is supported in two formats, depending on the passed type query parameter:

Request parameters

Parameter Type Required Description
pos_id UUID Merchant's identifier (POS_ID)
amount Number Amount for future transaction
currency CURRENCY Currency (ISO_4217)
mcc MCC MCC for future transaction
merchant_pan String PAN number
merchant_name String Merchant name
merchant_city String Merchant city
country_code String Country code (ISO_3166-2)

These parameters are required only if you have not configured them earlier in Tranzzo:

Response parameters for QR code in raw format:

Response example:

{
  "raw": "000201021642424242424242425204123453039805406100.005802UA5907TRANZZO6004Kyiv63044A84"
}
Parameter Type Description
raw String Raw QR code as alpha-numeric string

Response parameters for QR code in png format:

In response for the request to generate QR code in png format the byte representation of the generated QR code will be returned:

mVisa QR processing

Send the payment data to Tranzzo API, use the request parameters from Tranzzo documentation.

Additional parameters should be send:

Parameter Type Required Description
payway String Payway name
properties.mvisa_qr String Raw QR code as alpha-numeric string

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":"YzI3YmJjYTI4ZTU5NDFiYTg5MDNmYTUwNWM5NTY3ZjA6OXFvYmRtS001dElYYVdrWWVE",
      "expires_at":"2023-02-28T00:00:00",
      "card_mask":"411111******1111",
      "issuer":{
        "bank":"JPMORGAN CHASE BANK N.A.",
        "iso_a3_code":"USA",
        "card_type":"CREDIT",
        "payment_system":"VISA"
        }
     }
   */
 }
};

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.
issuer JSON Issuer parameters.

Allowed properties for issuer

Parameter Type Description
bank String Bank name
payment_system String Payment system
card_type String Card type
iso_a3_code String Country code (ISO_3166-2)

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.

Receipts

Request example:

$ curl -i "https://cpay.tranzzo.com/api/v1/pos/${POS_ID}/orders/${ORDER_ID}/report/receipt?format=${FORMAT}" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Response: Raw HTML

Tranzzo provides an endpoint to render a receipt for a specific payment in HTML or PDF formats.

Parameter definitions

Parameter Type Required Description
POS_ID String Merchant's identifier (POS_ID)
ORDER_ID String Merchant's order identifier
FORMAT String Receipt format (html, pdf)

Request example:

$ curl -i "https://cpay.tranzzo.com/api/v1/pos/${POS_ID}/date/${DATE}/report/receipt?format=${FORMAT}" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}"

Response: A zip file with all receipts for the given date.

Also, it is possible to render receipts for all payments for a specific day.

Parameter definitions

Parameter Type Required Description
POS_ID String Merchant's identifier (POS_ID)
DATE String Date in yyyy-MM-dd format
FORMAT String Receipt format (html, pdf)