Верифікація¶

Для проведення транзакції верифікації картки в запиті необхідно передавати параметр "flow": "verify"

Приклад створення verify платежа.

URL: (Видається менеджером)/payment-invoices

Method: POST

Запит

{
"data":{
"type":"payment-invoices",
"attributes":{
    "reference_id":"edf06585-25fc-4fb6-b7c2-73c85fbf2fce",
    "amount":100,
    "currency":"UAH",
    "service":"payment_card_uah_hpp",
    "flow":"verify",
    "gateway_options":{
        "cardgate":{"tokenize":true}},
        "test_mode":true,
        "description":"edf06585-25fc-4fb6-b7c2-73c85fbf2fce",
        "customer":{
            "reference_id":"test1",
            "name":"Тестов Тест Тестович",
            "individual_tax_id":"1234567890"
            "metadata":{
                 "verify_first_name":"",
                 "verify_last_name":""
            }
        },
        "return_url":"https://example.com/return",
        "return_urls":{
            "success":"https://example.com/success",
            "pending":"https://example.com/pending",
            "fail":"https://example.com/fail"
        },
        "callback_url":"https://example.com/callback",
        "metadata":{
            "site":"https://example.com/",
        }
      }
    }
}

Відповідь

{
    "data": {
    "type": "payment-invoices",
    "id": "cpi_jiN7FSC63ykk3L5R",
    "attributes": {
        "status": "process_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": "edf06585-25fc-4fb6-b7c2-73c85fbf2fce",
        "test_mode": true,
        "fee": 0,
        "deposit": 100,
        "processed": null,
        "processed_amount": null,
        "refunded_amount": null,
        "refunded_fee": null,
        "refunded": null,
        "processed_fee": null,
        "processed_deposit": null,
        "failed": null,
        "metadata": {
            "site": "https://example.com/"
    }
    "flow_data": {
    "action": "/hpp/cgi_BcSBNDNXgWsLm4SB",          "params": [],
            "id": "cpi_jiN7FSC63ykk3L5R",
        "metadata": {
                "sid": "cgi_BcSBNDNXgWsLm4",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzaWQiOiJjZ2lfQmNTQk5ETlhnV3NMbTRTQiIsImV4cGlyZXMiOm51bGwsImV4cCI6MTc0MTI1NTA0MX0.bMvtadKL-eSUF8d61-QJEd3cY6pLc_RfduujcOi1CYU",            }
        },
        "flow": "hpp",
        "payment_flow": "verify",
        "created": 1741254141,
        "updated": 1741254141,
        "payload": null,
        "description": "edf06585-25fc-4fb6-b7c2-73c85fbf2fce",
        "descriptor": "edf06585-25fc-4fb6-b7c2-73c85fbf2fce",
        "callback_url": "https://example.com/callback",
        "return_url": "https://example.com/return",
    "return_urls": {
            "fail": "https://example.com/fail",
            "pending": "https://example.com/pending",
            "success": "https://example.com/success",
    },
        "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": "/redirect/hpp/?cpi=cpi_jiN7FSC63ykk3L5R",
        "refunds": [],
        "reserves": [],
        "reserve_options": null,
        "processed_unreserve": null,
        "processed_reserve_cancel": null,
        "reserve_cancelled": 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_ZCxQwVVAHbgXALyy",
            },
        },    
    "active-payment": {
                    "data": {
                            "type": "payments",
                            "id": "pay_N1g939itHeo7uWpaQQN51Eid",
                    }
                }
            },
        "links": {
                "self": "/api/payment-invoices/cpi_jiN7FSC63ykk3L5R",
        }
    }
}

Якщо використовувати платіжну сторінку:¶

У відповіді на запит в flow_data.action міститься посилання для редіректа клієнта. Після редіректа виконувати реконсиляцію або очікувати фінальний статус в Callbacks.

Якщо використовувати h2h:¶

У відповіді на запит в flow_data.token міститься токен для авторизації і запиту payment/sale з browser_info

URL: (Видається менеджером)/payment/sale

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

Method: POST

Запит

{
      "data":{
      "type":"sale-operation",
  "attributes":{
      "card_number":"5123817234060000",
      "exp_month":"12",
      "exp_year":"28",
      "cvv":"111",
  "browser_info":{
          "browser_tz":"-120",
          "browser_screen_width":"1920",
          "browser_screen_height":"1080",
          "browser_color_depth":"24",
          "browser_language":"uk-UA",
          "browser_java_enabled":false,
          "browser_accept_header":"application/json, text/plain, */*",
          "browser_user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36",
          "browser_ip":"11.11.111.111",
          "device_channel":"desktop",
          "window_width":"1920",
          "window_height":"960",
              }
          }
      }
  }

Відповідь при non3ds

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

Відповідь при 3ds

{
        "status":"process_pending",
        "auth_mode":"3ds",
        "auth_payload":{
            "action":"/form/cgi_qH3TjqWUN4ptZ1Bo?hash=d8b632c4c94c30f3c8f7e32eab6eeb154ca48e4e48c3f1718728e2f2be6c97b4",
            "params":[],
            "method":"GET",
            "embedded_acs":false
        },
        "data_collecting_payload":[]
  }

Відповідь при 3ds містить посилання для редіректа клієнта для проходження 3ds перевірки.

Отримання токена карти після успішного verify платежа (токен карти надсилається в колбеці з фінальним успішним статусом верифікації "verified" в параметрі payload.token).

