Виплати на платіжні картки

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

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

Схема взаємодії сервісів

інформація

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

Особливості проведення транзакцій виплати:

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

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

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	`credit`
`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 identifier of transfer
`cc_number`	CC_NUMBER		Recipient's card number
`cc_token`	String		Card token
`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. 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_ip`	String	✅	Customer's IP address
`customer_country`	String		Customer’s country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
`customer_city`	String		Customer's city
`customer_birthday`	String		Customer's birthday (format: `yyyy-MM-dd`). The parameter is mandatory for merchants operating in either the microfinance sector or the iGaming sector
`customer_tax_id`	String		Customer’s tax identification number. The parameter is mandatory for merchants operating in the microfinance sector when the payout 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
`properties`	JSON		Additional specific parameters for integrations

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

Використання повного номеру картки: cc_number
Використання токену cc_token.

Окрім того, у запиті в обʼєкті properties можe передаватися також параметр:

Parameter	Type	Description
`is_operation_taxable`	String	Displays the special taxation regime for the credit transaction. The parameter is mandatory for merchants operating in the iGaming sector

Параметр properties.is_operation_taxable використовується мерчантами, що у своїй діяльності здійснюють виплату винагороди на користь інших осіб (iGaming, служби таксі тощо) для розмежування таких операцій, оскільки вони мають спеціальний режим оподаткування, від операцій повернення раніше внесених клієнтами коштів. Значення параметру:

false - повернення раніше внесених клієнтами коштів
true - виплата винагороди, виграшів

Важливо

Для мерчантів, що здійснюють діяльність у сфері iGaming передача параметрів customer_fname, customer_lname, customer_birthday та is_operation_taxable у запитах на проведення credit-транзакцій є обовʼязковою.

Важливо

Для мерчантів - мікрофінансових установ передача параметрів customer_fname, customer_lname, а також customer_birthday у платіжних запитах є обовʼязковою. Якщо сума виплати перевищує 30 000 UAH, то обовʼязковою є передача параметру customer_tax_id (РНОКПП).

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

$ curl --location 'https://cpay.tranzzo.com/api/v1/payment' \
  --header 'Content-Type: application/json' \
  --header 'X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}' \
  --header 'X-API-KEY: ${ENDPOINTS_KEY}' \
  --header 'X-Requested-With: XMLHttpRequest' \
  --header 'Cookie: psessionid=eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7ImNzcmZUb2tlbiI6IjFmYzYzOTMxMDNkYzQ0NTc2ZmE5ODNlMjNjMWI2ZjY3NjY0YjEyNDUtMTcyMTM3NzA5MjY1Mi1kZWM1YjExZWQ5Y2RlNTBjY2JlYmVmMjMifSwibmJmIjoxNzIxMzc3MDkyLCJpYXQiOjE3MjEzNzcwOTJ9.2II15Dxju3mz2umPic-NHlzXdJ5rObHMqYj2sUldkHM' \
  --data '{
      "pos_id": "238afc85-a179-41d3-9ad7-e8ccaa803dc5",
      "mode": "direct",
      "method": "credit",
      "amount": 100,
      "currency": "UAH",
      "description": "Credit description",
      "order_id": "01586b85-78c0-4bfd-807d-c7124e7be186",
      "order_3ds_bypass": "always",
      "cc_number": "4242424242424242",
      "server_url": "https://callback.blackhole.com/callback",
      "result_url": "https://example.com/result",
      "payload": "sale=true",
      "properties":
          {
              "is_operation_taxable": "true"
          }'
      }'

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

$ curl --location 'https://cpay.tranzzo.com/api/v1/payment' \
  --header 'Content-Type: application/json' \
  --header 'X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}' \
  --header 'X-API-KEY: ${ENDPOINTS_KEY}' \
  --header 'X-Requested-With: XMLHttpRequest' \
  --header 'Cookie: psessionid=eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7ImNzcmZUb2tlbiI6IjFmYzYzOTMxMDNkYzQ0NTc2ZmE5ODNlMjNjMWI2ZjY3NjY0YjEyNDUtMTcyMTM3NzA5MjY1Mi1kZWM1YjExZWQ5Y2RlNTBjY2JlYmVmMjMifSwibmJmIjoxNzIxMzc3MDkyLCJpYXQiOjE3MjEzNzcwOTJ9.2II15Dxju3mz2umPic-NHlzXdJ5rObHMqYj2sUldkHM' \
  --data '{
      "pos_id": "238afc85-a179-41d3-9ad7-e8ccaa803dc5",
      "mode": "direct",
      "method": "credit",
      "amount": 100,
      "currency": "UAH",
      "description": "Credit description",
      "order_id": "01586b85-78c0-4bfd-807d-c7124e7be186",
      "order_3ds_bypass": "always",
      "cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "server_url": "https://callback.blackhole.com/callback",
      "result_url": "https://example.com/result",
      "payload": "sale=true",
      "properties":
          {
              "is_operation_taxable": "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	`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-1 (alpha-2)). For instance, UA for Ukraine
`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
`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(≤4096)	Field for custom data.
`properties`	JSON	Additional specific parameters for integrations

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

{
  "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":               1000,
  "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":       "[email protected]",
  "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",
  "fee": {
                          "amount": 136,
                          "currency": "UAH"
  },
  "percent_fee": {
                          "amount": 126,
                          "currency": "UAH"
  },
  "fixed_fee": {
                          "amount": 10,
                          "currency": "UAH"
  },
  "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"
  }
}

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

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

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

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

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

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

Додавання платіжних методів

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

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

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

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