# Advanced features of Invoice creation ### The Invoice creation API The Invoice creation API endpoint is a complex all-in-one endpoint, that routes a customer to a corresponding payment flow based on the parameters sent be the merchant. This API endpoint accepts several optional parameters that may be used to streamline the customer experience. The full API endpoint specification is available at the end of this page. Below there are the features supported by the Invoice creation API. #### Applications The request to create an invoice may specify application using `applicationId`. This is an optional parameter used to customise the look and feel of the checkout page. Every application contains its own settings set to tailor the checkout page for different needs (example - different brands under the same merchant). #### Pre-populate the form for KYC The KYC flow through the Checkout V2 supports pre-population of fields in case your service already has the personal data of the customers. This function is only available for banking onramp. In order to pre-populate the form add the information into the URL parameters (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: \ 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 to a customer a subset of supported currencies. To do this pass the `displayCurrencies` array. #### Dynamic redirections The API supports `redirectUrl` parameter. The provided URL is used to redirect a customer in case of a failed or successful deposit. ### The Invoice creation API specification {% hint style="info" %} 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. {% endhint %} The customer identifier is a **mandatory** field, which must contain the id of the customer, used in your system. This id is sent back in the callbacks on every deposit in order to link deposits with corresponding customers. The order identifier is an **optional** parameter, which will be sent back to your system with a callback for the deposit linked to this exact invoice. Please read more about invoice currencies [here](https://docs.xgateway.tech/miscellaneous/invoice-currencies). ## Create an invoice for the customer for a specified currency and optional order id. > Creates an invoice using a fixed or floating exchange rate strategy.\ > The invoice is generated based on the provided parameters including amount, base currency, customer ID, order ID (optional).\ > \ > This API creates an invoice and returns a checkout link, that should be served to a customer.\ > \ > If \`paymentCurrency\` is provided and all required activation parameters for a specific payment are included\ > (\`customerFirstName\`, \`customerLastName\`, \`customerEmail\`, \`customerCountry\`, \`customerPhone\`, \`customerAccount\`), the invoice is instantly activated.\ > \ > A base currency in this end point is the currency a customer will typically see on the merchant cashier page.\ > Example: A customer wants to deposit 10 EUR of ETH. In this case the base currency is EUR.\ > \ > A payment currency is the currency that is actually deposited by the customer and available for settlement by the corresponding merchant.\ > Example: A customer wants to deposit 10 EUR of ETH. In this case the payment currency is ETH.\ > \ > Access to this endpoint requires a valid API key. The API key is sent in the \`x-api-key\` header on requests. ```json {"openapi":"3.0.0","info":{"title":"x-gateway-external-api","version":"0.0.1"},"servers":[{"url":"https://api.xgateway.tech/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AppSuccessResponse_string_":{"description":"The AppSuccessResponse object contains general information about the success execution.","properties":{"success":{"type":"boolean","default":true},"data":{"type":"string"}},"required":["success","data"],"type":"object","additionalProperties":false},"AppErrorResponse":{"description":"The AppErrorResponse object contains general information about the error message.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"IAppError":{"description":"The IAppError interface represents an application error message.","properties":{"code":{"anyOf":[{"$ref":"#/components/schemas/AppClientErrorResponseCode"},{"$ref":"#/components/schemas/AppServerErrorResponseCode"}]},"message":{"type":"string"}},"required":["code","message"],"type":"object","additionalProperties":false},"AppClientErrorResponseCode":{"type":"string","enum":["bad_request","db_violation","unauthorized","payment_required","forbidden","not_found","method_not_allowed","not_acceptable","proxy_authentication_required","request_timeout","conflict","db_unique_violation","gone","length_required","precondition_failed","payload_too_large","uri_too_long","unsupported_media_type","range_not_satisfiable","expectation_failed","misdirected_request","unprocessable_content","db_non_null_violation","locked","failed_dependency","upgrade_required","precondition_required","too_many_requests","request_header_fields_too_large","unavailable_for_legal_reasons"],"nullable":false,"description":"The AppClientErrorResponseCode object contains all client error response codes."},"AppServerErrorResponseCode":{"type":"string","enum":["internal_server_error","not_implemented","bad_gateway","service_unavailable","gateway_timeout","http_version_not_supported","variant_also_negotiates","insufficient_storage","loop_detected","not_extended","network_authentication_required"],"nullable":false,"description":"The AppServerErrorResponseCode object contains all server error response codes."},"AppAuthenticationErrorResponse":{"description":"The AppAuthenticationErrorResponse object contains general information about the authentication\nerror.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array","default":[{"code":"unauthorized","message":"You do not have permission to access this resource."}]}},"required":["success","errors"],"type":"object","additionalProperties":false},"AppValidationErrorResponse":{"description":"The AppValidationErrorResponse object contains general information about the validation error.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"CreateInvoiceV2Input":{"properties":{"accountId":{"type":"string"},"amount":{"type":"number","format":"double"},"applicationId":{"type":"string"},"baseCurrency":{"$ref":"#/components/schemas/Currency"},"customerAccount":{"type":"string"},"customerCountry":{"type":"string"},"customerEmail":{"type":"string"},"customerFirstName":{"type":"string"},"customerId":{"type":"string"},"customerLastName":{"type":"string"},"customerPhone":{"type":"string"},"customerDateOfBirth":{"type":"string"},"displayCurrencies":{"anyOf":[{"$ref":"#/components/schemas/Currency"},{"items":{"$ref":"#/components/schemas/Currency"},"type":"array"}]},"invoiceStrategy":{"$ref":"#/components/schemas/InvoiceStrategy"},"locale":{"type":"string"},"orderId":{"type":"string"},"paymentCurrency":{"$ref":"#/components/schemas/Currency"},"redirectUrl":{"type":"string"},"billingAddress":{"properties":{"state":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string"},"city":{"type":"string"},"addressLine2":{"type":"string"},"addressLine1":{"type":"string"}},"required":["state","postalCode","countryCode","city","addressLine1"],"type":"object"}},"required":["amount","baseCurrency","customerId"],"type":"object","additionalProperties":{}},"Currency":{"type":"string","enum":["USDC","USDT","BNB","bUSDT","BTC","ETH","eUSDC","eUSDT","FTN","POL","pUSDC","SOL","sUSDT","TRX","tUSDC","tUSDT","wpUSDC","wpUSDT","EUR","GBP","AZN","BDT","INR","JPY","PKR","RUB","TRY","UZS","AUD","BRL","CAD","CHF","CZK","DKK","KES","NOK","NZD","SEK","USD"],"description":"Represents all currencies in the payment processing system.\n\nUsed to specify the currency of accounts, exchange rates, and transactions in the payment\nprocessing system.\n\nIt provides a controlled and standardized list of supported currencies for all transactions and\nbalances in the payment processing system.\n\nNew currencies can be added to the payment processing system as additional members.\n\nSupported cryptocurrencies:\n- `BNB` - Binance Coin\n- `bUSDT` - Tether (pegged to USD), issued on BNB Smart Chain network (BEP20 token)\n- `BTC` - Bitcoin\n- `ETH` - Ether\n- `eUSDC` - USD Coin (pegged to USD), issued on Ethereum network (ERC20 token)\n- `eUSDT` - Tether (pegged to USD), issued on Ethereum network (ERC20 token)\n- `FTN` - Fasttoken\n- `POL` - POL\n- `pUSDC` - USD Coin (pegged to USD), issued on Polygon network (ERC20 token)\n- `SOL` - SOL\n- `sUSDT` - Tether (pegged to USD), issued on Solana network (SPL token)\n- `TRX` - Tronix (native coin), issued on Tron network\n- `tUSDC` - USD Coin (pegged to USD), issued on Tron network (TRC20 token)\n- `tUSDT` - Tether (pegged to USD), issued on Tron network (TRC20 token)\n- `wpUSDC` - wrapped USD Coin (pegged to USD), issued on Polygon network (ERC20 token)\n- `wpUSDT` - wrapped Tether (pegged to USD), issued on Polygon network (ERC20 token).\n\nSupported fiat currencies:\n- `AZN` - Azerbaijani Manat\n- `BDT` - Bangladeshi Taka\n- `EUR` - Euro\n- `GBP` - Pound Sterling\n- `INR` - Indian Rupee\n- `JPY` - Japanese Yen\n- `KES` - Kenyan Shilling\n- `PKR` - Pakistani Rupee\n- `RUB` - Russian Ruble\n- `TRY` - Turkish Lira\n- `USD` - United States Dollar\n- `UZS` - Uzbekistani Som."},"InvoiceStrategy":{"description":"Represents the possible strategies of an invoice.","enum":["floating","fixed"],"type":"string"}}},"paths":{"/invoices":{"post":{"operationId":"CreateDepositInvoiceAsync","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSuccessResponse_string_"}}}},"400":{"description":"Database violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthenticationErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"422":{"description":"Unprocessable content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppValidationErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}}},"description":"Creates an invoice using a fixed or floating exchange rate strategy.\nThe invoice is generated based on the provided parameters including amount, base currency, customer ID, order ID (optional).\n\nThis API creates an invoice and returns a checkout link, that should be served to a customer.\n\nIf `paymentCurrency` is provided and all required activation parameters for a specific payment are included\n(`customerFirstName`, `customerLastName`, `customerEmail`, `customerCountry`, `customerPhone`, `customerAccount`), the invoice is instantly activated.\n\nA base currency in this end point is the currency a customer will typically see on the merchant cashier page.\nExample: A customer wants to deposit 10 EUR of ETH. In this case the base currency is EUR.\n\nA payment currency is the currency that is actually deposited by the customer and available for settlement by the corresponding merchant.\nExample: A customer wants to deposit 10 EUR of ETH. In this case the payment currency is ETH.\n\nAccess to this endpoint requires a valid API key. The API key is sent in the `x-api-key` header on requests.","summary":"Create an invoice for the customer for a specified currency and optional order id.","tags":["Invoice"],"parameters":[],"requestBody":{"description":"- The input data for creating an invoice.\n\n__Params__:\n- __amount__ - The amount. Must be greater than 0.\n- __applicationId__ - The associated application ID in your system.\n- __baseCurrency__ - The base currency.\n- __customerId__ - The customer ID in the your system.\n- __orderId__ - The associated order ID in the your system.\n- __invoiceStrategy__ - The invoice strategy. \"floating\" || \"fixed\"\n- __displayCurrencies__ - The list of currencies to display to the customer.\n- __customerAccount__ - The Customer Account number in payment system.\n- __customerCountry__ - The ISO 3166-1 alpha-2 country name.\n- __customerEmail__ - The email address.\n- __customerFirstName__ - The first name.\n- __customerLastName__ - The last name.\n- __customerPhone__ - The phone number.\n- __customerDateOfBirth__ - The birth date.\n- __paymentCurrency__ - The currency in which the payment will be made.\n- __redirectUrl__ - The URL to which the customer will be redirected after completing checkout.\n- __billingAddress__ - Full billing address for payment verification.\n- __billingAddress.addressLine1__ - Line 1 of the address (e.g., Number, street, etc).\n- __billingAddress.addressLine2__ - Line 2 of the address (e.g., Suite, apt).\n- __billingAddress.city__ - City name.\n- __billingAddress.countryCode__ - 2-character ISO-3166-1 country code.\n- __billingAddress.postalCode__ - Postal code.\n- __billingAddress.state__ - State code.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceV2Input","description":"- The input data for creating an invoice.\n\n__Params__:\n- __amount__ - The amount. Must be greater than 0.\n- __applicationId__ - The associated application ID in your system.\n- __baseCurrency__ - The base currency.\n- __customerId__ - The customer ID in the your system.\n- __orderId__ - The associated order ID in the your system.\n- __invoiceStrategy__ - The invoice strategy. \"floating\" || \"fixed\"\n- __displayCurrencies__ - The list of currencies to display to the customer.\n- __customerAccount__ - The Customer Account number in payment system.\n- __customerCountry__ - The ISO 3166-1 alpha-2 country name.\n- __customerEmail__ - The email address.\n- __customerFirstName__ - The first name.\n- __customerLastName__ - The last name.\n- __customerPhone__ - The phone number.\n- __customerDateOfBirth__ - The birth date.\n- __paymentCurrency__ - The currency in which the payment will be made.\n- __redirectUrl__ - The URL to which the customer will be redirected after completing checkout.\n- __billingAddress__ - Full billing address for payment verification.\n- __billingAddress.addressLine1__ - Line 1 of the address (e.g., Number, street, etc).\n- __billingAddress.addressLine2__ - Line 2 of the address (e.g., Suite, apt).\n- __billingAddress.city__ - City name.\n- __billingAddress.countryCode__ - 2-character ISO-3166-1 country code.\n- __billingAddress.postalCode__ - Postal code.\n- __billingAddress.state__ - State code."}}}}}}}} ``` #### Extended response for invoice creation This API endpoint returns extended invoice data. ## Creates a new deposit invoice. > Creates a deposit invoice.\ > \ > This endpoint creates a new deposit invoice for the specified merchant.\ > The invoice is created with the specified amount, base currency, and optional order ID.\ > If a payment currency is specified, the invoice will be activated automatically.\ > \ > Returns the generated invoice details.\ > \ > \### Invoice fields\ > \- \`id\` \*(string)\*: Unique invoice identifier.\ > \- \`amount\` \*(number)\*: The amount to deposit.\ > \- \`baseCurrency\` \*(string)\*: The base currency of the deposit.\ > \- \`paymentCurrency\` \*(string | null)\*: The payment currency of the deposit.\ > \- \`customerId\` \*(string)\*: The customer ID in your system.\ > \- \`orderId\` \*(string | null)\*: The associated order ID in your system.\ > \- \`status\` \*(string)\*: The current status of the invoice. Possible values: \`created\`, \`active\`, \`processing\`, \`canceled\`.\ > \- \`createdAt\` \*(string)\*: The date and time when the invoice was created, in ISO 8601 format.\ > \- \`paymentUrl\` \*(string)\*: The URL to which the customer will be redirected after completing checkout.\ > \- \`type\` \*(string)\*: The type of the invoice. Possible values: \`deposit\`.\ > \- \`accountId\` \*(string)\*: The merchant's account ID.\ > \- \`strategy\` \*(string)\*: The invoice strategy. Possible values: \`floating\`, \`fixed\`.\ > \- \`transactions\` \*(array)\*: List of transactions associated with this invoice (empty for newly created invoices). ```json {"openapi":"3.0.0","info":{"title":"x-gateway-external-api","version":"0.0.1"},"servers":[{"url":"https://api.xgateway.tech/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AppSuccessResponse_PublicInvoice_":{"description":"The AppSuccessResponse object contains general information about the success execution.","properties":{"success":{"type":"boolean","default":true},"data":{"$ref":"#/components/schemas/PublicInvoice"}},"required":["success","data"],"type":"object","additionalProperties":false},"PublicInvoice":{"properties":{"amount":{"type":"string"},"baseCurrency":{"$ref":"#/components/schemas/Currency"},"createdAt":{"type":"string"},"customerId":{"type":"string"},"id":{"type":"string"},"status":{"$ref":"#/components/schemas/InvoiceStatus"},"strategy":{"$ref":"#/components/schemas/InvoiceStrategy"},"type":{"$ref":"#/components/schemas/InvoiceType"},"accountId":{"type":"string"},"orderId":{"type":"string"},"paymentCurrency":{"$ref":"#/components/schemas/Currency"},"paymentUrl":{"type":"string"},"transactions":{"items":{"$ref":"#/components/schemas/PublicInvoiceTransaction"},"type":"array"}},"required":["amount","baseCurrency","createdAt","customerId","id","status","strategy","type","transactions"],"type":"object","additionalProperties":false},"Currency":{"type":"string","enum":["USDC","USDT","BNB","bUSDT","BTC","ETH","eUSDC","eUSDT","FTN","POL","pUSDC","SOL","sUSDT","TRX","tUSDC","tUSDT","wpUSDC","wpUSDT","EUR","GBP","AZN","BDT","INR","JPY","PKR","RUB","TRY","UZS","AUD","BRL","CAD","CHF","CZK","DKK","KES","NOK","NZD","SEK","USD"],"description":"Represents all currencies in the payment processing system.\n\nUsed to specify the currency of accounts, exchange rates, and transactions in the payment\nprocessing system.\n\nIt provides a controlled and standardized list of supported currencies for all transactions and\nbalances in the payment processing system.\n\nNew currencies can be added to the payment processing system as additional members.\n\nSupported cryptocurrencies:\n- `BNB` - Binance Coin\n- `bUSDT` - Tether (pegged to USD), issued on BNB Smart Chain network (BEP20 token)\n- `BTC` - Bitcoin\n- `ETH` - Ether\n- `eUSDC` - USD Coin (pegged to USD), issued on Ethereum network (ERC20 token)\n- `eUSDT` - Tether (pegged to USD), issued on Ethereum network (ERC20 token)\n- `FTN` - Fasttoken\n- `POL` - POL\n- `pUSDC` - USD Coin (pegged to USD), issued on Polygon network (ERC20 token)\n- `SOL` - SOL\n- `sUSDT` - Tether (pegged to USD), issued on Solana network (SPL token)\n- `TRX` - Tronix (native coin), issued on Tron network\n- `tUSDC` - USD Coin (pegged to USD), issued on Tron network (TRC20 token)\n- `tUSDT` - Tether (pegged to USD), issued on Tron network (TRC20 token)\n- `wpUSDC` - wrapped USD Coin (pegged to USD), issued on Polygon network (ERC20 token)\n- `wpUSDT` - wrapped Tether (pegged to USD), issued on Polygon network (ERC20 token).\n\nSupported fiat currencies:\n- `AZN` - Azerbaijani Manat\n- `BDT` - Bangladeshi Taka\n- `EUR` - Euro\n- `GBP` - Pound Sterling\n- `INR` - Indian Rupee\n- `JPY` - Japanese Yen\n- `KES` - Kenyan Shilling\n- `PKR` - Pakistani Rupee\n- `RUB` - Russian Ruble\n- `TRY` - Turkish Lira\n- `USD` - United States Dollar\n- `UZS` - Uzbekistani Som."},"InvoiceStatus":{"description":"Represents the possible statuses of an invoice.","enum":["active","canceled","completed","created","processing"],"type":"string"},"InvoiceStrategy":{"description":"Represents the possible strategies of an invoice.","enum":["floating","fixed"],"type":"string"},"InvoiceType":{"description":"Represents the possible types of an invoice.","enum":["deposit","withdrawal"],"type":"string"},"PublicInvoiceTransaction":{"description":"Represents a minimal transaction summary exposed via the public invoice API.","properties":{"id":{"type":"string"},"createdAt":{"type":"string"},"type":{"$ref":"#/components/schemas/TransactionType"},"status":{"type":"string","description":"Lowercased {@link NewTransactionStatus } value, e.g. `\"confirmed\"`, `\"processing\"`."}},"required":["id","createdAt","type","status"],"type":"object","additionalProperties":false},"TransactionType":{"description":"Represents the possible types of a transaction.\n\nUsed to categorize transactions by their nature.","enum":["activation_expense","cancellation","cash_out","change","chargeback","consolidation","consolidation_expense","correction_down","correction_up","deposit","merchant_deposit","money_out_expense","settlement","settlement_expense","shadow_deposit","withdrawal"],"type":"string"},"AppErrorResponse":{"description":"The AppErrorResponse object contains general information about the error message.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"IAppError":{"description":"The IAppError interface represents an application error message.","properties":{"code":{"anyOf":[{"$ref":"#/components/schemas/AppClientErrorResponseCode"},{"$ref":"#/components/schemas/AppServerErrorResponseCode"}]},"message":{"type":"string"}},"required":["code","message"],"type":"object","additionalProperties":false},"AppClientErrorResponseCode":{"type":"string","enum":["bad_request","db_violation","unauthorized","payment_required","forbidden","not_found","method_not_allowed","not_acceptable","proxy_authentication_required","request_timeout","conflict","db_unique_violation","gone","length_required","precondition_failed","payload_too_large","uri_too_long","unsupported_media_type","range_not_satisfiable","expectation_failed","misdirected_request","unprocessable_content","db_non_null_violation","locked","failed_dependency","upgrade_required","precondition_required","too_many_requests","request_header_fields_too_large","unavailable_for_legal_reasons"],"nullable":false,"description":"The AppClientErrorResponseCode object contains all client error response codes."},"AppServerErrorResponseCode":{"type":"string","enum":["internal_server_error","not_implemented","bad_gateway","service_unavailable","gateway_timeout","http_version_not_supported","variant_also_negotiates","insufficient_storage","loop_detected","not_extended","network_authentication_required"],"nullable":false,"description":"The AppServerErrorResponseCode object contains all server error response codes."},"AppAuthenticationErrorResponse":{"description":"The AppAuthenticationErrorResponse object contains general information about the authentication\nerror.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array","default":[{"code":"unauthorized","message":"You do not have permission to access this resource."}]}},"required":["success","errors"],"type":"object","additionalProperties":false},"AppValidationErrorResponse":{"description":"The AppValidationErrorResponse object contains general information about the validation error.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"CreateInvoiceV2Input":{"properties":{"accountId":{"type":"string"},"amount":{"type":"number","format":"double"},"applicationId":{"type":"string"},"baseCurrency":{"$ref":"#/components/schemas/Currency"},"customerAccount":{"type":"string"},"customerCountry":{"type":"string"},"customerEmail":{"type":"string"},"customerFirstName":{"type":"string"},"customerId":{"type":"string"},"customerLastName":{"type":"string"},"customerPhone":{"type":"string"},"customerDateOfBirth":{"type":"string"},"displayCurrencies":{"anyOf":[{"$ref":"#/components/schemas/Currency"},{"items":{"$ref":"#/components/schemas/Currency"},"type":"array"}]},"invoiceStrategy":{"$ref":"#/components/schemas/InvoiceStrategy"},"locale":{"type":"string"},"orderId":{"type":"string"},"paymentCurrency":{"$ref":"#/components/schemas/Currency"},"redirectUrl":{"type":"string"},"billingAddress":{"properties":{"state":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string"},"city":{"type":"string"},"addressLine2":{"type":"string"},"addressLine1":{"type":"string"}},"required":["state","postalCode","countryCode","city","addressLine1"],"type":"object"}},"required":["amount","baseCurrency","customerId"],"type":"object","additionalProperties":{}}}},"paths":{"/invoices/extended":{"post":{"operationId":"CreateDepositInvoiceAsyncExtended","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSuccessResponse_PublicInvoice_"}}}},"400":{"description":"Database violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthenticationErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"422":{"description":"Unprocessable content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppValidationErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}}},"description":"Creates a deposit invoice.\n\nThis endpoint creates a new deposit invoice for the specified merchant.\nThe invoice is created with the specified amount, base currency, and optional order ID.\nIf a payment currency is specified, the invoice will be activated automatically.\n\nReturns the generated invoice details.\n\n### Invoice fields\n- `id` *(string)*: Unique invoice identifier.\n- `amount` *(number)*: The amount to deposit.\n- `baseCurrency` *(string)*: The base currency of the deposit.\n- `paymentCurrency` *(string | null)*: The payment currency of the deposit.\n- `customerId` *(string)*: The customer ID in your system.\n- `orderId` *(string | null)*: The associated order ID in your system.\n- `status` *(string)*: The current status of the invoice. Possible values: `created`, `active`, `processing`, `canceled`.\n- `createdAt` *(string)*: The date and time when the invoice was created, in ISO 8601 format.\n- `paymentUrl` *(string)*: The URL to which the customer will be redirected after completing checkout.\n- `type` *(string)*: The type of the invoice. Possible values: `deposit`.\n- `accountId` *(string)*: The merchant's account ID.\n- `strategy` *(string)*: The invoice strategy. Possible values: `floating`, `fixed`.\n- `transactions` *(array)*: List of transactions associated with this invoice (empty for newly created invoices).","summary":"Creates a new deposit invoice.","tags":["Invoice"],"parameters":[],"requestBody":{"description":"- Input data for creating an invoice.\n__Parameters__:\n- __amount__ - The amount. Must be greater than 0.\n- __applicationId__ - The associated application ID in your system.\n- __baseCurrency__ - The base currency.\n- __customerId__ - The customer ID in your system.\n- __orderId__ - The associated order ID in your system (optional).\n- __invoiceStrategy__ - The invoice strategy. Possible values: `\"floating\"` or `\"fixed\"`.\n- __displayCurrencies__ - The list of currencies to display to the customer.\n- __customerAccount__ - The customer account number in the payment system.\n- __customerCountry__ - The ISO 3166-1 alpha-2 country code.\n- __customerEmail__ - The email address.\n- __customerFirstName__ - The first name.\n- __customerLastName__ - The last name.\n- __customerPhone__ - The phone number.\n- __customerDateOfBirth__ - The birth date.\n- __paymentCurrency__ - The currency in which the payment will be made (optional).\n- __redirectUrl__ - The URL to which the customer will be redirected after completing checkout.\n- __locale__ - The locale in which checkout page will be displayed (optional).\n- __billingAddress__ - Full billing address for payment verification.\n- __billingAddress.addressLine1__ - Line 1 of the address (e.g., Number, street, etc).\n- __billingAddress.addressLine2__ - Line 2 of the address (e.g., Suite, apt).\n- __billingAddress.city__ - City name.\n- __billingAddress.countryCode__ - 2-character ISO-3166-1 country code.\n- __billingAddress.postalCode__ - Postal code.\n- __billingAddress.state__ - State code.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceV2Input","description":"- Input data for creating an invoice.\n__Parameters__:\n- __amount__ - The amount. Must be greater than 0.\n- __applicationId__ - The associated application ID in your system.\n- __baseCurrency__ - The base currency.\n- __customerId__ - The customer ID in your system.\n- __orderId__ - The associated order ID in your system (optional).\n- __invoiceStrategy__ - The invoice strategy. Possible values: `\"floating\"` or `\"fixed\"`.\n- __displayCurrencies__ - The list of currencies to display to the customer.\n- __customerAccount__ - The customer account number in the payment system.\n- __customerCountry__ - The ISO 3166-1 alpha-2 country code.\n- __customerEmail__ - The email address.\n- __customerFirstName__ - The first name.\n- __customerLastName__ - The last name.\n- __customerPhone__ - The phone number.\n- __customerDateOfBirth__ - The birth date.\n- __paymentCurrency__ - The currency in which the payment will be made (optional).\n- __redirectUrl__ - The URL to which the customer will be redirected after completing checkout.\n- __locale__ - The locale in which checkout page will be displayed (optional).\n- __billingAddress__ - Full billing address for payment verification.\n- __billingAddress.addressLine1__ - Line 1 of the address (e.g., Number, street, etc).\n- __billingAddress.addressLine2__ - Line 2 of the address (e.g., Suite, apt).\n- __billingAddress.city__ - City name.\n- __billingAddress.countryCode__ - 2-character ISO-3166-1 country code.\n- __billingAddress.postalCode__ - Postal code.\n- __billingAddress.state__ - State code."}}}}}}}} ``` #### Headers
NameTypeDescription
x-api-key*StringYour API key
#### 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 will set an expiration time according to invoice TTL. Once an invoice has expired, the link will show an error. You can make several requests for the same customer with a different amount/base currency and get a different checkout link back. #### Under and over payment Please review [this page](https://docs.xgateway.tech/payment-flows#invoice) to get more information about cases, when a customer overpays an invoice, underpays an invoice or does a deposit with no invoice at all.