API integration

Direct integration

Direct integration allows you to accept payments using your own payment page. At the same time, the integration allows making payment by payment cards and using alternative payment methods.

Interaction format:

info

Note: the use of direct integration when collecting card data on the merchant side requires PCI DSS certification. Alternatively, you can use our tokenization widget by implementing it on your site.

If you're collecting payment data yourself without using a widget when using direct integration, make sure you're using the following validation:

• Card expiration date validation.

• Checking the card number according to the (Luhn algorithm).

• The entered CVV/CVC contains only numbers.
  
  

Features of using direct integration:

1. The payment page must use the HTTPS protocol.
2. Customer details must be persistent and unique.
3. Use the HTTP POST method.
   
   

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. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
currency	CURRENCY	✅	Transaction currency (ISO_4217)
description	String	✅	Payment description
order_id	String	✅	Unique identified of order
order_3ds_bypass	String	✅	3-D Secure flow option
cc_number	CC_NUMBER		Card number
exp_month	Number		Card expiration month field
exp_year	Number		Card expiration year field
card_cvv	String		Card CVV
cc_token	String		Card token
products	Array[Product]		Array of products to be paid
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_patronym	String		Customer’s patronym
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-1 (alpha-2)). For instance, UA for Ukraine
customer_birthday	String		Customer's birthday (format: yyyy-MM-dd)
customer_referrer	URL		Page customer is redirected from.
customer_tax_id	String		Customer’s tax identification number. The parameter is mandatory for merchants operating in the microfinance sector when the payment amount exceeds 30 000 UAH
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.

caution

For merchants that are microfinance institutions, providing either the customer_birthday or customer_tax_id parameter in payment requests is mandatory. If the payment amount exceeds 30 000 UAH, the customer_tax_id parameter becomes mandatory.

Depending on whether the request is full card data or a token, you need to pass the following parameters:

• Using full card data: cc_number, exp_month, exp_year, card_cvv.
• Using tokens: cc_token.

info

In addition to supporting payments with tokens received after card payments, we also support tokens generated during the first payment via Apple Pay or Google Pay™. These tokens should be passed in the cc_token parameter

For example:

"cc_token":"rcr:ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv" (token after an Apple Pay or Google Pay™ payment)
or
"cc_token": "ODJkZjBhNmY2OTMyND7sSjdD0S8TQzOXU3ZDFhYzI6cWJmWHFmMHlz M3hYaXJMWEZv" (token after a card payment).

Example request using card data:

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

Example request using token:

$ 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_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"
      }
    }'

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	String	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_patronym	String	Customer’s patronym
customer_email	String	Customer’s email
customer_phone	String	Customer’s phone
customer_country	String	Customer’s country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
customer_birthday	String	Customer’s birthday (format: yyyy-MM-dd)
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
fee	Object	Amount and currency of commission
fixed_fee	Object	Amount and currency of fixed commission (fee), which constitutes a portion of the total commission (fee)
percent_fee	Object	Amount and currency representing the interest commission (fee), which constitutes a portion of the total commission (fee)
payload	String	Field for custom data
bank_short_name	String	Bank short name.

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":               1000,
  "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":       "[email protected]",
  "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",
  "fee": {
                          "amount": 136,
                          "currency": "UAH"
  },
 "percent_fee": {
                          "amount": 126,
                          "currency": "UAH"
  },
  "fixed_fee": {
                          "amount": 10,
                          "currency": "UAH"
  },
  "payload":              "sale=true",
  "bank_short_name":      "Bank name"
}

When utilizing certain alternative payment methods, there may be instances where the payer can make partial payments, leading to changeable transaction amounts. In such scenarios, the response will also include the following parameters:

Parameter	Type	Description
processed_amount	Number	The amount that was actually paid by the customer and processed by the payment system. It applies to payments where the final payment amount can be changed by the payer.
processed_currency	String(≤256)	Actual currency of payment with processed_amount. It applies to payments where the final payment amount can be changed by the payer.

Response example with changeable amount:

{
  "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":              1000,
  "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",
  "processed_amount":    980,
  "processed_currency":  "UAH",
  "fee":   {
                        "amount": 136,
                        "currency": "UAH"
  },
  "percent_fee": {
                        "amount": 126,
                        "currency": "UAH"
  },
  "fixed_fee": {
                        "amount": 10,
                        "currency": "UAH"
  }
}

In addition, the following data regarding the fingerprint of the payer's browser must be submitted in the request:

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

An example of a payer's 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"
}

Hosted integration

Hosted integration will allow you to accept payments from customers from the Tranzzo payment page. This payment setup method allows you to use payment cards, digital wallets Apple Pay and Google Pay™, and other payment methods.

Interaction format:

To create a hosted integration payment, use the POST HTTP method.

Request parameters:

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. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
currency	CURRENCY	✅	Transaction currency (ISO_4217)
description	String	✅	Payment description
order_id	String	✅	Unique identified of order
order_3ds_bypass	String	✅	3-D Secure flow option
products	Array[Product]		Array of products to be paid, empty array can be specified
customer_id	String		Customer’s identifier in merchant's system
customer_fname	String		Customer’s first name. The parameter is mandatory for merchants operating in either the microfinance sector or the iGaming sector
customer_lname	String		Customer’s last name. The parameter is mandatory for merchants operating in either the microfinance sector or the iGaming sector
customer_patronym	String		Customer’s patronym
customer_email	String	✅	Customer’s email
customer_phone	String	✅	Customer’s phone
customer_lang	String		Checkout language. Supported values.
customer_country	String		Customer’s country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
customer_birthday	String		Customer's birthday (format: yyyy-MM-dd)
customer_tax_id	String		Customer’s tax identification number. The parameter is mandatory for merchants operating in the microfinance sector when the payment amount exceeds 30 000 UAH
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
order_timeout	Integer		Payment lifespan. Value in seconds

caution

For merchants operating in the iGaming sector, passing the parameters customer_fname and customer_lname in payment requests is mandatory.

caution

For merchants that are microfinance institutions, providing the parameters customer_fname, customer_lname, as well as customer_birthday or customer_tax_id in payment requests is mandatory. If the payment amount exceeds 30 000 UAH, the customer_tax_id parameter becomes mandatory.

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

A 303 HTTP response status to a successful request contains a location header to which the customer should be redirected to proceed with payment.

Response example:

HTTP/2 303
# .. other headers
location: https://cpay.tranzzo.com/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form

Next steps

To test the payment process:

• Create an account in the merchant portal.
• Use the authentication data of the test project.

• Configure webhooks.
• Use the test data to obtain different operation result codes.
• Handle received errors.

Find more details in the integration checklist.

After completing the testing to go live, you need:

1. Create a live project in the merchant portal.
2. With direct integration: pass PCI DSS certification (if you intend to work with card data of the payers on your side) or implement a tokenization widget (possibility of making direct payments without using card data).
3. After receiving information from our Compliance team about the completion of the settings for the project, make changes to the authentication data using the data of the live project.
4. You are ready to accept payments from your customers.

See also:

• Recurring payments

• Payment refund
• Payment widget
• Tokenization widget
• Hosted checkout
• Adding payment methods