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 with capture method.

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

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

Retrying credit or p2p operations are allowed only after receiving final unsuccessful status. In case of timeout you should use status polling api to find out current status of operation.

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.

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

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.

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

Request signing

Requests to Tranzzo could be optionally signed, it is recommended. In this case, header X-API-AUTH should be 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.

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

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

HTTP method: POST

Request parameters

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "4242424242424242",
      "exp_month":        2,
      "exp_year":         24,
      "card_cvv":         "111",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`auth` or `purchase`)
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`cc_number`	CC_NUMBER	✅	Card number
`exp_month`	Number	✅	Card expiration month field
`exp_year`	Number	✅	Card expiration year field
`card_cvv`	String	✅	Card CVV
`products`	Array[Product]		Array of products to be paid
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String	✅	Customer email
`customer_phone`	String	✅	Customer phone
`customer_ip`	String	✅	Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for merchant custom data. Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
`cryptogram`	Json		Cryptogram parameters.
`customer_referrer`	URL		Page customer is redirected from.

Response parameters

Response example:

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

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

Direct payments using Privat24

HTTP method: POST

Request parameters

Request example:

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

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

Response parameters

Response example:

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

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

Direct payments using Privat Payment by Parts

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

HTTP method: POST

Request parameters

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           300,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "payway":           "privat_payparts",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "properties":       {
        "part_counts": 2
      },
      "products":         [
        {
          "name"    : "Apple",
          "amount"  : 100,
          "currency": UAH,
          "qty"     : 2
        },
        {
          "name"    : "Pineapple",
          "amount"  : 100,
          "currency": UAH,
          "qty"     : 1
        }
      ]
    }'

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	Payment method (`auth` or `purchase`)
`amount`	Number	✅	Transaction amount (must be > 300 UAH)
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of order
`order_3ds_bypass`	String	✅	3-D Secure flow option
`payway`	String	✅	Optional payway. Use "privat_payparts" for processing direct payments through Privat Payment by Parts
`products`	Array[Product]		Array of products to be paid
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String	✅	Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for merchant custom data. Max 4000 symbols.
`validation_url`	String		Preflight request will be sent to this URL
`properties.parts_count`	String		The number of parts into which the payment amount is divided (must be > 1 and <= 25)

Response parameters

Response example:

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

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

Direct payments using Tranzzo tokens

HTTP method: POST

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "UAH",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_token":         "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Request parameters

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

Response example:

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

Response parameters

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

P2P payments

HTTP method: POST

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":              "${POS_ID}",
      "mode":                "direct",
      "method":              "p2p",
      "amount":              1,
      "currency":            "UAH",
      "description":         "P2P description",
      "order_id":            "123",
      "order_3ds_bypass":    "always",
      "cc_number":           "4242424242424242",
      "exp_month":           2,
      "exp_year":            24,
      "card_cvv":            "111",
      "recipient_cc_number": "5555555555554444",
      "server_url":          "https://callback.blackhole.com/callback",
      "result_url":          "https://example.com/result",
      "payload":             "sale=true",
      "external_fee":        0.05,
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Request parameters

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

Response example:

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

Response parameters

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

P2P payments using Tranzzo tokens

