Предавторизація¶

Двоетапне списання коштів (delayed charge flow) дозволяє утримувати кошти на картці клієнта до підтвердження остаточного розрахунку.

При обробці «Delayed Charge flow» використовується для виконання двоетапної транзакції списання коштів.

Двоетапний потік списання коштів включає 2 кроки:

Створення Авторизація транзакції (HOLD)
Обробка транзакції (Capture / Void)

Друга дія може бути Capture або Void, залежно від налаштувань, встановлених в інтерфейсі панелі інструментів або запиті API.

Step 1: Створити авторизацію транзакції (Hold)

API: PRIVATE

Endpoint: /payment-invoices

Authentication: BasicAuth

Method: POST

Обов'язкові поля:

reference_id — унікальний ідентифікатор операції на стороні продавця; якщо його не вказати, система поверне код помилки 422.
service — ідентифікатор сервісу payment_card_uah_hpp
currency — валюта рахунку.
amount — сума рахунку у форматі числа з плаваючою комою, наприклад: 100.55
flow — вкажіть тип рахунку. Щоб ініціювати двоетапне стягнення плати, введіть значення delayed_charge у це поле.
customer[reference_id] — обов’язковий атрибут, якщо ви надсилаєте об’єкт customer.

Додаткові поля:

test_mode— надсилати true для тестових транзакцій; це false за замовчуванням.
description
customer— об'єкт містить основні дані клієнта та будь-які пов'язані з ними метадані.
reference_id— обов'язковий атрибут для customerоб'єкта в запиті.
name
email
phone
individual_tax_id
date_of_birth
metadata— для customer об'єкта.
metadata— для Рахунку-фактури.
return_url— загальна URL-адреса для повернення користувача після оплати.
return_urls— об'єкт із 3 різними URL-адресами для повернення користувачем після оплати на основі статусу платежу.

success
fail
pending — обов'язковий атрибут для return_urls об'єкта в запиті.

callback_urlURL-адреса для надсилання зворотних викликів у разі зміни статусу транзакції.
delayed_action— Вказує операцію, яку потрібно виконати після закінчення терміну затримки (може бути: capture або void).
delayed_action_delay— Вказує час у хвилинах, коли слід виконати відкладену дію.

Зверніть увагу!

Параметри delayed_action та delayed_action_delay слід включити до об'єкта attributes → options.

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

{
"data":{
"type":"payment-invoices",
"attributes":{
    "reference_id":"321",
    "amount":100,
    "currency":"UAH",
    "service":"payment_card_uah_hpp",
    "flow":"delayed_charge",
    "options":{
        "delayed_action":"capture",
        "delayed_action_delay":60
    },
    "test_mode":true,
    "description":"Invoice Example",
    "customer":{
        "reference_id":"1203515",
        "email":"somename@domain.com",
        "name":"John Wick",
        "phone":"+380987654321"
    },
    "metadata":{
        "key":"value"
    },
    "return_url":"https://example.com",
    "callback_url":"https://example.com"
      }
   }
}

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


