Skip to content

Host-to-host Integration for Payments

Intro

Organisations that meet PCI DSS requirements can use Host-to-Host (H2H) integration to accept card payments.

Please apply a request to our support team to clarify the requirements and enable H2H payment mode for your account.

H2H Interaction Scheme

H2H scheme

Create Payment Invoice

Endpoint: /payment-invoices

Method: POST

Samples (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_eqUNbE6SpIEmRB2K",
    "attributes":{  
       "status":"process_pending",
       "resolution":"ok",
       "moderation_required":false,
       "amount":17,
       "payment_amount":17,
       "currency":"USD",
       "service_currency":"USD",
       "reference_id":"{guid}",
       "test_mode":true,
       "fee":0,
       "deposit":17,
       "processed":null,
       "processed_amount":null,
       "processed_fee":null,
       "processed_deposit":null,
       "metadata":[  

       ],
       "flow_data":{  
          "action":"https://our.pay_domain/hpp/7b3df799-5608-56fa-a26b-5a9b3c26bb5c",
          "method":"GET",
          "params":[  

          ],
          "metadata":{  
             "sid":"7b3df799-5608-56fa-a26b-5a9b3c26bb5c",
             "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9...fGbuc"
          }
       },
       "flow":"hpp",
       "created":1567434682,
       "updated":1567434682,
       "payload":[  

       ],
       "description":"Payment by order#1",
       "callback_url":"api.paymega.io/payments/callback",
       "return_url":"api.paymega.io"
    },
    "relationships":{  
       "payment-service":{  
          "data":{  
             "type":"payment-services",
             "id":"payment_card_uah_hpp"
          }
       },
       "payment-method":{  
          "data":{  
             "type":"payment-methods",
             "id":"payment_card"
          }
       },
       "customer":{  
          "data":null
       }
    },
    "links":{  
       "self":"/api/payment-invoices/cpi_eqUNbE6SpIEmRB2K"
    }
  }
}

Send Card Data to the Gateway

API URL: issued by the manager before integration beginning

Endpoint: /payment/sale

Method: POST

Authentication: bearerToken (send the token parameter from response on request, flow_data object → metadata)

If a card does not require 3DS authentication, but the payment provider has returned an transitional status (process_pending), you should wait for the Callback message or make a reconciliation of the payment by invoice ID or reference ID.

And, in addition to the required card data attributes, it is also possible to transfer information about optional parameters of the client’s browser in the browser_info object*.

Samples (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", // Time zone
            "browser_screen_width": "1920" // The width of the customer's screen in pixels
            }
        }
    }
}
{
    "status":"auth_required",
    "auth_mode":"3ds",
    "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":"https://api.paymega.io/3ds-return?pid=pay_Hjh3kMlNdqE4WpOmNPCoIgFU_K1_nM"
        }
    }
}
{
    "status": "processed",
    "auth_mode": null,
    "auth_payload": []
}
* Possible properties of the browser_info object
Property Type Description Example
browser_accept_header string HTTP accept headers as sent by the browser application/json, text/plain, */
browser_color_depth string Browser color depth 24
browser_ip string IP address returned by the browser 123.123.12.1
browser_java_enabled boolean Whether the browser can execute Java false
browser_language string Browser language (ISO code) en-US
browser_screen_height string Total height of the customer's screen in pixels 1200
browser_screen_width string Total width of the customer's screen in pixels 1920
browser_tz string Time difference between UTC time and the customer's browser local time, in minutes -120
browser_user_agent string Exact content of the HTTP user-agent header sent by the browser Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.135 Safari/537.36
device_channel string Device channel ID 02
window_height string Height of the customer's browser window in pixels 1200
window_width string Width of the customer's browser window in pixels 1920

(for 3DS Flow) Client Redirect to ACS

The auth_payload object contains 3DS data in the Card Gate request response.

Send to action URL the form's parameters params by method method.

In the parameters for 3DS Flow 1.0, you send:

  • MD (Merchant Data, a link number to identify the transaction on the merchant side),
  • PaReq (Payer Authentication Request, the DIBS server response message),
  • TermUrl (Merchant website URL to which the authenticating bank send the payer after completing the authentication).

In the parameters for 3DS Flow 1.0, you send:

  • creq (Challenge Request Message that initiate the transaction)

Samples (JSON)

{
"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="
        }
    }
}