Host to host (Gateway10)#

This is an integration document applicable to the host-to-host IGaming payment integrations for Visa/Mastercard.
Card payments involve multiple parties and several validation steps. Merchants initiate payments, cardholders provide their details and may be required to complete 3DS authentication.

Before proceeding with this integration, the merchant must complete the standard onboarding process and obtain the following resources from the support team:

Merchant API key
Must be included in the x-api-key request header for most API endpoints.
Merchant Secret key
Used to validate callback payload signatures.
Active account for the target currency
The account must be created and activated before integration begins.
For Gateway10 operations, the transaction base currency must match the configured account ID.

Demo and Prod environments use different API and Secret keys

Optionally, merchants may configure and register a callback endpoint in the XGateway system to receive asynchronous payment updates. See the callbacks documentation for more details.

Brief#

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.
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/gateway10 API endpoint.

POST https://api.xgateway.tech/api/v2/gateway10

EUR Host to Host deposits with auto activation payload

{
  "amount": 10,
  "baseCurrency": "EUR",
  "customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
  "customerEmail": "[email protected]",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "customerPhone": "49 15123456789",
  "customerCity": "Prague",
  "customerState": "Praha, Hlavni mesto",
  "customerStreet": "Hlavni mesto Praha 11 22",
  "customerCountry": "CZ",
  "customerPostCode": "15000",
  "accountId": "a67ec03c-0253-4c14-9961-28985186f90c",
  "ip": "217.138.202.40",
  "card": {
    "cardNumber": "4000 0000 0000 0002",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "cardSecurityCode": "444"
  }
}

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

Success, 3DS required (201)Success, no 3DS required (201)Validation Error (422)

If the issuer requires 3D Secure verification, you must redirect the user to the threeDSURL.

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

If 3DS is not required (frictionless flow), the threeDSURL will be null.

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

Returned if input data fails basic validation (e.g., type mismatch, failed validation).
For example, for 5-digit expiry year you will see

{
  "errors": [
    {
      "code": "too_big",
      "maximum": 4,
      "type": "string",
      "inclusive": true,
      "exact": true,
      "message": "String must contain exactly 4 character(s)",
      "path": [
        "body",
        "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.

POST https://api.demo.xgateway.tech/api/v2/gateway10

Validating limits#

The minimum and maximum amount values for Gateway10 operations:

Currency	Min value	Max value	Increment step
EUR	10.00	5 000.00	0.01
USD	10.00	5 000.00	0.01

On the Demo environment, please use narrower amounts margins - between 20.00 and 150.00 - to ensure stable processing.

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.

Parameter	Type	Mandatory	Description
amount	Number	true	Requested payment amount. Must be greater than zero, with 0 to 2 decimal places. Limits apply
accountId	String	true	Merchant's account ID associated with the payment. Accounts are set up for a specific currency during onboarding
baseCurrency	String	true	String representation of the requested currency (e.g., `EUR`, `USD`), must match the account
customerId	String	true	Customer's id in the merchant system
customerEmail	String	true	Customer's email
customerFirstName	String	true	Customer's First name
customerLastName	String	true	Customer's Last name
customerPhone	String	true	Customer's phone number, including country code, f.e. "3725068189"
customerCity	String	true	Customer's billing city
customerState	String	true	Customer's billing state/region
customerStreet	String	true	Customer's billing street address
customerCountry	String	true	ISO 3166-1 alpha-2 code (e.g., `US`, `CZ`)
customerPostCode	String	true	Customer's billing zip/postal code
ip	String	true	Customer's IP passed as a string, e.g. `217.138.202.40`
`card`
`card`.cardNumber	String	true	Card PAN. In most cases all non-numeric characters will be ignored, but we advise to follow the 4-group whitespace-delimited format, 15-16 digit card numbers, f.e. `4000 0000 0000 0002`
`card`.expiryMonth	String	true	Card expiration month, 2 digits
`card`.expiryYear	String	true	Card expiration year, 4 digits
`card`.cardSecurityCode	String	true	CVV/CVC code, 3 to 4 digits

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

Parameter	Type	Mandatory	Description
invoiceStrategy	String	false	Invoice strategy, `fixed` \| `floating` values allowed. This method defaults to `fixed`
orderId	String	false	Invoice id in the merchant system. If provided, used as an idempotency key
applicationId	String	false	Application ID for tracking purposes
redirectUrl	String	false	Full URL including the protocol, like `https://redirect-url.com`, to which the user will be redirected after a successful 3DS check

Payload examples#

Host to host Gateway10 deposits, mandatory fields providedFull Host to host Gateway10 deposits flow

Host to host Gateway10 Card deposits (EUR / USD), test card 4000 0000 0000 0408 on Demo will trigger the automatic 3DS validation

{
  "amount": 10,
  "baseCurrency": "EUR",
  "customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
  "customerEmail": "[email protected]",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "customerPhone": "49 15123456789",
  "customerCity": "Prague",
  "customerState": "Praha, Hlavni mesto",
  "customerStreet": "Hlavni mesto Praha 11 22",
  "customerCountry": "CZ",
  "customerPostCode": "15000",
  "accountId": "a67ec03c-0253-4c14-9961-28985186f90c",
  "ip": "217.138.202.40",
  "card": {
    "cardNumber": "4000 0000 0000 0408",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "cardSecurityCode": "444"
  }
}

Host to host Gateway10 Card deposits (EUR / USD), test card 4000 0000 0000 0002 on Demo will trigger manual 3DS validation

{
  "amount": 10,
  "baseCurrency": "EUR",
  "customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
  "customerEmail": "[email protected]",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "customerPhone": "49 15123456789",
  "customerCity": "Prague",
  "customerState": "Praha, Hlavni mesto",
  "customerStreet": "Hlavni mesto Praha 11 22",
  "customerCountry": "CZ",
  "customerPostCode": "15000",
  "orderId": "XBNfu922e2",
  "accountId": "a67ec03c-0253-4c14-9961-28985186f90c",
  "redirectUrl": "https://xgateway.tech",
  "ip": "217.138.202.40",
  "card": {
    "cardNumber": "4000 0000 0000 0002",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "cardSecurityCode": "444"
  }
}

optional orderId and redirectUrl fields specified.

On Demo this payload will create a mock 3DS validation.

After approval there will be a redirect to the url provided ( https://xgateway.tech)

API Response#

After a successful call, you will receive a 201 - Created response with one of the two successful states, or a 422 response with a structured error.

Success, 3DS required (201)Success, no 3DS required (201)Validation Error (422)

If the issuer requires 3D Secure verification, you must redirect the user to the threeDSURL.

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

If 3DS is not required (frictionless flow), the threeDSURL will be null.

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

Returned if input data fails basic validation (e.g., type mismatch, failed validation).

{
  "errors": [
    {
      "code": "too_big",
      "maximum": 4,
      "type": "string",
      "inclusive": true,
      "exact": true,
      "message": "String must contain exactly 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.

Test cards data

Card number	Test scenario
4000 0000 0000 0002	3DS, successful authorisation

Only use currencies configured for your account, otherwise the endpoint will return a generic error!

3DS testing limitation#

Currently it is not possible to get a 'Success, no 3DS required' response from API Response section on Demo.
Environment is limited to happy cases.

OpenAPI specification#

POST