Skip to content

Advanced features of Invoice creation#

Invoice Creation APIs overview#

Invoice creation is the first step in a payment procedure, initiated by the merchant.

XGateway provides base (/invoices) and extended (/invoices/extended) API endpoints for this task. Both are complex, all-in-one endpoints that route the customer to the appropriate payment flow based on the parameters sent by the merchant.

The main difference is that the base endpoint always returns a redirect URL to the checkout page, where the customer must enter additional information and activate the invoice. The extended endpoint can collect optional fields from the merchant request and may skip the checkout page entirely if enough data is provided to activate the invoice automatically. This endpoint accepts several optional parameters that can be used to streamline the customer experience. It is slightly more complex to use but offers better customer conversion.

Both methods support custom application IDs, KYC field pre-population, displayed currencies, dynamic redirect features, and more. Full descriptions and OpenAPI specifications for both endpoints are provided below.

Custom Applications#

The request to create an invoice may specify an application using applicationId. This is an optional parameter used to customise the look and feel of the checkout page. Each application contains its own settings, allowing the checkout page to be tailored for different needs (e.g., different brands under the same merchant).

Pre-populating the form for KYC#

The KYC flow in Checkout V2 supports pre-populating fields if your service already has customer personal data.

This feature is currently available only for banking on-ramp.

To pre-populate the form, include the relevant information as URL (query) parameters when working with an invoice. See the example below:

Query Params

Used to pre-fill customer data on the checkout page.

  • firstName
  • lastName
  • email
  • address1
  • address2
  • postCode
  • city
  • country: (ISO 3166-1 alfa-2 country code)
  • dateOfBirth: YYYY-MM-DD
  • sourceOfFunds: SALARY, BUSINESS_INCOME, PENSION, OTHER

Add all or some query params to a URL. Example of usage:

https://checkout.xgateway.dev/v2/invoice/4f61498c-6e80-4b15-a88a-b7e5a29292bd?firstName=John&lastName=Doe&email[email protected]&address1=Some-Street 12 tn.2&address2=ap.3&postCode=12345&city=New York&country=US&dateOfBirth=1984-09-09&sourceOfFunds=SALARY

Displayed currencies#

It is possible to show the customer a subset of supported currencies. To do this, pass the displayCurrencies array with the desired subset (see the endpoint specification below for supported currency symbols).

Dynamic redirections#

The API supports the redirectUrl parameter. The provided URL is used to redirect the customer in case of a successful or failed deposit.

Invoice creation APIs specification#

Note, that baseCurrency parameter defines the expected currency of the deposit. It does not change or affect the reference currency - the currency used for all the internal accounting for you as a merchant.

The customer identifier is a mandatory field and must contain the id of the customer used in your system. This ID is returned in callbacks for every deposit in order to link deposits with the corresponding customers.

The order identifier is an optional parameter that will be sent back to your system in a callback for the deposit linked to this specific invoice.

Please read more about invoice currencies on the invoice currencies page.

Two methods can be used: the base method returns checkout link to complete invoice setup; the extended method activates invoice automatically and returns extended invoice data.

POST

Extended invoice creation method (returns extended invoice data)#

POST

Session Time To Live#

Invoices, at the moment of creation, have no expiration time. After invoice activation on the checkout page (when the customer selects the payment currency and clicks "Proceed"), the system sets an expiration time according to the invoice TTL. Once an invoice has expired, the link will display an error.

You can make several requests for the same customer with a different amounts or base currencies and receive different checkout links.

Under- and Overpayment#

Please review the payment flows page for more information about cases where a customer overpays an invoice, underpays an invoice, or makes a deposit without an invoice.