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
:
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.
Primary operations
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 withcapture
method.
credit
- payout operation. Replenishes customer's card with specified amount from merchant's balance.p2p
- money transfer from one card to another.
lookup
- card authorization method that means blocking of the amount up to 1 usd for up to 30 days to verify the validity of the client's card. To check card validation you are sending request for card authorization with the amount. To verify that the card belongs to the client, a dynamic authorization code is used.
Secondary operations
Secondary operations are bound to primary.
refund
- return full or partial amount of captured transaction.
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.
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.
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}
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. |
customer_lang
supported values: "EN", "ES", "PL", "AR", "AZ", "BG", "CS", "DA", "DE", "EL", "FA", "FI", "FR", "HE", "HI", "HR", "HU", "IT", "JA", "KO", "NL", "NO", "PT", "PT_BR", "RO", "SK", "SL", "SR", "Ї", "SV", "TH", "TR", "UK", "ZH", "ZH_HA"
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 | ✅ | Use "privat_payparts" for processing direct payments through Privat Payment by Parts |
properties.part_counts |
String | ✅ | The number of parts into which the payment amount is divided (must be > 1 and <= 25) |
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": 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 |
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 Mono Payment by Parts
Payment by Parts from Mono 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 Monobank card. Details are here: https://chast.monobank.ua/
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": "mono_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 | ✅ | Use "mono_payparts" for processing direct payments through Mono Payment by Parts |
products |
Array[Product] | ✅ | Array of products to be paid |
properties.part_counts |
String | ✅ | The number of parts into which the payment amount is divided (must be > 1 and <= 25) |
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": 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": "mono_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 |
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
- Implement secondary operations
- Ensure that all Tranzzo transactions go through your regular risk input validation and checks, just like any other transaction that you handle
- iframe-based Checkout Pages. Even though Tranzzo’s checkout page has HTTPS, end users would see the merchant's website address in the browser URL. If you use HTTP, end users may think they are entering the credit card on an insecure page. Though not mandatory from the compliance point of view, we strongly recommend using HTTPS for iframe-based checkout pages to ensure better checkout experience for end users
- Provide copy of successful request and response for all operations (test a successful transaction for each of the payment flows where Checkout is implemented)
- Checkout button is properly placed on all required pages e.g., Shopping cart, Payment page, etc. (Per Branding Requirements)
- You are using Production credentials
- Provide Tranzzo team with your SVG logo that can be placed in Partner's page
HOSTED METHOD
- Integrate a payment widget. It should be accessible on your website/application
- Customer details must be persistent and unique per user account
DIRECT METHOD
- Payment page must be served via HTTPS
- Client-side tokenization using widget.js
- Customer details must be persistent and unique per user
- The following parameters should be passed in TRZ API requests:
fingerprint
customer_ip
customer_fname
customer_lname
- Your servers must not persist customer's credit card data
- Recurring billing
- Website clearly shows recurring billing conditions
- Cancellation and refund policy is clearly accessible and visible in the website
CALLBACKS/WEBHOOKS
- Set up a webhook endpoint in your server
- Webhook Testing
- If webhook was processed successfully your server should response with
200 OK
- Callback system properly rejects duplicates
- Webhook with wrong signature are rejected
- If webhook was processed successfully your server should response with
- Confirm that the webhooks are being handled
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 only
- Supported currency - INR
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 and Pay Out
- Supported currency - INR
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 and Pay Out
- Supported currency - INR
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 and Pay Out
- Supported currency - INR
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 and Pay Out
- Supported currency - INR
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 and Pay Out
- Supported currency - INR
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 and Pay Out
- Supported currency - INR
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 and Pay Out
- Supported currency - IDR
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 and Pay Out
- Supported currency - MYR
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 only
- Supported currency - PHP
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 and Pay Out
- Supported currency - KRW
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 only
- Supported currency - VND
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 and Pay Out
- Supported currency - VND
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 and Pay Out
- Supported currency - VND
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 only
- Supported currency - BRL
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 only
- Supported currency - BRL
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 and Pay Out
- Supported currency - BRL
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 only
- Supported currency - BRL
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 and Pay Out
- Supported currency - BRL
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 and Pay Out
- Supported currency - BRL
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:
- Merchant creates
hosted
payment - User is redirected to Checkout page
- User submits card data
- Tranzzo sends Preflight request to
validation_url
if it was defined - If endpoint responses with
200 OK
and content isPROCEED
, then Tranzzo starts the transaction. Otherwise, payment is cancelled and webhook withfailure
status is sent toserver_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:
35.187.74.148
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
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:
- via Tranzzo checkout page
- via Google Pay API
Card networks currently supported: Visa and Mastercard available for EU, Ukraine, and region specific Prostir for Ukraine.
Integration
Integration via Tranzzo checkout page
Before you start
- Please make sure you are registered with Tranzzo as a merchant.
- Adhere to Google Pay API Acceptable Use Policy and Terms of service
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
- You should register with Google Pay API to proceed with this integration option
- Your website should use HTTPS and support TLS protocol
- You should be registered with Tranzzo as a merchant
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:
- API documentation for mobile application and for website
- Brand guidelines for mobile application and for website
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:
"payway": "gpay"
"cc_token": "gpay:${base64_google_encrypted_token}"
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:
- via Tranzzo checkout page
- via Apple Pay API
Before you start
- Please make sure you are registered with Tranzzo as a merchant.
- Follow the Acceptable Use Guidelines for Apple Pay on the web
- Your website should use HTTPS and support TLS protocol
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:
- An Apple Developer account that is associated with either the Apple Developer Program, or the Apple Developer Enterprise Program.
- An individual Merchant ID that identifies you to Apple Pay as a merchant who is able to accept payments.
- Brand guidelines reviewed and accepted.
Step 1: Create your merchant identifier
- Log in to your Apple Developer account
- Go to «Certificates, Identifiers & Profiles» tab
- At the section «Identifiers» choose «Merchant IDs»
- Add a new Merchant ID by clicking “+” at the top right corner of the page
- Fill the requested fields and click «Continue»
- Tap «Register» to confirm the data.
Step 2: Create a merchant identity certificate
- In «Certificates, Identifiers & Profiles», select Identifiers from the sidebar, then select Merchant IDs from the pop-up menu on the top right.
- On the right, select your merchant identifier.
- Under Apple Pay Merchant Identity Certificate, click Create Certificate.
- Create a certificate signing request on your Mac, and click Continue.
- Click Choose File.
- In the dialog that appears, select the certificate request file (a file with a .certSigningRequest file extension), then click Choose.
- Click Continue.
- Click Download.
- 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.
- Log in to your Apple Developer account.
- 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).
- On the right, select your merchant identifier.
- Under Merchant Domains, click Add Domain.
- Enter the fully qualified domain name, then click Save.
- Click Download, place the downloaded file in the specified location, then click Verify.
- Click Done.
Step 4: Verify your merchant domain
- Log in to your Apple Developer account.
- 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).
- On the right, select your merchant identifier.
- 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
"payway": "applepay",
"mode": "direct",
"cc_token": "applepay:${base64_applepay_encrypted_token}"
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:
"payway": "applepay",
"mode": "direct",
"cc_token": "applepay:${base64_applepay_encrypted_token}"
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:
- Go to @BotFather
- Type
/mybots
command - Select bot for which you would like to accept payments
- Select
Payments
>Tranzzo
>Connect Tranzzo Test
- Click
Connect TRANZZO
button and you are done! - Now in @BotFather you would see
Tranzzo Test
as a connected method
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
- Please make sure you are registered with Tranzzo as a merchant.
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:
raw
- alpha-numeric stringpng
- PNG 294х294 px
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:
mcc
merchant_pan
merchant_name
merchant_city
country_code
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:
- QR code size:
294 x 294
px - Content-type:
application/octet-stream
mVisa QR processing
Send the payment data to Tranzzo API, use the request parameters from Tranzzo documentation.
Additional parameters should be send:
"payway": "mvisa",
"properties": { "mvisa_qr": "000201021642424242424242425204123453039805406100.005802UA5907TRANZZO6004Kyiv63044A84" }
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) |