API integration

Direct integration

Direct integration allows you to verify payment cards using your own payment page.

Interaction format:

info

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

If using direct integration, if payment data is collected on your end, make sure that it is properly validated on your page, including:

• Validate the expiration date of the card.
• Check the card number using the Luhn algorithm.
• Check that the CVV/CVC contains only numbers.
  

In addition, the use of direct integration involves the following features:

• The payment page must use the HTTPS protocol.
• With direct integration, you can make requests using full payment data or tokens.
• Customer details must be persistent and unique.
• 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 (lookup)
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
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
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

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

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 (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’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
payload	String	Field for custom data.

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":       "[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",
  "payload":              "sale=true"
}

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 allows you to verify your customers' payment cards using the Tranzzo payment page.

Interaction format:

Request parameters:

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	hosted
method	METHOD	✅	Payment method (lookup)
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
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_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
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
order_timeout	Integer		Payment lifespan. Value in seconds

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":             "hosted",
      "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"
    }'

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 testing, to go online you need to:

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 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 verify payment cards provided by your customers.

See also:

• Tokenization widget
• Hosted checkout
• Adding payment methods