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

Primary operations

Payment modes

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

hosted - the most popular way to integrate Tranzzo. It provides hosted checkout which can be connected to merchant's project. The request define preferred Payment method and include full Product details and customer information. The user interface can be adjust in merchant's styles and host at merchant's domain name.
direct - seamless integration. Let customer enter card data details on merchant's website or pay by card tokens issued by Tranzzo.

PCI-DSS certification is required in order to use direct mode.

Payment methods

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

purchase - one-step payment. Charges customer's card for specified amount.
auth - two-step payment. Amount is simply hold on payer's card. For actual charging, complete the transaction with capture method.

Customer may see the same message as for purchase. This message is under bank issuer control.

credit - payout operation. Replenishes customer's card with specified amount from merchant's balance.
p2p - money transfer from one card to another.

Secondary operations

Secondary operations are bound to primary.

refund - . Applicable for completed (captures) authorizations and purchases.

capture - confirm hold. Optionally takes an alternative amount (less than hold amount) to be captured.
void - release hold. Declines previously made authorization.

Controlling 3D-Secure flow

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

supported (default) - depends on card 3-D Secure support.
always - transaction will be declined if card does not support 3-D Secure.
never - transaction will be made without 3-D Secure involving.

By default, merchants are allowed to use supported and always only. If merchant needs never flow, please contact integration team.

API

API URL

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

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

Expected response:

OK

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

If these headers were not passed or contain incorrect values then 401 Unauthorized will be returned

Request signing

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

HMAC-SHA1 (recommended)

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}

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.

Although products field is required in API, it can be an empty array ([]).

API statuses

status field can contain the following values:

Status	Description
`initiated`	Transaction was created, but processing has not been started.
`pending`	Transaction is being processed.
`unsuccessful`	Unsuccessful transaction.
`rejected`	Transaction was declined.
`success`	Transaction is successful.

Gateway statuses

status_processing field contains more detailed status from processing gateway:

Status	`status`	Description
`Sandbox`	`success`	Test transaction is successful.
`Success`	`success`	Transaction is successful.
`Pending`	`pending`	Transaction is being processed.
`Antifraud`	`pending`	Transaction is on Antifraud check.
`Hold`	`pending`	Transaction is on Hold.
`Created`	`pending`	Transaction was created and is being processed.
`Unsuccessful`	`rejected`	Unsuccessful transaction.
`Rejected`	`rejected`	Transaction was declined.
`Error`	`rejected`	Failed to process transaction.
`Refund`	`rejected`	Transaction was refunded by gateway.
`Canceled`	`rejected`	Transaction was canceled by gateway.

Hosted payments

$ 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",
      "products": [],
      "server_url": "https://callback.blackhole.com/callback",
      "result_url": "https://example.com/result",
      "payload": "THIS_IS_PAYLOAD"
    }'

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

Request parameters:

Parameter	Type	Required	Description
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`hosted`
`method`	String	✅	Payment method (`purchase`, `auth`)
`amount`	Number	✅	Transaction amount
`currency`	String	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`products`	Array[Product]	✅	Array of products to be paid
`order_id`	String	✅	Unique identified of order
`order_3ds_bypass`	String		3-D Secure flow option
`order_date`	String		Timestamp, when order was created
`order_timeout`	Number		Controls during which time order could 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`	String		Webhook notification will be sent to this URL
`result_url`	String		Customer will be redirected to this URL after payment
`merchant_mcc`	String		MCC for this transaction
`payload`	String		Field for custom data (will be sent in webhook). Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL. See TODO anchor

Direct payments with card data

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",
      "cc_number": "4242424242424242",
      "exp_month": 2,
      "exp_year": 24,
      "card_cvv": "111",
      "products": [],
      "server_url": "https://callback.blackhole.com/callback",
      "result_url": "https://example.com/result",
      "payload": "THIS_IS_PAYLOAD"
    }'

Request parameters:

Parameter	Type	Required	Description
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	Payment method (`purchase`, `auth`)
`amount`	Number	✅	Transaction amount
`currency`	String	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`products`	Array[Product]	✅	Array of products to be paid
`order_id`	String	✅	Unique identified of order
`cc_number`	String	✅	Card number
`exp_month`	Number	✅	Card expiration month field
`exp_year`	Number	✅	Card expiration year field
`card_cvv`	String	✅	Card CVV
`order_3ds_bypass`	String		3-D Secure flow option
`order_date`	String		Timestamp, when order was created
`order_timeout`	Number		Controls during which time order could 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`	String		Webhook notification will be sent to this URL
`result_url`	String		Customer will be redirected to this URL after payment
`merchant_mcc`	String		MCC for this transaction
`payload`	String		Field for custom data (will be sent in webhook). Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL. See TODO anchor

Response example:

{
  "uuid": "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "pos_id": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "created": 1540046568154,
  "mode": "direct",
  "method": "auth",
  "amount": 1,
  "currency": "UAH",
  "description": "description_1",
  "order_id": "123",
  "options_3ds": "supported",
  "user_action_required": true,
  "enrolled_3ds": true,
  "status": "pending",
  "cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "customer_ip": "194.183.171.239",
  "user_action_url": "https://ing.tranzzo.com/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "user_account_id": "041b0c46-8072-43bc-92c4-99c524ba2507",
  "payment_id": "47d82d40-459c-4181-9c1f-43218e981568",
  "transaction_id": "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "cc_mask": "424242******4242",
  "gw_order_id": "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "result_url": "https://example.com/result",
  "code": "2122",
  "code_description": "3DS verification is required to finish the transaction.",
  "status_processing": "Pending"
}

