API інтеграція

Direct-інтеграція

Direct-інтеграція дозволить вам приймати спліт-платежі, використовуючи власну платіжну сторінку.

Формат взаємодії:

інформація

Використання direct-інтеграції потребує проходження сертифікації PCI DSS. У якості альтернативи ви можете скористатися нашим токенізаційним віджетом.

Якщо ви збираєте карткові дані самостійно, переконайтеся, що ви належним чином їх перевіряєте:

• Валідація строку дії картки.

• Перевіряйте номер картк за алгоритмом Луна (Luhn algorithm).

• Перевірте, щоб CVV/CVC містив тільки цифри
  
  

Особливості використання direct-інтеграції:

1. Платіжна сторінка повинна використовувати HTTPS-протокол.
2. Дані кожного клієнта мають бути сталими та унікальними.
3. Використовуйте HTTP-метод POST.
   

Параметри запиту:

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	direct
method	METHOD	✅	Payment method (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
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.
split	Array[SplitPayment]	✅	Split payment properties

В залежності від того, що використовується у запиті: повні карткові дані чи токен, вам необхідно передавати такі параметри:

• Використання повних карткових даних: cc_number, exp_month, exp_year, card_cvv.
• Використання токенів cc_token.

інформація

Окрім платежів з токенами, що були отримані після оплати карткою, також підтримуються платежі за допомогою токенів, що були отримані під час першої оплати через платіжні методи Apple Pay чи Google Pay™. Ці токени будуть передаватися у параметрі cc_token.

Наприклад:

"cc_token":"rcr:ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv" (токен після оплати Apple Pay / Google Pay™)
або
"cc_token":"ODJkZjBhNmY2OTMyND7sSjdD0S8TQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv" (токен після оплати карткою).

Окрім того, спліт-платіж додатково має містити специфічні параметри в масиві split:

Parameter	Type	Required	Description
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)
sub_merchant_id	UUID	✅	Unique Sub merchant identifier (to get the identifier, please contact support at [email protected])

Приклад запиту з картковими даними:

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

Приклад запиту з токеном:

$ 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_token":         "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "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	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’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)
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

Приклад відповіді:

{
  "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":       "[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",
  "bank_short_name":      "Bank name"
}

Окрім того, в запиті обов’язково мають передаватися такі дані щодо фінгерпринту браузера платника:

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

Приклад фінгерпринту браузера платника:

"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-інтеграція

Hosted-інтеграція дозволить вам приймати спліт-платежі від клієнтів з платіжної сторінки Tranzzo.

Формат взаємодії:

Для створення платежу за hosted-інтеграцією використовуйте HTTP-метод POST.

Параметри запиту:

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	hosted
method	METHOD	✅	Payment method (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
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_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
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

Приклад запиту:

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

Окрім того, спліт-платіж додатково має містити специфічні параметри в масиві split:

Parameter	Type	Required	Description
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)
sub_merchant_id	UUID	✅	Unique Sub merchant identifier (to get the identifier, please contact support at [email protected])

Відповідь зі статусом 303 HTTP на успішний запит містить заголовок location, в який клієнт повинен бути перенаправлений для продовження оплати.

Приклад відповіді:

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

Наступні кроки

Для тестування платіжного процесу:

• Створіть обліковий запис у мерчант-порталі.
• Використовуйте автентифікаційні дані тестового проєкту.
• Налаштуйте вебхуки.
• Скористайтеся даними для тестування для отримання різних кодів результатів операцій.
• Опрацьовуйте отримані помилки.

Знайдіть більше деталей у контрольному списку інтеграції.

Вихід в онлайн:

1. Створіть робочий проєкт у мерчант-порталі.
2. При direct-інтеграції: пройдіть сертифікацію PCI DSS або підключіть імплементувати токенізаційний віджет.
3. Коли наша команда Комплаєнсу активує робочий проєкт, замініть автентифікаційні дані тестового проєкту на дані робочого.

Дивіться також:

• Проведення повернень
• Токенізаційний віджет
• Hosted-чекаут
• Додавання платіжних методів