{
"data":{
    "type":"payment-invoices",
    "id":"cpi_IPEphq1XwInHNOpH",
    "attributes":{,
        "status":"authorize_pending",
        "resolution":"ok",
        "moderation_required":false,
        "amount":100,
        "payment_amount":100,
        "currency":"UAH",
        "service_amount":100,
        "payment_service_amount":100,
        "exchange_rate":1,
        "service_currency":"UAH",
        "reference_id":"5587a275-f393-4599-948e-0efe4249559c",
        "test_mode":true,
        "fee":0,
        "failed_fee":null,
        "deposit":100,
        "processed":null,
        "processed_amount":null,
        "refunded_amount":null,
        "refunded_fee":null,
        "refunded":null,
        "processed_fee":null,
        "processed_failed_fee":null,
        "processed_deposit":null,
        "failed":null,    
        "metadata":{    
            "key":"value"    
        },
        "flow_data":{         
            "action":"https://example.io/hpp/cgi_G0bsyhroZj802zQU",  
            "method":"GET",  
            "params":[],  
            "metadata":{
                    "sid":"cgi_rb8eMnIYaDoRA1Qn",  
                    "token":"yJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzaWQiOiJjZ2lfcmI5ZU1uSVlhRG9SQTFRbiIsImV4cGlyZXMiOm51bGwsImV4cCI6MTc1MTUyMzk2NX0.kvcZpCGI7rgw1mqYcUfgO2UmsnisH4Pda_s3Vucl7-k"  
                }
            },
        "flow":"hpp",
        "payment_flow":"delayed_charge",
        "created":1751463965,
        "updated":1751463966,
        "payload":null,
        "description":"Description example",
        "descriptor":"Descriptor example",
        "callback_url":"https://example.com",
        "return_url":"https://example.com",
        "return_urls":{
            "fail":"https://example.com/3",
            "pending":"https://example.com/2",
            "success":"https://example.com/1"
        },
        "original_data":[],
        "rrn":null,
        "arn":null,
        "approval_code":null,
        "reserved_amount":null,
        "reserve_expires":null,
        "unreserved":null,
        "source":"merchant_api",
        "callback_logs":[],
        "charged_back_amount":null,
        "charged_back":null,
        "resolution_message":null,
        "hpp_url":"https://example.io/com/redirect/hpp/?cpi=cpi_IPEphq1XwInHNOpH",
        "refunds":[],
        "reserves":[],
        "reserve_options":null,
        "processed_unreserve":null,
        "processed_reserve_cancel":null,
        "reserve_cancelled":null,
        "delayed_action":null,
        "delayed_action_at":null,
        "charged_back_amount":null
    },
    "relationships":{
        "payment-service":{
            "data":{
                "type":"payment-services",
                "id":"payment_card_uah_hpp"
            }
        },
        "payment-method":{
            "data":{
                "type":"payment-methods",
                "id":"payment_card"
            }
        }, 
        "customer":{
            "data":{
                "type":"customers",
                "id":"cus_F0zqT9wWKBeJ51DA"
            }
        } 
    },  
        "active-payment":{
            "data":{
                "type":"payments",
                "id":"pay_Uvlm8WChE2OVeZ7Qu2FAk8q9"
            }
        } 
    },     
    "links":"{"
        "self":"/api/payment-invoices/cpi_ADzwZTG99f3q3utQ"
            }
        } 
 },

Примітка!

Параметр `flow` за замовчуванням встановлено на `charge`, що є простим потоком оплати з одноетапною оплатою.

Примітка!

Якщо ви включите параметр `delayed_action` у свій запит, тоді параметр `delayed_action_delay` стане обов'язковим. В іншому випадку ви отримаєте відповідь з кодом помилки 422.

Примітка!

Параметр `delayed_action_delay` слід встановити в хвилинах.

Примітка!

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

Після ініціювання обробки рахунку-фактури він отримує статус authorize_pending з waiting_for second_step. На цьому етапі клієнт повинен авторизувати транзакцію, підтвердивши платіж.

Step 2: Авторизація платежу

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

CAPTURE

API: PRIVATE

Endpoint: /payment-invoices/{id}/capture

Authentication: BasicAuth

Method: POST

Обов'язкові поля:

id — унікальний ідентифікатор інвойсу
amount — сума, яку потрібно списати. Параметр allow_partially у платіжному рахунку має бути true для часткового зафіксування суми [amount].
type — тип транзакції, яку потрібно виконати.

Примітка!

Для часткового отримання суми [`amount`] параметр платіжного рахунку `allow_partially` має бути true.

Приклад

{
      "data":{
      "id":"cpi_IPEphq1XwInHNOpH",
      "type":"payment-invoices",
      "attributes":{
          "amount":"100"
          }
      }
  }

VOID

API: PRIVATE

Endpoint: /payment-invoices/{id}/void

Authentication: BasicAuth

Method: POST

Обов'язкові поля:

id — унікальний ідентифікатор інвойсу
amount — сума, яку потрібно повернути. Параметр allow_partially у платіжному рахунку має бути true для часткового зафіксування суми [amount].
type — тип транзакції, яку потрібно виконати.

Примітка!

Доступне лише анулювання повної суми.

Приклад

{
      "data":{
      "id":"cpi_IPEphq1XwInHNOpH",
      "type":"payment-invoices",
      "attributes":{}
      }
  }

Коди помилок потоку delayed charge flow

Код	Етап	Опис
`422`	`"This value should be greater than or equal to 60"`	Параметр delayed_action_delay встановлено на менше 60 під час ініціювання виставлення рахунку
`422`	`“To use option delayed_action, option delay must be passed or set in Commerce Account payment options”`	Якщо ви включаєте параметр delayed_action до свого запиту, тоді параметр delayed_action_delay стає обов'язковим. Оскільки затримка дії повинна мати час.
`422`	`“Options delay and delayed_action can be used only with flow delayed_charge“`	Параметри delayed_action та delayed_action_delay стають обов'язковими. Оскільки затримка дії повинна мати час.