Skip to content

Host-to-host Integration for Payments

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

  1. The client creates an order on the merchant's website.
  2. To give the client a choice of payment options, the merchant sends a payment pre-request and receives a response from the PaymentsTrust platform with a list of available methods.

  3. The merchant displays the list of methods, and the client chooses the convenient way to pay for the order.

    You can skip acts 2 and 3

    Sending a payment pre-request is unnecessary if the merchant has defined a payment method for the client and creates a payment invoice after the order creation.

  4. The merchant creates a payment invoice. Having received the invoice, PaymentsTrust:

    • Initiates a transaction on the provider side
    • Sends a reply with the payment's bearer token
    • Sends a Callback to the merchant notifying him of the successful creation of the invoice

  5. Merchant displays payment form data on its side.

  6. The client enters payment details that the merchant sends to the PaymentsTrust Card Gateway. And PaymentsTrust forwards the debit request to the issuer.
  7. If an additional step of payment confirmation is required (3DSecure or another verification type), the merchant receives the data to display the verification page. The client confirms the payment, and the issuer obtains the sent data.
  8. The issuer returns the payment results and completes the transaction.
  9. The payment status is recorded and forwarded to the merchant.
  10. The merchant displays the payment status to the client on the pages of the website page.
  11. PaymentsTrust sends a Callback to the merchant notifying them of the payment status.
  12. The merchant can reconcile payment by ID or get a complete list of invoice data using a private API to check transaction status. Daily transactional reports are also available on the portal.

Create Payment Invoice

Authentication parameters

Access the h2h connection by BasicAuth standard via private API.

Use Account ID as Login (Username) and API key as Password: find these settings in the Account Integration section.

API: PRIVATE

Endpoint: /payment-invoices

Authentication: BasicAuth

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://test.example.com/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":"https://test.example.com/payments/callback",
       "return_url":"https://test.example.com/payments/return"
    },
    "relationships":{  
       "payment-service":{  
          "data":{  
             "type":"payment-services",
             "id":"payment_card_usd_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: CARDGATE (URL issued by the manager before integration beginning)

Endpoint: /payment/sale

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

Method: POST

If a card doesn't 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's 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": "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": []
}
* 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 for the Card Gate request response.

You should send to action URL the form's parameters params by method method. Meanwhile, these parameters and their names may change depending on the acquirer standards.

Warning

Payload parameters will be diffrerent depending on the acquiring bank and authorisation type.

auth_payload examples (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"
            }
    }
}

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