Платежі з використанням токенів¶

Токенізація (для карткових платежів)¶

Для отримання токена картки необхідно, щоб по цій карті було проведено хоча б один успішний платіж із включеною опцією токенізації. Тоді в Callbacks або [по реконсіляції] (/uk/integration/payments/payment-page/#api_5) повернеться токен token в об'єкті payload разом з маскою карти та даними користувача.

API: PRIVATE

Авторизація: BasicAuth

Endpoint: /payment-invoices

Method: POST

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

reference_id
currency
amount
service
gateway_options → cardgate → "tokenize":true
customer
- reference_id

Опціональні поля:

test_mode
description
customer
- name
- email
- phone
- meta_data

JSON

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

{
"data":{
    "type":"payment-invoices",
    "attributes":{
        "test_mode":true,
        "reference_id":"ORDER1233",
        "description":"TEST",
        "currency":"USD",
        "amount":1,
        "customer":{
        "reference_id":"my_customer_1",
        "name":"John Doe"
        },
        "service":"payment_card_usd_hpp",
        "gateway_options":{
            "cardgate":{
            "tokenize":true
            }
        }
    }
}
}

Фрагмент відповіді [Payload] успішного платежу

{
"payload":{
    "client_ip":"",
    "payment_card":{
        "last":"0000",
        "mask":"512381******0000",
        "brand":"mastercard",
        "first":"512381",
        "holder":"asd asdas ",
        "expiry_year":"32",
        "issuer_name":"FIRST DATA CORPORATION",
        "expiry_month":"12",
        "issuer_country":"US"
    },
    "token":"4c9jHUgeL1SD7g5byDYn9Gc0RC60NN3x"
    }
}

Використання токенів¶

Визначення картки для Checkout¶

API: PRIVATE

Авторизація: BasicAuth

Endpoint: /payment-invoices

Method: POST

Створення інвойсу із зазначенням token (токена карти) та пов'язаного з ним Customer reference_id (обов'язково)
Надсилання даних форми, зібраних з flow_data

JSON

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

{
"data":{
    "type":"payment-invoices",
    "attributes":{
        "reference_id":"test_live_recurrent_11",
        "amount":100,
        "currency":"USD",
        "service":"payment_card_usd_hpp",
        "flow":"charge",
        "test_mode":true,
        "description":"Invoice by Token Example",
        "token": "4c9jHUgeL1SD7g5byDYn9Gc0RC60NN3x",
        "customer":{
            "reference_id":"my_customer_1"
            }
        },
        "callback_url":"https://example.com"
    }
}

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

{
    "data": {
        "type": "payment-invoices",
        "id": "cpi_ADzwZTG99f3q3utQ",
        "attributes": {
            "serial_number": "ADzwZTG99f3q3utQ",
            "status": "process_pending",
            "resolution": "ok", // При неуспішному статусі уточнює причину помилки
             "moderation_required": false // Описує, чи знаходиться операція на ручній модерації (якщо `true` - операція блокується для ручної модерації
            "amount": 100,
            "payment_amount": 100,
            "currency": "USD",
            "service_currency": "USD",
            "reference_id": "test_live_recurrent_11",
            "test_mode": true,
            "fee": 0,
            "deposit": 1,
            "processed": null,
            "processed_amount": null,
            "refunded_amount": null,
            "processed_fee": null,
            "processed_deposit": null,
            "metadata": [],
            "flow_data": {
                "action": "https://cardgate.example.io/hpp/cgi_ZzhRb7xLro7cIf0N",
                "method": "GET",
                "params": [],
                "metadata": {
                    "sid": "cgi_ZzhRb7xLro7cIf0N",
                    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfVWxReDF4d1pBY3FpMWl5aiI........sImV4cCI6MTYwMDg2NTM2MX0"
                }
            },
            "flow": "hpp",
            "payment_flow": "charge",
            "created": 1585175055,
            "updated": 1585175056,
            "payload": null,
            "description": null,
            "descriptor": "DEMO ACC:Заказ №:test_live_recurrent_11",
            "callback_url": "https://example.site/2fac2a84-a905-40fb-bf61-517506e4f3eb",
            "return_url": "https://example.io/about-us?myparam=myvalue",
            "original_data": null,
            "rrn": null,
            "approval_code": null
        },
        "relationships": {
            "payment-service": {
                "data": {
                    "type": "payment-services",
                    "id": "payment_card_usd_hpp"
                }
            },
            "payment-method": {
                "data": {
                    "type": "payment-methods",
                    "id": "payment_card"
                }
            },
            "customer": {
                "data": {
                    "type": "customers",
                    "id": "cus_kFIAv2l4M9diZGzK"
                }
            }
        },
        "links": {
            "self": "/api/payment-invoices/cpi_ADzwZTG99f3q3utQ"
        }
    }
}