Response parameters:

Parameter	Type	Description
`uuid`	String	Tranzzo unique payment identifier
`pos_id`	String	Merchant's identifier (`POS_ID`)
`created`	number	UNIX Timestamp when payment was created
`mode`	String	`direct`
`method`	String	Payment method (`purchase`, `auth`)
`amount`	Number	Transaction amount
`currency`	String	Transaction currency (ISO_4217)
`description`	String	Payment description
`products`	Array[Product]	Array of products to be paid
`order_id`	String	Unique identifier of order
`options_3ds`	String	3-D Secure flow option
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`enrolled_3ds`	Boolean	Either customer's card is enrolled in 3-D Secure
`status`	String	Transaction status
`user_action_url`	String	If `user_action_required` is `true` then user should be redirected to this URL
`user_account_id`	String	Customer identifier in Tranzzo
`payment_id`	String	Tranzzo payment identifier in billing system
`transaction_id`	String	Tranzzo transaction identifier
`gw_order_id`	String	Unique order identifier in bank acquirer system.
`code`	String	Tranzzo payment status code
`code_description`	String	Tranzzo payment status code description
`status_processing`	String	Tranzzo overall payment status
`cc_mask`	String	Card number mask
`cc_token`	String	Tranzzo card token generated for this card
`order_date`	String	Timestamp, when order was created
`order_timeout`	Number	Controls during which time order could 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`	String	Webhook notification will be sent to this URL
`result_url`	String	Customer will be redirected to this URL after payment
`merchant_mcc`	String	MCC for this transaction
`payload`	String	Field for custom data (will be sent in webhook). Max 4000 symbols.

Direct payments using Tranzzo tokens

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",
      "cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "products": [],
      "server_url": "https://callback.blackhole.com/callback",
      "result_url": "https://example.com/result",
      "payload": "THIS_IS_PAYLOAD"
    }'

Request parameters:

Parameter	Type	Required	Description
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	Payment method (`purchase`, `auth`)
`amount`	Number	✅	Transaction amount
`currency`	String	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`products`	Array[Product]	✅	Array of products to be paid
`order_id`	String	✅	Unique identified of order
`cc_token`	String	✅	Tranzzo card token, obtained from previous payments
`order_3ds_bypass`	String		3-D Secure flow option
`order_date`	String		Timestamp, when order was created
`order_timeout`	Number		Controls during which time order could 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`	String		Webhook notification will be sent to this URL
`result_url`	String		Customer will be redirected to this URL after payment
`merchant_mcc`	String		MCC for this transaction
`payload`	String		Field for custom data (will be sent in webhook). Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL. See TODO anchor

Response example:

{
  "uuid": "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "pos_id": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "created": 1540046568154,
  "mode": "direct",
  "method": "auth",
  "amount": 1,
  "currency": "UAH",
  "description": "description_1",
  "order_id": "123",
  "options_3ds": "supported",
  "user_action_required": true,
  "enrolled_3ds": true,
  "status": "pending",
  "cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "customer_ip": "194.183.171.239",
  "user_action_url": "https://ing.tranzzo.com/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "user_account_id": "041b0c46-8072-43bc-92c4-99c524ba2507",
  "payment_id": "47d82d40-459c-4181-9c1f-43218e981568",
  "transaction_id": "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "cc_mask": "424242******4242",
  "gw_order_id": "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "result_url": "https://example.com/result",
  "code": "2122",
  "code_description": "3DS verification is required to finish the transaction.",
  "status_processing": "Pending"
}

Response parameters:

Parameter	Type	Description
`uuid`	String	Tranzzo unique payment identifier
`pos_id`	String	Merchant's identifier (`POS_ID`)
`created`	number	UNIX Timestamp when payment was created
`mode`	String	`direct`
`method`	String	Payment method (`purchase`, `auth`)
`amount`	Number	Transaction amount
`currency`	String	Transaction currency (ISO_4217)
`description`	String	Payment description
`products`	Array[Product]	Array of products to be paid
`order_id`	String	Unique identified of order
`options_3ds`	String	3-D Secure flow option
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`enrolled_3ds`	Boolean	Either customer's card is enrolled in 3-D Secure
`status`	String	Transaction status
`user_action_url`	String	If `user_action_required` is `true` then user should be redirected to this URL
`user_account_id`	String	Customer identifier in Tranzzo
`payment_id`	String	Tranzzo payment identifier in billing system
`transaction_id`	String	Tranzzo transaction identifier
`gw_order_id`	String	Unique order identifier in bank acquirer system.
`code`	String	Tranzzo payment status code
`code_description`	String	Tranzzo payment status code description
`status_processing`	String	Tranzzo overall payment status
`cc_mask`	String	Card number mask
`cc_token`	String	Tranzzo card token generated for this card
`order_date`	String	Timestamp, when order was created
`order_timeout`	Number	Controls during which time order could 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`	String	Webhook notification will be sent to this URL
`result_url`	String	Customer will be redirected to this URL after payment
`merchant_mcc`	String	MCC for this transaction
`payload`	String	Field for custom data (will be sent in webhook). Max 4000 symbols.

P2P payments

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": "description_1",
      "order_id": "123",
      "cc_number": "4242424242424242",
      "exp_month": 2,
      "exp_year": 24,
      "card_cvv": "111",
      "recipient_cc_number": "5555555555554444",
      "products": [],
      "server_url": "https://callback.blackhole.com/callback",
      "result_url": "https://example.com/result",
      "payload": "THIS_IS_PAYLOAD"
    }'

Request parameters:

Parameter	Type	Required	Description
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	Payment method (`purchase`, `auth`)
`amount`	Number	✅	Transaction amount
`currency`	String	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`products`	Array[Product]	✅	Array of products to be paid
`order_id`	String	✅	Unique identified of transfer
`cc_number`	String	✅	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
`order_date`	String		Timestamp, when order was created
`order_timeout`	Number		Controls during which time order could 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`	String		Webhook notification will be sent to this URL
`result_url`	String		Customer will be redirected to this URL after payment
`merchant_mcc`	String		MCC for this transaction
`payload`	String		Field for custom data (will be sent in webhook). Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL. See TODO anchor

