Перейти к содержанию

Host-to-host интеграция для получения платежей

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

Отправьте заявку службе поддержки , чтобы уточнить требования и включить для вашего аккаунта режим H2H-платежей.

Общая схема взаимодействия

H2H scheme

  1. Клиент формирует заказ на сайте мерчанта.

  2. Чтобы предоставить клиенту возможность выбора варианта для оплаты, мерчант отправляет предзапрос платежа и получает в ответе от платформы Paymega список доступных методов.

  3. Мерчант отображает список методов, и клиент выбирает удобный ему способ оплатить заказ.

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

    Отправка предзапроса не требуется, если мерчант определяет метод оплаты за клиента и создает инвойс платежа после формирования заказа.

  4. Мерчант создает инвойс платежа. Получив инвойс, Paymega:

    • Инициирует транзакцию на стороне провайдера.
    • Присылает в ответе bearerToken платежа.
    • Отправляет Callback мерчанту с уведомлением об успешном создании инвойса.
  5. Мерчант отображает данные платежной формы на своей стороне.

  6. Клиент вводит реквизиты для оплаты. Мерчант отправляет платёжные данные на Card Gate Paymega. Paymega перенаправляет запрос на списание средств эмитенту.

  7. В случае, если требуется 3DSecure верификация, мерчант получает данные для отображения страницы верификации. Клиент подтверждает платёж на странице верификации, и данные передаются эмитенту.

  8. Эмитент возвращает результаты оплаты и завершает транзакцию.

  9. Статус платежа фиксируется и перенаправляется мерчанту.

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

  11. Paymega отправляет мерчанту Callback с уведомлением о статусе платежа.

  12. Для уточнения статуса транзакции мерчант может провести реконсиляцию платежа по ID либо получить полный список данных инвойсов с помощью приватного API. Также на портале доступно ежедневное получение отчетов по транзакциям.

Создание платежного инвойса

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

Создание инвойса для H2H-соединения осуществляется по BasicAuth стандарту через приватный API — api.paymega.io.

Для авторизации используются 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. При этом сами параметры и их названия могут меняться в зависимости от эквайера.

Примеры объекта auth_payload для:

{
"auth_payload":{
        "action":"https://acs.pay_domain/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":"api.paymega.io/3ds-return?pid=pay_Hjh3kMlNdqE4WpOmNPCoIgFU_K1_nM"
            }
    }
}
{
    "auth_payload": {
    "action": "https://acs.pay_domain/acspage/challenge?id=0c95e0873",
    "method": "POST",
    "params": {
        "creq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjBjOTNhNWFhLTUyNzAtMzhiNi04ZGQ4LWY5Mjc5MTVlMDg3MyIsImFjc1RyYW5zSUQiOiIyYjVkNzIyYi0yNjk2LTRhOTktYTcxZS1iZjYwYmI5MzlmNTgiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0="
        }
    }
}

Особенности передачи параметров при 3DS 1.0 flow

В стандартном ответе на запрос при 3DS 1.0 в auth_payload приходят параметры MD (Merchant Data, ссылочный номер для идентификации транзакции на стороне мерчанта), PaReq (Payer Authentication Request, сообщение ответа DIBS сервера) и TermUrl (URL веб-сайта мерчанта, на который аутентифицирующий банк отправит плательщика после завершения аутентификации).

Вы можете заменить полученный параметр TermUrl на свой для перенаправления пользователя. Но, в таком случае, обязательно ретранслируйте запрос ACS без модификации и тем же методом, которым прислал ACS, на исходный адрес из TermUrl (endpoint: /payment/sale).