Приклад

{
    "data": {
        "type": "payment-invoices",
        "id": "cpi_jiN7FSC63ykk3L5R",
        "attributes": {
            "status": "verified",
            "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": "edf06585-25fc-4fb6-b7c2-73c85fbf2fce",
            "test_mode": true,
            "fee": 0,
            "deposit": 100,
            "processed": 1741254676,
            "processed_amount": null.
            "refunded_amount": null.
            "refunded_fee": null.
            "refunded": null.
            "processed_fee": null.
            "processed_deposit": null.
            "failed": null,
            "metadata": {
                  "site": "https://example.com/"
            },
            "flow_data": {
                  "action": "/hpp/cgi_BcSBNDNXgWsLm4SB"
                  "method": "GET"
                  "params": []
                      "metadata": {
                          "sid": "cgi_BcSBNDNXgWsLm4SB"
                          "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzaWQiOiJjZ2lfQmNTQk5ETlhnV3NMbTRTQiIsImV4cGlyZXMiOm51bGwsImV4cCI6MTc0MTI1NTA0MX0.bMvtadKL-eSUF8d61-QJEd3cY6pLc_RfduujcOi1CYU"
                      }
             },
             "flow": "hpp"
             "payment_flow": "verify"
             "created": 1741254141,
             "updated": 1741254676,
             "payload": {
                  "token": "ECWCHTHTsr9XW5rq6jI0OSCSR40O7BcQ"
                  "auth_type": "card",
                  "client_ip": "77.72.132.194",
                  "payment_card": {
                      "last": "0000",
                      "mask": "512381******0000",
                      "type": "credit",
                      "brand": null,
                      "first": "512381",
                      "holder": "null",
                      "card_id": "card_GRdnsnf0PepXbjLN",
                      "network": "mastercard",
                      "expiry_year": "30",
                      "issuer_name": "FIRST DATA CORPORATION",
                      "expiry_month": "12",
                      "verification": {
                          "type": "3ds",
                          "details": {
                              "eci": "08",
                              "version": "1"
                          },
                      },
                  },
                  "issuer_country": "US"
               },
         },
         "description": "edf06585-25fc-4fb6-b7c2-73c85fbf2fce",
         "descriptor": "edf06585-25fc-4fb6-b7c2-73c85fbf2fce",
         "callback_url": "https://example.com/callback",
         "return_url": "https://example.com/return",
         "return_urls": { 
              "fail": "https://example.com/fail",
              "pending": "https://example.com/pending",
              "success": "https://example.com/success"
         },
         "original_data": { 
              "provider_code": "test",
              "original_account_name": null,
              "original_provider_payload": {
                   "electronic_verification_results": {
                         "code": "null",
                         "codeRaw": "null",
                         "lastName": "null",
                         "firstName": "null",
                         "lastNameRaw": "null",
                         "firstNameRaw": "null"
                    }
              }
         },
         "rrn": "19594313",
         "arn": "73112992",
         "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": "/redirect/hpp/?cpi=cpi_jiN7FSC63ykk3L5R",
         "refunds": [],
         "reserves": [],
         "reserve_options": null,
         "processed_unreserve": null,
         "processed_reserve_cancel": null,
         "reserve_cancelled": null
         },
         "relationships": { 
              "payment-service": { 
                  "data": { 
                      "type": "payment-services"
                      "id": "payment_card_uah_hpp"
                  },
              },
              "payment-method": { 
                  "data": { 
                      "type": "payment-methods",
                      "id": "payment_card"
                  },
              },
              "active-payment": { 
                  "data": { 
                      "type": "payments",
                      "id": "pay_N1g939itHeo7uWpaQQN51Eid"
                  },
              },
         },
         "links": { 
              "self": "/api/payment-invoices/cpi_jiN7FSC63ykk3L5R"
         },
       },
     },

Об'єкт electronic_verification_results містить результати електронної верифікації держателя картки. Ці поля перевіряють відповідність імені та прізвища користувача з даними банку-емітента картки й повертають статус їхнього збігу.
Визначення вхідних даних для перевірки:

Система перевіряє параметри верифікації в об'єкті customer.metadata запиту: verify_first_name та verify_last_name.
У випадку, якщо параметри не були передані, система автоматично перевіряє параметр/параметри з об'єкта customer.

Поле API	Код / Значення	Статус відповідності
First Name (Ім'я)
`firstNameRaw`	`'01'`	Match (Збіг)
`firstNameRaw`	`'50'`	Partial Match (Частковий)
`firstNameRaw`	`'99'`	No Match (Немає збігу)
`firstName`	`'Y'`	Yes, Matches (Збігається)
`firstName`	`'O'`	Partial Match (Частковий)
`firstName`	`'N'`	No Match (Немає збігу)
Last Name (Прізвище)
`lastNameRaw`	`'01'`	Match (Збіг)
`lastNameRaw`	`'50'`	Partial Match (Частковий)
`lastNameRaw`	`'99'`	No Match (Немає збігу)
`lastName`	`'Y'`	Yes, Matches (Збігається)
`lastName`	`'O'`	Partial Match (Частковий)
`lastName`	`'N'`	No Match (Немає збігу)

По неуспішному verify платежу токена у відповіді не буде - в колбеці буде фінальний неуспішний статус верифікації "verify_failed".