Перейти до змісту

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

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

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

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

H2H scheme

  1. Клієнт формує замовлення на сайті Мерчента.

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

  3. Мерчант відображає список методів і клієнт вибирає зручний йому спосіб оплатити замовлення.

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

    Надсилання попереднього запиту не потрібно, якщо мерчант визначає метод оплати за клієнта і створює інвойс платежу після формування замовлення.

  4. Мерчант створює [інвойс платежу] (#_2). Отримавши інвойс MilkyPay:

    • Ініціює транзакцію на стороні провайдера.
    • Надсилає у відповіді bearerToken платежу.
    • Відправляє Callback мерчантові з повідомленням про успішне створення інвойсу.
  5. Мерчант відображає дані платіжної форми зі свого боку.

  6. Клієнт запроваджує реквізити на оплату. Мерчант відправляє платіжні дані на Card Gate MilkyPay. MilkyPay перенаправляє запит на списання коштів емітенту.

  7. У випадку, якщо 3DSecure потрібна верифікація, мерчант отримує дані для відображення сторінки верифікації. Клієнт підтверджує платіж на сторінці верифікації, і дані передаються емітенту.

  8. Емітент повертає результати оплати та завершує транзакцію.

  9. Статус платежу фіксується та перенаправляється мерчантові.

  10. Мерчант відображає клієнту статус платежу сторінках свого сайту.

  11. MilkyPay відправляє мерчанту Callback із повідомленням про статус платежу.

  12. Для уточнення статусу транзакції мерчант може провести реконсиляцію платежу за 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_datametadata)

Крім обов'язкових атрибутів з даними карток, є можливість також передати опціональні — з параметрами браузера клієнта об'єкті 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" // Ширина экрана браузера
            }
        }
    }
}
{
    "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"
        }
    }
}
{
    "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 для:

{
    "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"
        }
    }
}
{
    "auth_payload": {
        "action": "https://acs.example.com/acspage/challenge?id=0c95e0873",
        "method": "POST",
        "params": {
            "creq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjBjOTNhNWFhLTUyNzAtMzhiNi04ZGQ4LWY5Mjc5MTVlMDg3MyIsImFjc1RyYW5zSUQiOiIyYjVkNzIyYi0yNjk2LTRhOTktYTcxZS1iZjYwYmI5MzlmNTgiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0="
        }
    }
}