Списання по токену (без участі користувача)¶

Створення інвойсу¶

API: PRIVATE

Авторизація: BasicAuth

Endpoint: /payment-invoices

Method: POST

При створенні інвойсу із зазначенням 'token' (токена карти) обов'язково зазначення пов'язаного з ним Customer 'reference_id'.

JSON

Приклад запиту (базовий)

{
"data":{
    "type":"payment-invoices",
    "attributes":{
        "test_mode":true,
        "reference_id":"ORDER1233",
        "currency":"USD",
        "amount":1,
        "service":"payment_card_usd_hpp",
        "token":"zsmmfyTkG6hn9DdwDhxh69LdQNJgZWk5xMdY7vg",
        "customer": {
            "reference_id":"my_customer_1"
            },
        "gateway_options":{
            "cardgate":{
            "instant":true
                }
            }
        }
    }
}

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

{
    "data": {
        "type": "payment-invoices",
        "id": "cpi_ADzwZTG99f3q3utQ",
        "attributes": {
            "serial_number": "ADzwZTG99f3q3utQ",
            "status": "process_pending",
            "resolution": "ok", // При неуспішному статусі уточнює причину помилки
            "moderation_required": false, // Описує, чи операція на ручній модерації (якщо `true` - операція блокується для ручної модерації)
            "amount": 1,
            "payment_amount": 1,
            "currency": "USD",
            "service_currency": "USD",
            "reference_id": "test_live_recurrent_11",
            "test_mode": true,
            "fee": 0,
            "deposit": 1,
            "processed": null,
            "processed_amount": null,
            "refunded_amount": null,
            "processed_fee": null,
            "processed_deposit": null,
            "metadata": [],
            "flow_data": {
                "action": "https://cardgate.example.io/hpp/cgi_ZzhRb7xLro7cIf0N",
                "method": "GET",
                "params": [],
                "metadata": {
                    "sid": "cgi_ZzhRb7xLro7cIf0N",
                    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9*****"
                }
            },
            "flow": "hpp",
            "payment_flow": "charge",
            "created": 1585175055,
            "updated": 1585175056,
            "payload": null,
            "description": null,
            "descriptor": "DEMO ACC:Заказ №:test_live_recurrent_11",
            "callback_url": "https://example.site/2fac2a84-a905-40fb-bf61-517506e4f3eb",
            "return_url": "https://example.io/about-us?myparam=myvalue",
            "original_data": null,
            "rrn": null,
            "approval_code": null
        },
        "relationships": {
            "payment-service": {
                "data": {
                    "type": "payment-services",
                    "id": "payment_card_usd_hpp"
                }
            },
            "payment-method": {
                "data": {
                    "type": "payment-methods",
                    "id": "payment_card"
                }
            },
            "customer": {
                "data": {
                    "type": "customers",
                    "id": "cus_kFIAv2l4M9diZGzK"
                }
            }
        },
        "links": {
            "self": "/api/payment-invoices/cpi_ADzwZTG99f3q3utQ"
        }
    }
}

Ініціювання списання¶

API: CARDGATE (URL при інтеграції видається менеджером)

Endpoint: /payment/sale

Method: POST

Авторизація: bearerToken (передається параметр token, отриманий у відповідь на запит створення інвойсу, об'єкт flow_data → metadata)

Приклад запиту на списання (JSON)

{
    "data": {
        "type": "sale-operation",
        "attributes": {}
    }
}