Оплата частинами від ПриватБанку

Оплата частинами від Приват - це розстрочка, що надається банком ПриватБанк в межах кредитного ліміту, встановленого при оплаті товару/послуги в торгово-сервісних мережах та/або інтернет-магазинах. Для використання цього платіжного методу, оплата може бути проведена тільки карткою Privatbank. Більш детально ознайомитися з особливостями роботи та умовами надання послуг можна на сайті банку.

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

Запит на створення платежу повинен містити такі параметри:

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 > 300 UAH). 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 order
order_3ds_bypass	String	✅	3-D Secure flow option
payway	String	✅	Optional payway. Use "privat_payparts" for processing direct payments through Privat Payment by Parts
products	Array[Product]	✅	Array of products to be paid
customer_id	String		Customer identifier in merchant's system
customer_fname	String		Customer first name
customer_lname	String		Customer last name
customer_email	String		Customer email
customer_phone	String	✅	Customer phone. It must be in the format +380992223344.
customer_ip	String	✅	Customer IP address
customer_country	String		Customer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
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
properties.parts_count	String	✅	The number of parts into which the payment amount is divided (must be > 1 and <= 25)

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

$ 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":           "auth",
      "amount":           500,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "payway":           "privat_payparts",
      "customer_id":      1234,
      "customer_fname":   "Tom",
      "customer_lname":   "Hanks",
      "customer_email":   "[email protected]",
      "customer_phone":   "+380999999999",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "properties":       {
        "part_counts": "2"
      },
      "products":         [
        {
          "name"    : "Apple",
          "amount"  : 100,
          "currency": "UAH",
          "qty"     : 2
        },
        {
          "name"    : "Pineapple",
          "amount"  : 100,
          "currency": "UAH",
          "qty"     : 1
        }
      ]
    }'

Параметри відповіді:

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)
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
processed_at	TIMESTAMP	Timestamp when transaction was updated last time
payload	String	Field for custom data
receipt_url	URL	URL link to the receipt for the corresponding transaction

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

{
  "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":               "auth",
  "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":      "null",
  "eci":                  "null",
  "mcc":                  "null",
  "options_3ds":          "supported",
  "cc_mask":              "null",
  "cc_token":             "null",
  "cc_token_expiration":  "null",
  "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",
  "processed_at":         "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "receipt_url":          "https://cpay.tranzzo.com/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
}

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

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

інформація

Для активації методу “Оплата частинами від ПриватБанку“ на платіжній сторінці зверніться у службу підтримки Tranzzo

Запит на створення платежу повинен містити такі параметри:

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 identifier of order
order_3ds_bypass	String	✅	3-D Secure flow option
products	Array[Product]	✅	Array of products to be paid
name	String	✅	Product name
amount	Number	✅	Product price (does not influence total payment 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	String	✅	Product price currency
qty	Number	✅	Product quantity. Max three decimals (e.g. 1.455)
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
f_receipt_delivery	String		Fiscal receipt delivery option (email, sms, viber, none). For more details, refer to the Receiving Fiscal Receipts section.

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

$ 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":           "auth",
      "amount":           500,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_email":   "[email protected]",
      "customer_phone":   "+380999999999",
      "products":         [
        {
          "name"    : "Apple",
          "amount"  : 100,
          "qty"     : 2
        },
        {
          "name"    : "Pineapple",
          "amount"  : 100,
          "qty"     : 1
        }
      ]
    }'

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

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

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

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

Тестування процесу обміну токену і оплати:

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

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

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

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

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

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