Host to host (Gateway8)#

Card payments involve multiple parties and several validation steps. Merchants initiate payments, cardholders provide their details and may be required to complete 3DS authentication.

Host to host integration enables merchants to bypass the XGateway checkout page and receive the confirmation or 3DS URL directly, provided all required fields are correctly supplied and pass validation.

Brief#

In order to create a Fixed Rate Invoice in the payment processing system, auto-activate it and get the link to the 3DS you need to make a POST request to the v2/gateway8 API endpoint.

{
  "amount": 10,
  "baseCurrency": "EUR",
  "customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
  "customerEmail": "[email protected]",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "customerPhone": "49 15123456789",
  "customerDateOfBirth": "2000-02-10",
  "accountId": "a67ec03c-0253-4c14-9961-28985186f90c",
  "userIp": "217.138.202.40",
  "billingAddress": {
    "addressLine1": "Hlavni mesto Praha 11 22",
    "city": "Prague",
    "countryCode": "CZ",
    "postalCode": "15000",
    "state": "Praha, Hlavni mesto"
  },
  "card": {
    "cardNumber": "4000 0000 0000 0002",
    "cardholderName": "John Doe",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "cardSecurityCode": "444"
  }
}

The API will return one of two successful states or a structured error.

{
  "data": {
    "threeDSURL": "https://secure-pay.example.com/auth",
    "message": "Invoice has been successfully activated. 3DS verification is required."
  },
  "success": true
}

{
  "data": {
    "threeDSURL": null,
    "message": "The invoice has been successfully finalized."
  },
  "success": true
}

{
  "errors": [
    {
      "code": "too_big",
      "maximum": 4,
      "type": "string",
      "inclusive": true,
      "exact": false,
      "message": "String must contain at most 4 character(s)",
      "path": [
        "card",
        "expiryYear"
      ]
    }
  ],
  "success": false
}

Details#

Acquirer banks use their own heuristics to decide if additional checks are needed, and these rules can change between sandbox and production environments. As a result, sandbox testing is essential, but it cannot fully replicate live behavior. Real acquirer and issuer bank decisions may differ.

The more accurately the cardholder data matches what is on file with the issuer bank, the higher the acceptance rate. XGateway cannot guarantee that a specific set of user data will or will not trigger acquirer heuristics, nor can we guarantee issuer acceptance of 3DS validation results.

Always test your integration in the Demo environment first. Keep in mind that demo and production environments may behave differently due to acquirer and issuer anti-fraud heuristics. While sandbox testing helps prevent issues, it cannot fully replicate live processing, and failed transactions in production may still occur if anti-fraud rules are triggered.
Data formats, callback handling, and redirect logic could still be tested that way.

Validating limits#

The minimum and maximum amount values for Gateway8 operations:

Contact the support team if you want to confirm the limits.

Required payload#

Please check the blocked countries list on the global cards processing page.

All parameters marked as Mandatory below are required to properly bypass the user input needed from Acquirer side.

Four additional parameters could be used to customize certain parameters of the invoice creation, but these are not required to create the invoice:

Payload examples#

{
  "amount": 10,
  "baseCurrency": "EUR",
  "customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
  "customerEmail": "[email protected]",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "customerPhone": "49 15123456789",
  "customerDateOfBirth": "2000-02-10",
  "accountId": "a67ec03c-0253-4c14-9961-28985186f90c",
  "userIp": "217.138.202.40",
  "billingAddress": {
    "addressLine1": "Hlavni mesto Praha 11 22",
    "city": "Prague",
    "countryCode": "CZ",
    "postalCode": "15000",
    "state": "Praha, Hlavni mesto"
  },
  "card": {
    "cardNumber": "4000 0000 0000 0408",
    "cardholderName": "John Doe",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "cardSecurityCode": "444"
  }
}

{
  "amount": 10,
  "baseCurrency": "EUR",
  "customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
  "customerEmail": "[email protected]",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "customerPhone": "49 15123456789",
  "customerDateOfBirth": "2000-02-10",
  "orderId": "XBNfu922e2",
  "accountId": "a67ec03c-0253-4c14-9961-28985186f90c",
  "redirectUrl": "https://xgateway.tech",
  "userIp": "217.138.202.40",
  "billingAddress": {
    "addressLine1": "Hlavni mesto Praha 11 22",
    "addressLine2": "Suite 56",
    "city": "Prague",
    "countryCode": "CZ",
    "postalCode": "15000",
    "state": "Praha, Hlavni mesto"
  },
  "card": {
    "cardNumber": "4000 0000 0000 0002",
    "cardholderName": "John Doe",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "cardSecurityCode": "444"
  }
}

API Response#

After a successful call, you will receive a 201 - Created response with either

The API will return one of two successful states or a structured error.

{
  "data": {
    "threeDSURL": "https://secure-pay.example.com/auth",
    "message": "Invoice activated. 3DS verification required."
  },
  "success": true
}

{
  "data": {
    "threeDSURL": null,
    "message": "The invoice has been successfully finalized."
  },
  "success": true
}

{
  "errors": [
    {
      "code": "too_big",
      "maximum": 4,
      "type": "string",
      "inclusive": true,
      "exact": false,
      "message": "String must contain at most 4 character(s)",
      "path": [
        "card",
        "expiryYear"
      ]
    }
  ],
  "success": false
}

The API returns structured error message and 422 code in case of any issues with the input data.

For cases of general API failure (example - failure on the banking partner side) the 500 code will be returned.

Testing on Demo environment#

Test cards#

Please use the following data to simulate deposits in the Demo Environment.

3DS testing limitation#

Currently it is not possible to get a 'Success, no 3DS required' response from API Response section on Demo.
The scenario can be tested though:
The card 4000 0000 0000 0408 (non-3DS enrolled) will still return a successful response

{
  "data": {
    "threeDSURL": "https://app-demo...1234",
    "message": "Invoice has been successfully activated. 3DS verification is required."
  },
  "success": true
}

The URL provided in the response will automatically 'pass' the check and perform one more redirect (if specified in redirectURL).

OpenAPI specification#