Response example:

{
  "uuid": "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "pos_id": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "created": 1540046568154,
  "mode": "direct",
  "method": "p2p",
  "amount": 1,
  "currency": "UAH",
  "description": "description_1",
  "order_id": "123",
  "options_3ds": "supported",
  "user_action_required": true,
  "enrolled_3ds": true,
  "status": "pending",
  "cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "customer_ip": "194.183.171.239",
  "user_action_url": "https://ing.tranzzo.com/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "user_account_id": "041b0c46-8072-43bc-92c4-99c524ba2507",
  "payment_id": "47d82d40-459c-4181-9c1f-43218e981568",
  "transaction_id": "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "cc_mask": "424242******4242",
  "gw_order_id": "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "result_url": "https://example.com/result",
  "code": "2122",
  "code_description": "3DS verification is required to finish the transaction.",
  "status_processing": "Pending"
}

Response parameters:

Parameter	Type	Description
`uuid`	String	Tranzzo unique payment identifier
`pos_id`	String	Merchant's identifier (`POS_ID`)
`created`	number	UNIX Timestamp when payment was created
`mode`	String	`direct`
`method`	String	Payment method (`purchase`, `auth`)
`amount`	Number	Transaction amount
`currency`	String	Transaction currency (ISO_4217)
`description`	String	Payment description
`products`	Array[Product]	Array of products to be paid
`order_id`	String	Unique identified of transfer
`options_3ds`	String	3-D Secure flow option
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`enrolled_3ds`	Boolean	Either customer's card is enrolled in 3-D Secure
`status`	String	Transaction status
`user_action_url`	String	If `user_action_required` is `true` then user should be redirected to this URL
`user_account_id`	String	Customer identifier in Tranzzo
`payment_id`	String	Tranzzo payment identifier in billing system
`transaction_id`	String	Tranzzo transaction identifier
`gw_order_id`	String	Unique order identifier in bank acquirer system.
`code`	String	Tranzzo payment status code
`code_description`	String	Tranzzo payment status code description
`status_processing`	String	Tranzzo overall payment status
`cc_mask`	String	Card number mask
`cc_token`	String	Tranzzo card token generated for this card
`order_date`	String	Timestamp, when order was created
`order_timeout`	Number	Controls during which time order could 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`	String	Webhook notification will be sent to this URL
`result_url`	String	Customer will be redirected to this URL after payment
`merchant_mcc`	String	MCC for this transaction
`payload`	String	Field for custom data (will be sent in webhook). Max 4000 symbols.

P2P payments using Tranzzo tokens

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": "description_1",
      "order_id": "123",
      "cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "recipient_cc_number": "5555555555554444",
      "products": [],
      "server_url": "https://callback.blackhole.com/callback",
      "result_url": "https://example.com/result",
      "payload": "THIS_IS_PAYLOAD"
    }'

Request parameters:

Parameter	Type	Required	Description
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	Payment method (`purchase`, `auth`)
`amount`	Number	✅	Transaction amount
`currency`	String	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`products`	Array[Product]	✅	Array of products to be paid
`order_id`	String	✅	Unique identified of transfer
`cc_token`	String	✅	Tranzzo card token, obtained from previous payments
`recipient_cc_number`	String	✅	Recipient's card number
`order_3ds_bypass`	String		3-D Secure flow option
`order_date`	String		Timestamp, when order was created
`order_timeout`	Number		Controls during which time order could 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`	String		Webhook notification will be sent to this URL
`result_url`	String		Customer will be redirected to this URL after payment
`merchant_mcc`	String		MCC for this transaction
`payload`	String		Field for custom data (will be sent in webhook). Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL. See TODO anchor

Response example:

{
  "uuid": "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "pos_id": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "created": 1540046568154,
  "mode": "direct",
  "method": "p2p",
  "amount": 1,
  "currency": "UAH",
  "description": "description_1",
  "order_id": "123",
  "options_3ds": "supported",
  "user_action_required": true,
  "enrolled_3ds": true,
  "status": "pending",
  "cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "customer_ip": "194.183.171.239",
  "user_action_url": "https://ing.tranzzo.com/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "user_account_id": "041b0c46-8072-43bc-92c4-99c524ba2507",
  "payment_id": "47d82d40-459c-4181-9c1f-43218e981568",
  "transaction_id": "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "cc_mask": "424242******4242",
  "gw_order_id": "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "result_url": "https://example.com/result",
  "code": "2122",
  "code_description": "3DS verification is required to finish the transaction.",
  "status_processing": "Pending"
}

Response parameters:

Parameter	Type	Description
`uuid`	String	Tranzzo unique payment identifier
`pos_id`	String	Merchant's identifier (`POS_ID`)
`created`	number	UNIX Timestamp when payment was created
`mode`	String	`direct`
`method`	String	Payment method (`purchase`, `auth`)
`amount`	Number	Transaction amount
`currency`	String	Transaction currency (ISO_4217)
`description`	String	Payment description
`products`	Array[Product]	Array of products to be paid
`order_id`	String	Unique identified of transfer
`options_3ds`	String	3-D Secure flow option
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`enrolled_3ds`	Boolean	Either customer's card is enrolled in 3-D Secure
`status`	String	Transaction status
`user_action_url`	String	If `user_action_required` is `true` then user should be redirected to this URL
`user_account_id`	String	Customer identifier in Tranzzo
`payment_id`	String	Tranzzo payment identifier in billing system
`transaction_id`	String	Tranzzo transaction identifier
`gw_order_id`	String	Unique order identifier in bank acquirer system.
`code`	String	Tranzzo payment status code
`code_description`	String	Tranzzo payment status code description
`status_processing`	String	Tranzzo overall payment status
`cc_mask`	String	Card number mask
`cc_token`	String	Tranzzo card token generated for this card
`order_date`	String	Timestamp, when order was created
`order_timeout`	Number	Controls during which time order could 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`	String	Webhook notification will be sent to this URL
`result_url`	String	Customer will be redirected to this URL after payment
`merchant_mcc`	String	MCC for this transaction
`payload`	String	Field for custom data (will be sent in webhook). Max 4000 symbols.

Capture

Capture could be called only for authorizations with success status.

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_amount": 100,
      "order_currency": "UAH",
      "server_url": "https://callback.blackhole.com/callback/capture"
    }'

Request parameters:

Parameter	Type	Required	Description
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured
`order_amount`	Number	✅	Amount of original order
`order_currency`	String	✅	Currency of original order
`server_url`	String		Webhook notification will be sent to this URL

Response example:

{
  "pos_id": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode": "direct",
  "method": "capture",
  "order_id": "123",
  "amount": 100,
  "currency": "UAH",
  "payment_id": "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "pay_request_id": "fdf1a710-8a34-414c-b023-b7e78104301a",
  "status": "success"
}

Response parameters:

Parameter	Type	Description
`pos_id`	String	Merchant's identifier (`POS_ID`)
`mode`	String	`direct`
`method`	String	`capture`
`order_id`	String	Unique identified of order
`amount`	Number	Actually captured amount
`currency`	String	Transaction currency (ISO_4217)
`payment_id`	String	Tranzzo unique capture identifier
`pay_request_id`	String	Tranzzo unique identifier of primary operation
`status`	String	Capture status

Partial capture

Capture could be called only for authorizations with success status.

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": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
      "order_id": "123",
      "order_amount": 100,
      "order_currency": "UAH",
      "charge_amount": 80,
      "server_url": "https://callback.blackhole.com/callback/capture"
    }'

Request parameters:

Parameter	Type	Required	Description
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured
`order_amount`	Number	✅	Amount of original order
`order_currency`	String	✅	Currency of original order
`charge_amount`	Number	✅	Optional amount to be captured
`server_url`	String		Webhook notification will be sent to this URL

Response example:

{
  "pos_id": "$dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode": "direct",
  "method": "capture",
  "order_id": "123",
  "amount": 80,
  "currency": "UAH",
  "payment_id": "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "pay_request_id": "fdf1a710-8a34-414c-b023-b7e78104301a",
  "status": "success"
}

Response parameters:

Parameter	Type	Description
`pos_id`	String	Merchant's identifier (`POS_ID`)
`mode`	String	`direct`
`method`	String	`capture`
`order_id`	String	Unique identified of order
`amount`	Number	Actually captured amount
`currency`	String	Transaction currency (ISO_4217)
`payment_id`	String	Tranzzo unique capture identifier
`pay_request_id`	String	Tranzzo unique identifier of primary operation
`status`	String	Capture status

Void

Capture could be called only for authorizations with success status.

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": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
      "order_id": "123",
      "order_amount": 100,
      "order_currency": "UAH",
      "server_url": "https://callback.blackhole.com/callback/capture"
    }'

Request parameters:

Parameter	Type	Required	Description
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured
`order_amount`	Number	✅	Amount of original order
`order_currency`	String	✅	Currency of original order
`server_url`	String		Webhook notification will be sent to this URL

Response example:

{
  "pos_id": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode": "direct",
  "method": "void",
  "order_id": "123",
  "amount": 80,
  "currency": "UAH",
  "payment_id": "9b13e2e3-bce1-472f-aa16-675e34987277",
  "pay_request_id": "8df1e61c-7b08-4614-8c5e-8cc0eab15338",
  "status": "success"
}

Response parameters:

Parameter	Type	Description
`pos_id`	String	Merchant's identifier (`POS_ID`)
`mode`	String	`direct`
`method`	String	`void`
`order_id`	String	Unique identified of order
`amount`	Number	Voided amount
`currency`	String	Transaction currency (ISO_4217)
`payment_id`	String	Tranzzo unique void identifier
`pay_request_id`	String	Tranzzo unique identifier of primary operation
`status`	String	Void status

Refund

Refunds could be called only for transactions with success status (authorizations should be captured).

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": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
      "order_id": "123",
      "order_amount": 100,
      "order_currency": "UAH",
      "server_url": "https://callback.blackhole.com/callback/capture"
    }'

Request parameters:

Parameter	Type	Required	Description
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured
`order_amount`	Number	✅	Amount of original order
`order_currency`	String	✅	Currency of original order
`server_url`	String		Webhook notification will be sent to this URL

Response example:

{
  "pos_id": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode": "direct",
  "method": "capture",
  "order_id": "123",
  "amount": 100,
  "currency": "UAH",
  "payment_id": "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "pay_request_id": "fdf1a710-8a34-414c-b023-b7e78104301a",
  "status": "success"
}

Response parameters:

Parameter	Type	Description
`pos_id`	String	Merchant's identifier (`POS_ID`)
`mode`	String	`direct`
`method`	String	`refund`
`order_id`	String	Unique identified of order
`amount`	Number	Actually refunded amount
`currency`	String	Transaction currency (ISO_4217)
`payment_id`	String	Tranzzo unique refund identifier
`pay_request_id`	String	Tranzzo unique identifier of primary operation
`status`	String	Refund status

Partial refund

Refunds could be called only for transactions with success status (authorizations should be captured).

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": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
      "order_id": "123",
      "order_amount": 100,
      "order_currency": "UAH",
      "refund_amount": 80,
      "server_url": "https://callback.blackhole.com/callback/capture"
    }'

Request parameters:

Parameter	Type	Required	Description
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured
`order_amount`	Number	✅	Amount of original order
`order_currency`	String	✅	Currency of original order
`refund_amount`	Number	✅	Amount to be refunded
`server_url`	String		Webhook notification will be sent to this URL

Response example:

{
  "pos_id": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode": "direct",
  "method": "capture",
  "order_id": "123",
  "amount": 80,
  "currency": "UAH",
  "payment_id": "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "pay_request_id": "fdf1a710-8a34-414c-b023-b7e78104301a",
  "status": "success"
}

Response parameters:

Parameter	Type	Description
`pos_id`	String	Merchant's identifier (`POS_ID`)
`mode`	String	`direct`
`method`	String	`refund`
`order_id`	String	Unique identified of order
`amount`	Number	Actually refunded amount
`currency`	String	Transaction currency (ISO_4217)
`payment_id`	String	Tranzzo unique refund identifier
`pay_request_id`	String	Tranzzo unique identifier of primary operation
`status`	String	Refund status

Get order transactions

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/pos/${POS_ID}/order/${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.

Path parameters:

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

Response example:

[
    {
        "amount": 0.01,
        "cc_mask": "424242******4242",
        "cc_token": "ODJkZjBhNmY2OTSyNDJlQ2JQQQFjOTQzODU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
        "code": "1000",
        "code_description": "Transaction is successful.",
        "created": 1540186115409,
        "currency": "UAH",
        "customer_ip": "8.8.8.8",
        "description": "Description",
        "eci": "7",
        "enrolled_3ds": false,
        "gw_order_id": "54E9221016E2F2120F1111173EF6D66:158927341",
        "method": "purchase",
        "mode": "direct",
        "options_3ds": "never",
        "order_id": "123",
        "payment_id": "e90387a2-1b49-4eb8-8aac-31df39166235",
        "pos_id": "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
        "result_url": "http://www.interkassa.com/result",
        "status": "success",
        "status_processing": "Success",
        "transaction_id": "d6331537-d569-4640-b930-f1b56740a774",
        "user_action_required": false,
        "uuid": "e1b9d97e-8f93-41f4-bbe6-866c7ee45676"
    },
    {
        "amount": 0.01,
        "currency": "UAH",
        "method": "refund",
        "mode": "direct",
        "order_id": "123",
        "pay_request_id": "e1b9d97e-8f93-41f4-bbe6-866c7ee45676",
        "payment_id": "d18be9ef-f131-4975-8808-3b14517e5e6a",
        "pos_id": "289e336f-46ae-443e-8235-a123eeb23715",
        "status": "success"
    }
]

Response structure:

Response contains Array of transactions with the same structure as in Create payment section.

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.

Path parameters:

Parameter	Type	Required	Description
`POS_ID`	String	✅	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 Array of transactions with the same structure as in Create payment section.

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} in webhook format.

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

Resend webhook for operation

Request example:

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

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

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

Query parameters:

Parameter	Type	Required	Description
`callback`	Boolean	✅	`true`

Payload

Example of Base64-encoded payload

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

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

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

Webhooks

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

Webhook structure

Example of webhook

data=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A
signature=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A

Form parameters:

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

Webhook verification

Signature calculation example:

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

signature='SofZuIZm73p2wn9zToHUcKm0EVM=' # base64url(sha1($secret + $data + secret))

Signature calculation algorithm: signature=base64url(sha1(${API_SECRET} + ${data} + ${API_SECRET}))

Primary operation webhook parameters

Primary operation webhook structure

{
  "eci" : "7",
  "mode" : "direct",
  "amount" : 0.28,
  "method" : "auth",
  "payway" : "privat24",
  "pos_id" : "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "status" : "success",
  "cc_mask" : "424242******4242",
  "created" : "2018-10-10T10:10:10.100",
  "user_id" : "9f67af86-66ab-308c-78f2-824843763270",
  "cc_token" : "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
  "currency" : "UAH",
  "order_id" : "111999991",
  "payment_id" : "c4939398-1dad-4b92-1c34-7f6802379180",
  "customer_id" : "123",
  "gw_order_id" : "6320ac9a-aaaa-4912-adb3-5bca2dd560fe",
  "response_code" : "1000",
  "response_description" : "Transaction is successful."
  "customer_phone" : "+380999999999",
  "transaction_id" : "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "processing_time" : "2018-10-10T10:10:22.100",
  "provider_order_id" : "123"
}

Parameter	Type	Description
`eci`	String	Electronic Commerce Indicator (ECI) - authentication result of credit card payment on 3D Secure
`mode`	String	Payment mode
`amount`	Number	Transaction amount
`method`	String	Payment method
`payway`	String	Optional payway TODO: Add payways
`pos_id`	String	Merchant's identifier (`POS_ID`)
`status`	String	Transaction status
`cc_mask`	String	Card number mask
`created`	String	Timestamp when transaction was created
`user_id`	String	Customer identifier in Tranzzo
`cc_token`	String	Tranzzo card token
`currency`	String	Transaction currency
`order_id`	String	Tranzzo billing identifier
`payment_id`	String	Tranzzo unique payment identifier
`customer_id`	String	Customer identifier in merchant's system
`gw_order_id`	String	Unique order identifier in bank acquirer system.
`response_code`	String	Tranzzo payment status code
`response_description`	String	Tranzzo payment status code description
`customer_phone`	String	Customer phone
`transaction_id`	String	Tranzzo transaction identifier
`processing_time`	String	Timestamp when transaction was updated last time
`provider_order_id`	String	Unique identifier of order

Secondary operation webhook parameters

Capture webhook

Capture webhook structure:

{
  "pos_id" : "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode" : "direct",
  "method" : "capture",
  "order_id" : "123",
  "amount" : 100,
  "currency" : "UAH",
  "payment_id" : "0f246465-f720-41a8-8f7c-f4af7fe61e8e",
  "pay_request_id" : "c4939398-1dad-4b92-1c34-7f6802379180",
  "transaction_id" : "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "status" : "success",
  "response_code" : "1000",
  "response_description" : "Transaction is successful.",
  "processing_time": "2018-10-10T10:10:22.100"
}

Capture webhook parameters:

Parameter	Type	Description
`pos_id`	String	Merchant's identifier (`POS_ID`)
`mode`	String	`direct`
`method`	String	`capture`
`amount`	Number	Actual capture amount
`currency`	String	Transaction currency
`payment_id`	String	Tranzzo unique payment identifier
`pay_request_id`	String	Tranzzo unique identifier of primary operation
`transaction_id`	String	Tranzzo transaction identifier
`status`	String	Transaction status
`response_code`	String	Tranzzo payment status code
`response_description`	String	Tranzzo payment status code description
`processing_time`	String	Timestamp when transaction was updated last time

Void webhook

Void webhook structure:

{
  "pos_id" : "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode" : "direct",
  "method" : "void",
  "order_id" : "123",
  "amount" : 100,
  "currency" : "UAH",
  "payment_id" : "ec33fe81-8785-4976-8bd4-ee397dd02fde",
  "pay_request_id" : "c4939398-1dad-4b92-1c34-7f6802379180",
  "transaction_id" : "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "status" : "success",
  "response_code" : "1009",
  "response_description" : "Reverse successful.",
  "processing_time": "2018-10-10T10:10:22.100"
}

Void webhook parameters:

Parameter	Type	Description
`pos_id`	String	Merchant's identifier (`POS_ID`)
`mode`	String	`direct`
`method`	String	`void`
`amount`	Number	Void amount
`currency`	String	Transaction currency
`payment_id`	String	Tranzzo unique payment identifier
`pay_request_id`	String	Tranzzo unique identifier of primary operation
`transaction_id`	String	Tranzzo transaction identifier
`status`	String	Transaction status
`response_code`	String	Tranzzo payment status code
`response_description`	String	Tranzzo payment status code description
`processing_time`	String	Timestamp when transaction was updated last time

Refund webhook

Refund webhook structure:

{
  "pos_id" : "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode" : "direct",
  "method" : "refund",
  "order_id" : "123",
  "amount" : 100,
  "currency" : "UAH",
  "payment_id" : "65ab3604-e03d-43c7-a9ad-f519dac1b816",
  "pay_request_id" : "c4939398-1dad-4b92-1c34-7f6802379180",
  "transaction_id" : "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "status" : "success",
  "response_code" : "1004",
  "response_description" : "Refund successful.",
  "processing_time": "2018-10-10T10:10:22.100"
}

Capture webhook parameters:

Parameter	Type	Description
`pos_id`	String	Merchant's identifier (`POS_ID`)
`mode`	String	`direct`
`method`	String	`refund`
`amount`	Number	Actual refund amount
`currency`	String	Transaction currency
`payment_id`	String	Tranzzo unique payment identifier
`pay_request_id`	String	Tranzzo unique identifier of primary operation
`transaction_id`	String	Tranzzo transaction identifier
`status`	String	Transaction status
`response_code`	String	Tranzzo payment status code
`response_description`	String	Tranzzo payment status code description
`processing_time`	String	Timestamp when transaction was updated last time

Tranzzo card tokens

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

Error codes

TODO REPHRASE

Status codes from TRANZZO:

Code	Status	Description
0	Sandbox	Test transaction
1000	Success	Transaction successful
1001	Success	Transaction is successful, it will be transferred in daily settlement
1002	Hold	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	Refund	Reversal successful
1005	Success	Subscription successful
1006	Success	Unsubscribed successfully
1007	Hold	Amount was successfully blocked on the sender's account
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
2003	Rejected	Wrong PIN
2004	Rejected	Wrong amount
2005	Rejected	Wrong authorization code
2006	Rejected	Wrong CAVV
2007	Rejected	Wrong CVV2
2008	Rejected	Internal error. Please try again.
2009	Rejected	Wrong account number
2010	Pending	Capture required
2100	Pending	3DS verification is required to finish the transaction.
2101	Pending	CVV is required
2102	Pending	OTP confirmation is required. OTP is sent to a customer phone number.
2103	Pending	Receiver info required
2104	Pending	Sender info required
2105	Pending	Missed payout method data
2106	Pending	Waiting for verification via captcha
2107	Pending	Waiting for verification via IVR call
2108	Pending	Waiting for verification via Privat24
2109	Pending	Waiting for customer's phone number verification
2110	Pending	Waiting for customer's pin-code verification
2111	Pending	Waiting for verification via SENDER app
2112	Pending	Waiting for verification via QR code
2113	Pending	Waiting for transaction verification via Privat24/SENDER application
2114	Pending	Waiting for transaction complete in Privat24
2115	Pending	Waiting for transaction complete in MasterPass
2116	Pending	Waiting for cash transaction at Self-Service Machine
2117	Created	Invoice is created successfully, waiting for a transaction.
2118	Created	Transaction is created successfully, waiting for sender to complete.
2119	Pending	Transaction is processing
2120	Pending	Authorization required
2121	Rejected	Card verification is required.
4000	Rejected	Invalid data. Missed required input fields
4001	Rejected	Payment card expired
4002	Rejected	Incorrect refund sum or currency
4003	Rejected	Payment card has invalid status
4004	Rejected	Wrong data used at `Info` input.
4005	Unsuccessful	Internal error
4006	Rejected	Internal error
4007	Rejected	Internal error. Please try again.
4008	Rejected	Wrong card number
4009	Unsuccessful	Insufficient funds
4010	Unsuccessful	Transaction limit exceeded. Try another card.
4011	Unsuccessful	Internal error
4012	Unsuccessful	Transaction amount limit exceeded. Try another card.
4013	Unsuccessful	Internal error
4014	Unsuccessful	Internal error
4015	Unsuccessful	Internal error
4016	Unsuccessful	Internal error
4017	Unsuccessful	Internal error
4018	Pending	PIN tries exceeded. Capture is required.
4019	Pending	Card expired
4020	Rejected	Payment card has constraints
4100	Pending	User not found
4101	Pending	Failed to send sms
4102	Pending	Wrong sms password
4103	Rejected	Card not found in wallet for receiving payments.
4104	Rejected	This card payment system is not supported. Please enter another card.
4105	Rejected	Invalid card type.
4106	Rejected	This country is not supported. Please enter another card.
4107	Rejected	Amount of transaction is more or less than the limit.
4108	Rejected	Amount of transaction is more or less than the limit.
4109	Rejected	Transaction amount limit is exceeded.
4110	Rejected	Please, enter sender's another card.
4111	Rejected	No discount found for the transaction.
4112	Rejected	Failed to load the wallet.
4113	Rejected	Invalid verification code.
4114	Unsuccessful	Additional information is pending. Please, try later.
4115	Rejected	Split amount is not equal to transaction amount.
4116	Rejected	Transaction is not recurring.
4117	Rejected	Transaction currency does not match with debit currency.
4118	Rejected	Capture amount cannot be more than the transaction amount.
4119	Rejected	Such `order_id` already exists in the system.
4120	Rejected	Parameter is empty.
4121	Rejected	`Phone` parameter is empty.
4122	Rejected	Parameter is not transferred.
4123	Rejected	Invalid parameter.
4124	Rejected	Invalid currency. Please use: USD, UAH, RUB, EUR.
4125	Rejected	Invalid phone number.
4126	Rejected	Invalid card number.
4127	Rejected	Card bin is not found.
4128	Rejected	Currency exchange rate is not found.
4129	Rejected	Invalid recipient name.
4130	Unsuccessful	Daily card usage limit reached.
4131	Rejected	Such `order_id` already exists in the system.
4132	Rejected	Transaction for this country are forbidden.
4133	Rejected	Expired card.
4134	Rejected	Invalid card number
4135	Rejected	Card does not support such transaction type.
4136	Rejected	Card does not support such transaction type.
4137	Unsuccessful	Insufficient funds.
4138	Unsuccessful	Transaction amount limit is exceeded.
4139	Rejected	Invalid transaction amount.
4140	Rejected	Transaction is declined. Please check if the card details are correct.
4141	Unsuccessful	OTP confirmation timeout
4142	Unsuccessful	Transaction amount limit is exceeded.
4143	Unsuccessful	Transaction amount limit is exceeded.
4144	Unsuccessful	Invalid card data
4145	Unsuccessful	Privat24 confirmation timeout
4146	Unsuccessful	SenderApp confirmation timeout
4147	Unsuccessful	3-D Secure verification timeout
5000	Rejected	Invalid operation
5001	Rejected	The transaction has incorrect attributes or this operation is prohibited.
5002	Rejected	Payment rejected. Please contact support.
5003	Unsuccessful	Internal error
5004	Unsuccessful	Transaction is not supported by provider
5005	Unsuccessful	Internal error
5009	Unsuccessful	Internal error
5010	Rejected	Internal error
5014	Unsuccessful	Authorization error. Please contact support.
5015	Unsuccessful	Internal error
5019	Unsuccessful	Internal error
5020	Unsuccessful	Internal error
5021	Unsuccessful	Authorization error. Contact issuer bank
5022	Rejected	This card type is not supported
5023	Unsuccessful	Timeout
5024	Unsuccessful	Internal error
5025	Unsuccessful	Internal error
5026	Unsuccessful	Internal error
5027	Unsuccessful	Internal error
5028	Unsuccessful	Internal error
5029	Unsuccessful	Transaction is not supported. Please contact customer support service
5030	Unsuccessful	Internal error
5102	Unsuccessful	Transaction cache data timeout
5103	Unsuccessful	Store is blocked
5104	Unsuccessful	Store is not active
5105	Unsuccessful	Wrong request signature
5106	Rejected	Order_id is empty
5107	Rejected	You are not the agent of the specified store
5108	Rejected	User doesn't have a card with such token.
5109	Rejected	Invalid request url.
5110	Rejected	Transaction cannot be processed
5111	Rejected	Receiver didn't set the card to receive transactions.
5112	Rejected	Invalid transaction status.
5113	Rejected	`Public_key` is not found.
5114	Rejected	Transaction is not found.
5115	Rejected	Access error
5116	Rejected	Access to account is blocked.
5117	Rejected	Terminal is not found.
5118	Rejected	Fee is not found.
5119	Rejected	Failed to create transaction.
5120	Rejected	Failed to verify a card.
5121	Rejected	Currency is prohibited.
5122	Unsuccessful	Failed to finish the transaction.
5123	Unsuccessful	Failed to finish the transaction
5124	Rejected	Invalid transaction type.
5125	Rejected	Transaction currency is prohibited.
5126	Rejected	Invalid transaction request signature.
5127	Rejected	`Action` parameter is not sent in request.
5128	Rejected	`Callback` parameter is not transferred.
5129	Rejected	This merchant is restricted to call API from this IP.
5130	Unsuccessful	Card does not support 3-D Secure.
5131	Rejected	General error during processing.
5132	Unsuccessful	Token doesn't belong to this merchant.
5133	Rejected	Received token is inactive.
5134	Unsuccessful	Token reached the maximum purchase amount.
5135	Unsuccessful	Token transactions' limit exceeded.
5136	Rejected	Card not supported.
5137	Rejected	Merchant is not allowed preauth.
5138	Unsuccessful	Acquirer does not support 3-D Secure.
5139	Rejected	This token does not exist.
5140	Rejected	Reached the limit of attempts for this IP.
5141	Rejected	Session expired.
5142	Rejected	Card branch is blocked.
5143	Rejected	Card branch daily limit reached.
5144	Rejected	Temporarily closed the P2P transactions from PB cards to foreign banks' cards.
5145	Unsuccessful	Completion limit reached.
5146	Unsuccessful	Transaction is declined. Please, try again later.
5147	Unsuccessful	Transaction is declined. Bank did not approve the transaction. Please, contact the bank.
5148	Unsuccessful	Bank did not approve the transaction. Please, contact the bank.
5149	Rejected	Invalid parameters or transaction is not allowed.
5150	Rejected	Merchant is not allowed for making recurring transactions.
5151	Canceled	Transaction is canceled by payer.
6000	Antifraud	Transaction is on antifraud check
6003	Antifraud	The transaction is declined by bank's anti-fraud system.
6001	Antifraud	The limit for the amount or number of customer payments has been exceeded. Amount or transaction limit has been exceeded.
6002	Antifraud	The transaction is rejected by bank's anti-fraud rules.
6004	Antifraud	Payment card is lost or stolen

HTTP statuses

Tranzzo API uses the following HTTP statuses:

HTTP 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.

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

Contact maintainers

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