Skip to main content

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:

An image from the static

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:

ParameterTypeRequiredDescription
pos_idUUIDMerchant's identifier (POS_ID)
modeMODEdirect
methodMETHODPayment method (auth or purchase)
amountNumberTransaction amount
currencyCURRENCYTransaction currency (ISO_4217)
descriptionStringPayment description
order_idStringUnique identified of order
order_3ds_bypassString3-D Secure flow option
cc_numberCC_NUMBERCard number
exp_monthNumberCard expiration month field
exp_yearNumberCard expiration year field
card_cvvStringCard CVV
productsArray[Product]Array of products to be paid
customer_idStringCustomer identifier in merchant's system
customer_fnameStringCustomer first name
customer_lnameStringCustomer last name
customer_emailStringCustomer email
customer_phoneStringCustomer phone
customer_ipStringCustomer IP address
customer_countryStringCustomer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
server_urlURLWebhook notification will be sent to this URL
result_urlURLCustomer will be redirected to this URL after payment.
merchant_mccMCCMCC for this transaction
payloadStringField for merchant custom data. Max 4000 symbols.
validation_urlStringPreflight request will be sent to this URL
browser_fingerprintJsonBrowser fingerprint. These parameters could be used in 3DS 2.0 verification.
cryptogramJsonCryptogram parameters.
customer_referrerURLPage customer is redirected from.

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:

ParameterTypeDescription
payment_idUUIDUnique Tranzzo payment identifier
order_idString(≤256)Unique identifier of order
gateway_order_idGW_IDUnique order identifier in bank acquirer system.
billing_order_idBILLING_IDUnique Tranzzo billing identifier
transaction_idUUIDTranzzo transaction identifier
pos_idUUIDMerchant's identifier (POS_ID)
modeMODEdirect
methodMETHODPayment method (auth or purchase)
amountNumberTransaction amount
currencyCURRENCYTransaction currency (ISO_4217)
descriptionString(≤2048)Payment description
statusSTATUSTransaction status
status_codeSTATUS_CODETranzzo payment status code
status_descriptionSTATUS_DESCRIPTIONTranzzo payment status code description
user_action_requiredBooleanEither customer action is required to proceed with payment
user_action_urlURLIf user_action_required is true then user should be redirected to this URL
eciECIElectronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mccMCCMCC for this transaction
options_3dsString3-D Secure flow option
cc_maskCC_MASKCard number mask
cc_tokenCC_TOKENTranzzo card token generated for this card
cc_token_expirationStringToken expiration timestamp
customer_idStringCustomer identifier in merchant's system
customer_ipStringCustomer IP address
customer_fnameStringCustomer first name
customer_lnameStringCustomer last name
customer_emailStringCustomer email
customer_phoneStringCustomer phone
customer_countryStringCustomer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
result_urlURLCustomer will be redirected to this URL after payment.
created_atTIMESTAMPTimestamp when transaction was created
processing_timeTIMESTAMPTimestamp when transaction was updated last time
feeObjectAmount and currency of commission
fixed_feeObjectAmount and currency of fixed commission (fee), which constitutes a portion of the total commission (fee)
percent_feeObjectAmount and currency representing the interest commission (fee), which constitutes a portion of the total commission (fee)
payloadStringField for custom data
bank_short_nameStringBank 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:

ParameterTypeDescription
processed_amountNumberThe 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_currencyString(≤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:

ParameterTypeDescription
browserColorDepthStringBrowser's color depth
browserScreenHeightStringBrowser's screen height
browserScreenWidthStringBrowser's screen width
browserJavaEnabledStringBrowser's java enabled
browserLanguageStringBrowser's language
browserTimeZoneStringBrowser's timezone
browserTimeZoneOffsetStringBrowser's timezone offset
browserAcceptHeaderStringBrowser's accept header
browserIpAddressStringBrowser's IP address
browserUserAgentStringBrowser'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:

An image from the static

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

Request parameters:

ParameterTypeRequiredDescription
pos_idUUIDMerchant's identifier (POS_ID)
modeMODEhosted
methodMETHODPayment method (auth or purchase)
amountNumberTransaction amount
currencyCURRENCYTransaction currency (ISO_4217)
descriptionStringPayment description
order_idStringUnique identified of order
order_3ds_bypassString3-D Secure flow option
productsArray[Product]Array of products to be paid, empty array can be specified
customer_idStringCustomer identifier in merchant's system
customer_fnameStringCustomer first name
customer_lnameStringCustomer last name
customer_emailStringCustomer email
customer_phoneStringCustomer phone
customer_ipStringCustomer IP address
customer_langStringCheckout language. Supported values.
customer_countryStringCustomer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
server_urlURLWebhook notification will be sent to this URL
result_urlURLCustomer will be redirected to this URL after payment.
merchant_mccMCCMCC for this transaction
payloadStringField for custom data. Max 4000 symbols.
validation_urlURLPreflight request will be sent to this URL

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:

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: