Host-to-host інтеграція для отримання платежів¶

Великі організації, що виконують вимоги PCI DSS, можуть використовувати Host-to-host (H2H) інтеграцію для отримання карткових платежів.

Надіслати заявку службі підтримки , щоб уточнити вимоги та включити для вашого акаунту режим H2H-платежів.

Загальна схема взаємодії¶

Клієнт формує замовлення на сайті Мерчента.
Щоб надати клієнту можливість вибору варіанта оплати, мерчант відправляє передзапит платежу і отримує у відповіді від платформи MilkyPay Список доступних методів.
Мерчант відображає список методів і клієнт вибирає зручний йому спосіб оплатити замовлення.

Пункти 2 та 3 можна пропустити

Надсилання попереднього запиту не потрібно, якщо мерчант визначає метод оплати за клієнта і створює інвойс платежу після формування замовлення.
Мерчант створює [інвойс платежу] (#_2). Отримавши інвойс MilkyPay:
- Ініціює транзакцію на стороні провайдера.
- Надсилає у відповіді bearerToken платежу.
- Відправляє Callback мерчантові з повідомленням про успішне створення інвойсу.
Мерчант відображає дані платіжної форми зі свого боку.
Клієнт запроваджує реквізити на оплату. Мерчант відправляє платіжні дані на Card Gate MilkyPay. MilkyPay перенаправляє запит на списання коштів емітенту.
У випадку, якщо 3DSecure потрібна верифікація, мерчант отримує дані для відображення сторінки верифікації. Клієнт підтверджує платіж на сторінці верифікації, і дані передаються емітенту.
Емітент повертає результати оплати та завершує транзакцію.
Статус платежу фіксується та перенаправляється мерчантові.
Мерчант відображає клієнту статус платежу сторінках свого сайту.
MilkyPay відправляє мерчанту Callback із повідомленням про статус платежу.
Для уточнення статусу транзакції мерчант може провести реконсиляцію платежу за ID або отримати повний список даних інвойсів за допомогою приватного API. Також на порталі є щоденне отримання звітів за транзакціями.

Створення платіжного інвойсу¶

Параметри для авторизації

Створення інвойсу для H2H-з'єднання здійснюється за стандартом BasicAuth через приватний API.

Для авторизації використовуються ID акаунту як Login (Username) і ключ API як Password. Ви можете знайти потрібні параметри в налаштуваннях акаунту в розділі «Інтеграція» .

API: PRIVATE

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

Endpoint: /payment-invoices

Method: POST

JSON

Приклад запиту для інвойсу

{
    "data": {
    "type": "payment-invoices",
    "attributes": {
        "reference_id": "{guid}",
        "description": "Payment by order#1",
        "currency": "USD",
        "amount": 17,
        "service": "payment_card_USD_hpp",
        "return_url": "https://example.com/",
        "callback_url": "https://example.com/payments/callback"
        }
    }
}

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

{
"data": {
    "type": "payment-invoices",
    "id": "cpi_pbqlMhg37O49gcxf",
    "attributes": {
    "status": "processed",
    "serial_number": "pbqlMhg37O49gcxf",
    "resolution": "ok",
    "moderation_required": false,
    "amount": 100,
    "payment_amount": 100,
    "currency": "USD",
    "service_currency": "USD",
    "reference_id": "0f3cb67e-097c-4367-a06e-e7523b427234",
    "test_mode": true,
    "description": "test",
    "descriptor": null,
    "fee": 0,
    "deposit": 100,
    "processed": 1615991970,
    "processed_amount": 100,
    "refunded_amount": null,
    "processed_fee": 0,
    "processed_deposit": 100,
    "metadata": [],
    "flow_data": {
        "action": "https://cardgate.psp.name/hpp/cgi_8A8vc28Hr15D8tZ3",
        "method": "GET",
        "params": [],
        "metadata": {
        "sid": "cgi_8A8vc28Hr15D8tZ3",
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9...obAhMSLaJOOmm-s"
        }
    },
    "flow": "hpp",
    "payment_flow": "charge",
    "return_url": "https://example.com",
    "return_urls": {
        "fail": "https://example.com/1",
        "pending": "https://example.com/2",
        "success": "https://example.com/3"
    },
    "callback_url": "http://example.com/4",
    "created": 1615991953,
    "updated": 1615991970,
    "payload": {
        "token": null,
        "auth_type": "card",
        "client_ip": "...",
        "payment_card": {
        "last": "0000",
        "mask": "512381******0000",
        "brand": null,
        "first": "512381",
        "holder": null,
        "network": "mastercard",
        "expiry_year": "44",
        "issuer_name": "U.S. BANK, N.A.",
        "expiry_month": "11",
        "issuer_country": "US"
        }
    },
    "original_data": {
        "external_id": "cgi_8A8vc28Hr15D8tZ3",
        "merchant_id": "host2hostTest",
        "provider_id": null,
        "external_mid": "org_02HJ5jTUtan8ZXaT",
        "provider_code": "test"
    },
    "rrn": null,
    "approval_code": null,
    "reserved_amount": null,
    "reserve_expires": null,
    "unreserved": null,
    "source": "merchant_dashboard",
    "callback_logs": []
    },
    "relationships": {
    "payment-service": {
        "data": {
        "type": "payment-services",
        "id": "payment_card_usd_hpp"
        }
    },
    "payment-method": {
        "data": {
        "type": "payment-methods",
        "id": "payment_card"
        }
    },
    "payment-request": {
        "data": {
        "type": "payment-requests",
        "id": "prq_tE4lUowE4f1C39od"
        }
    },
    "active-payment": {
        "data": {
        "type": "payments",
        "id": "pay_MOq594PzFxwU2CF9gntin897"
        }
    },
    "commerce-account": {
        "data": {
        "type": "commerce-accounts",
        "id": "coma_CVGZ6W38ZsBe5cqI"
        }
    },
    "currency-account": {
        "data": {
        "type": "currency-accounts",
        "id": "comca_p7mPXxsCTFu6sONW"
        }
    },
    "customer": {
        "data": null
        }
    },
    "links": {
    "self": "/commerce/payment-invoices/cpi_pbqlMhg37O49gcxf"
    }
},
"included": [
    {
    "type": "payment-requests",
    "id": "prq_tE4lUowE4f1C39od",
    "attributes": {
        "amount": 100,
        "paid_amount": 100,
        "amount_readonly": true,
        "currency": "USD",
        "reference_id": "cpi_pbqlMhg37O49gcxf",
        "status": "SUCCESSFUL",
        "description": "test",
        "test_mode": true,
        "expires": 1616164743,
        "created": 1615991953,
        "processed": 1615991970,
        "return_url": "https://psp.name/return?id=cpi_pbqlMhg37O49gcxf",
        "callback_url": null,
        "resolution": "OK",
        "payment_service": null,
        "metadata": {
        "fee": "0.00",
        "fee_strategy": "external"
        },
        "fields": []
    },
    "relationships": {
        "payment-page": {
        "data": null
        },
        "rate-schema": {
        "data": {
            "type": "rate-schemes",
            "id": "ers_bJYZhE0G2IzVgA7H"
            }
        },
        "routing-schema": {
        "data": {
            "type": "checkout-routing-schemes",
            "id": "rtg_2QQfnlKAkqT39Nnk"
            }
        },
        "payments": {
        "data": [
            {
            "type": "payments",
            "id": "pay_MOU2CF9gnq594PzFxwtin897"
                }
            ]
        },
        "merchant-account": {
        "data": {
            "type": "merchant-accounts",
            "id": "ma_aBct0mkJ3WiRndih"
            }
        },
        "payment-service": {
        "data": null
        },
        "payment-method": {
        "data": {
            "type": "payment-methods",
            "id": "payment_card"
            }
        },
        "payment-provider": {
        "data": {
            "type": "payment-providers",
            "id": "cardgate"
            }
        }
      }
    }
  ]
}

Надсилання даних картки на Card Gate¶

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

Endpoint: /payment/sale

Method: POST

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

Крім обов'язкових атрибутів з даними карток, є можливість також передати опціональні — з параметрами браузера клієнта об'єкті browser_info*.

Якщо картка не вимагає 3DS-аутентифікації, але у відповіді повернувся проміжний статус транзакції (process_pending), для уточнення статусу потрібно дочекатися повідомлення Callback або провести реконсіляцію платежу за ID інвойсу.

JSON

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

{
"data": {
    "type": "sale-operation",
    "attributes": {
        "card_number": "5519283812030000",
        "card_holder": "Card Holder",
        "cvv": "123",
        "exp_month": "10",
        "exp_year": "35",
        "browser_info": {
            "browser_tz": "-60", // Часовой пояс
            "browser_screen_width": "1920" // Ширина экрана браузера
            }
        }
    }
}

Приклад відповіді (по 3DS 1.0)

{
    "status": "process_pending",
    "auth_mode": "3ds",
    "auth_payload": {
        "action": "https://card.psp.name/acs/auth",
        "method": "POST",
        "params": {
            "MD": "cGF5X2xKWXUwaDBVeDNQMHhmTFp5enY1WFNiMl9keF9jbg",
            "PaReq": "eyJ0eXAiOiJKV1eyJjb2RlM2RzUT_uYyy6xDaS4gZHrDfTzlCbcYGOD8lYmGgoIjoiOTM1MTgzIiwicGF5bWVudF9pZCI6InBheV9sSll1MGI6IjEwMjIifQ.QiLCJhbGciOiJIUzUxMiJ9.eHUekACfQEuwYHSp3v1ctZ8eS5rE9PAtVSfyyJGgFOe16fKRaQgwVXgzUDB4ZkxaeXp2NVhTYjJfZHhfY24iLCJjYXJkX251bWJlciI6IjUxMjM4MTcyMzQwNjAwMDAiLCJleHBfZGF0ZS",
            "TermUrl": "https://card.psp.name/complete-auth?pid=pay_lJYu0h0Ux3P0xfLZyzv5XSb2_dx_cn"
        }
    }
}

Приклад відповіді (без 3DS аутентификации)

{
    "status": "processed",
    "auth_mode": null,
    "auth_payload": []
}

* Перелік атрибутів обʼєкту browser_info

Властивість	Тип	Опис	Приклад
`browser_accept_header`	`string`	Формат очікуваного браузером заголовка	`application/json, text/plain, */`
`browser_color_depth`	`string`	Глибина кольору браузера	`24`
`browser_ip`	`string`	IP адреса платника	`123.123.12.1`
`browser_java_enabled`	`boolean`	Можливість виконання браузером Java-кода	`false`
`browser_language`	`string`	Код мови браузера (згідно ISO)	`en-US`
`browser_screen_height`	`string`	Висота екрану браузера	`1200`
`browser_screen_width`	`string`	Ширина екрану браузера	`1920`
`browser_tz`	`string`	Часовий пояс (різниця в хвилинах між UTC и локальним часом платника)	`-120`
`browser_user_agent`	`string`	Точний зміст заголовка User-Agent НТТР, отправленного браузером	`Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.135 Safari/537.36`
`device_channel`	`string`	Ідентифікатор каналу пристрою	`02`
`window_height`	`string`	Висота вікна браузера	`1200`
`window_width`	`string`	Ширина вікна браузера	`1920`

(для 3DS) Перенаправлення користувача на ACS¶

У відповіді на запит /payment/sale об'єкт auth_payload містить дані для 3D-Secure.

На action URL потрібно передати параметри форми params методом method.

Warning

Параметри та їх назви можуть відрізнятись в залежності від банку та версії технології авторизації.

Приклади об'єкта auth_payload для:

3DS 1.0 Example (JSON)

{
    "auth_payload": {
        "action": "https://acs.example.com/acspage/cap?RID=8\u0026VAA=A",
        "method": "POST",
        "params": {
            "MD": "999999999",
            "PaReq": "eJxVUlFvVA2jYv2jAQfuZfoD5v2E5KfQlLFJ2jAQfuZfoD5v2E5KQqurpe5os5wRBJU6dZCX79bszlDIrUe6+zWRkwjEe0qVHL3dmbqjeATGvs6XKz2Np1GBFSxq3r684PeiZvQbwnXOj9i951XdPeC4HWHT5bV1v+3z29+Vgs/OIi+9oe48acmxbs8VxVT7cFNkaX3+raapimUYqiZPbGz2CAOvRCP6gbytXany0njnTX07Y3Ii6VYY9u64EQNFz3J5OPlalzjc/4nyTv63+Lo+rfR6tFtlbfnofQDCDmaXpUEdS3SmcbXhU7MLJSwQ12gwovceazvouxlVLxmX8EgKkXeDuMSs7UoPPH47/yLbkeV+MU3SeTqst8PT5mfi9m5WZtmv+eMzCzuTzr0rcpzulYTmVbAfBLejA8KAsIlhlij6b8b+AbaDvJg=",
            "TermUrl": "https://test.example.com/3ds-return?pid=pay_Hjh3kMlNdqE4WpOmNPCoIgFU_K1_nM"
        }
    }
}

3DS 2.0 Example (JSON)

{
    "auth_payload": {
        "action": "https://acs.example.com/acspage/challenge?id=0c95e0873",
        "method": "POST",
        "params": {
            "creq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjBjOTNhNWFhLTUyNzAtMzhiNi04ZGQ4LWY5Mjc5MTVlMDg3MyIsImFjc1RyYW5zSUQiOiIyYjVkNzIyYi0yNjk2LTRhOTktYTcxZS1iZjYwYmI5MzlmNTgiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0="
        }
    }
}