HTTP method: POST

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":              "${POS_ID}",
      "mode":                "direct",
      "method":              "p2p",
      "amount":              1,
      "currency":            "UAH",
      "description":         "P2P description",
      "order_id":            "123",
      "order_3ds_bypass":    "always",
      "cc_token":            "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "recipient_cc_number": "5555555555554444",
      "server_url":          "https://callback.blackhole.com/callback",
      "result_url":          "https://example.com/result",
      "payload":             "sale=true",
      "external_fee":        0.05,
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "uk-UA",
          "browserTimeZone":         "Europe/Kiev",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Request parameters

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	`p2p`
`amount`	Number	✅	Transaction amount
`currency`	CURRENCY	✅	Transaction currency (ISO_4217)
`description`	String	✅	Payment description
`order_id`	String	✅	Unique identifier of transfer
`cc_token`	CC_TOKEN	✅	Tranzzo card token, obtained from previous payments
`recipient_cc_token`	CC_TOKEN	✅	Tranzzo card token, obtained from previous payments. Note: you can use recipient_cc_number instead
`order_3ds_bypass`	String	✅	3-D Secure flow option
`customer_id`	String		Customer identifier in merchant's system
`customer_fname`	String		Customer first name
`customer_lname`	String		Customer last name
`customer_email`	String		Customer email
`customer_phone`	String		Customer phone
`customer_ip`	String	✅	Customer IP address
`customer_country`	String		Customer country
`server_url`	URL		Webhook notification will be sent to this URL
`result_url`	URL		Customer will be redirected to this URL after payment.
`merchant_mcc`	MCC		MCC for this transaction
`payload`	String		Field for custom data. Max 4000 symbols.
`validation_url`	URL		Preflight request will be sent to this URL
`external_fee`	Number		Transaction external fee. Note: usage of the parameter requires an approval
`browser_fingerprint`	Json		Browser fingerprint. These parameters could be used in 3DS 2.0 verification.

Response example:

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

Response parameters

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

Lookup

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

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

Capture could be called only for authorizations with success status.

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

Capture could be called only for authorizations with success status.

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

Void could be called only for authorizations with success status.

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

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

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

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

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

P2P Credit could be called only for transactions with success status (purchase or captured authorization).

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

Capture could be called only for authorizations with success status.

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

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

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 is PROCEED, then Tranzzo starts the transaction. Otherwise, payment is cancelled and webhook with failure status is sent to server_url

Preflight requests are sent only in hosted mode.

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

sha1 function should produce raw bytes rather than hex-encoded string.

Signature length: 28 characters

Primary operation webhook parameters

Primary operation webhook structure

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

Parameter	Type	Required	Description
`payment_id`	String	✅	Unique Tranzzo payment identifier
`order_id`	String	✅	Unique identifier of order
`gateway_order_id`	String		Unique order identifier in bank acquirer system.
`billing_order_id`	String		Unique Tranzzo billing identifier
`transaction_id`	String		Unique Tranzzo transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	Payment mode
`method`	String	✅	Payment method
`amount`	Number	✅	Transaction amount
`currency`	String	✅	Transaction currency
`payway`	String		Optional payway
`eci`	String		Electronic Commerce Indicator (ECI) - authentication result of credit card payment on 3D Secure
`status`	String	✅	Transaction status
`status_code`	String		Tranzzo payment status code
`status_description`	String		Tranzzo payment status code description
`cc_mask`	String		Card number mask
`cc_token`	String		Tranzzo card token
`cc_token_expiration`	String		Token expiration timestamp
`customer_id`	String		Customer identifier in merchant's system
`customer_phone`	String		Customer phone
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp when transaction was updated last time
`payload`	String		Payment request payload

Secondary operation webhook parameters

Capture webhook

Capture webhook structure:

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

Capture webhook parameters:

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

Void webhook

Void webhook structure:

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

Void webhook parameters:

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

Refund webhook

Refund webhook structure:

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

Refund webhook parameters:

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

Resend webhook for operation

Request example:

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

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

HTTP method: GET

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

Query parameters

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

Tranzzo card tokens

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

Use tokens to implement recurring payments.

Status codes

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

Successful codes

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

Pending codes

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

Failure codes

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

Init codes

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

Error handling

HTTP statuses

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

Client-side errors (4XX HTTP statuses)

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

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

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

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

Server-side errors (5XX HTTP statuses)

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

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

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

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

FAQ on errors returned from Tranzzo API:

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

CMS plugins

Available plugins

CMS	Plugin
Magento	magento-plugin
OpenCart	opencart-plugin
WordPress	wordpress-plugin
Joomla	joomla-plugin
Drupal	drupal-plugin
Netcat	netcat-plugin
PrestaShop	prestashop-plugin
MODX Shopkeeper	modx-shopkeeper

Contact maintainers

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

Google Pay

Google Pay™ Integration Guide

About Google Pay

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

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

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

via Tranzzo checkout page
via Google Pay API

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 string
png - 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 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)

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();
  }

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.

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)