# Create an Invoice Request to create a new invoice (payment request). POST [https://app.goodpayments.io/v1/api/payment/create](https://app.goodpayments.io/v1/api/payment/create) ### Headers | Name | Type | Description | Example | | --------------- | ------ | ----------------------- | ---------------------------------------------------------------- | | Authorization\* | string | Unique Merchant API Key | 94a48138b1f41b9cdb3e12c2ff0c7cbe1c7a5f50a311a5054b903cad84215662 | ### Request Body | Name | Type | Description | Example | | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | | type\* | string | Invoice type. `SINGLE` – temporary address; `MULTIPLE` – static address | SINGLE | | amount\* | number | Invoice amount in USD | 10 | | currencies\* | string |

List of accepted tokens. Possible values:

| \["USDT", "TRX"] | | expiry\_minutes | integer | Time period during which the invoice remains active (in minutes) | 30 | | client\_comission | boolean |

Flag that determines who pays the forwarding fee. Only for SINGLE invoice type.

| true / false | | order\_id | string | Order identifier in the merchant's system. Maximum 256 characters | 12345 | | webhook\_url | string | The URL to which goodPayments will send a webhook after the customer completes the payment | | | redirect\_url | string | The URL where the customer will be redirected after completing the payment | | | description | string | Order description: may contain any provided information related to the order | Payment for order #123 | {% hint style="info" %} For static addresses (`MULTIPLE`), the fields `amount`, `redirect_url`, and `expiry_minutes` are optional and are ignored. {% endhint %} ### **Request** **Example** ```yaml curl -X 'POST' \ 'https://app.goodpayments.io/v1/api/payment/create' \ -H 'accept: application/json' \ -H 'Authorization: 94a48138b1f41b9cdb3e12c2ff0c7cbe1c7a5f50a311a5054b903cad84215662' \ -H 'Content-Type: application/json' \ -d '{ "type": "SINGLE", "amount": 10, "currencies": [ "TRX", "USDT" ], "expiry_minutes": 30 }' ``` ### Response Parameters | Name | Type | Description | Example | | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | | id | integer | Unique invoice ID | 123477361 | | status | string |

Invoice status. Possible values:

| COMPLETED | | type | string | Invoice type. `SINGLE` – temporary address; `MULTIPLE` – static address | SINGLE | | paymentURL | string | Payment page URL | | | amount | number | Invoice amount in USD | 1 | | currencies | string |

List of accepted tokens. Possible values:

  • TRX
  • USDT
  • TRX, USDT
| \["USDT", "TRX"] | | currencies\_amounts | string | Amount to be paid in each accepted token | "TRX": 3.6329 | | transfer\_amounts | string | Actual received amount | "TRX": 3.6329 | | cost | number | Service fee charged for processing the payment | 6.5 | | order\_id | string | Order identifier in the merchant's system | 12345 | | address | string | Generated payment address | TBi3zPSQ8JszpkkgwZL4kZWDjXEZsi9Fze | | client\_comission | boolean |

Flag that determines who pays the forwarding fee. Only for SINGLE invoice type.

  • true – the fee is charged to the client. The invoice amount is increased by the fee, and the client pays the total amount.
  • false – the fee is paid by the merchant.
| true / false | | webhook\_url | string | The URL to which goodPayments will send a webhook after the customer completes the payment | | | redirect\_url | string | The URL where the customer will be redirected after completing the payment | | | description | string | Order description: may contain any provided information related to the order | Payment for order #123 | | merchant\_contact | string | Merchant contact details | @username | | target\_wallets | object | An object containing a list of addresses and the amount to be sent to each address (for invoices with type `MULTIPLE_TRANSFER`). | | | expired\_at | string | Invoice expiration timestamp | 2025-11-23T14:28:57.786076+00:00 | | created\_at | string | Invoice creation timestamp | 2025-11-23T13:58:57.789617+00:00 | ### Response Example {% tabs %} {% tab title="200 Success" %} ```json { "id": 336575574, "status": "ACTIVE", "type": "SINGLE", "paymentURL": "https://app.goodpayments.io/payment/336575574", "amount": 10, "currencies": [ "TRX", "USDT" ], "currencies_amounts": { "TRX": 33.402357, "USDT": 10 }, "transfer_amounts": { "input": { "TRX": 0, "USDT": 0 }, "output": { "TRX": 0, "USDT": 0 } }, "cost": null, "client_commission": true, "order_id": null, "address": "TRWvSiQzhSpLdRAmwDHKtgd7bZb2G2be53", "webhook_url": null, "redirect_url": null, "description": "", "merchant_contact": "@username", "target_wallets": {}, "expired_at": "2026-03-17T11:59:07.515594+03:00", "created_at": "2026-03-17T11:29:07.518981+03:00" } ``` {% endtab %} {% tab title="400 User's target wallet address is not set" %} ```json { "detail": "User's target wallet address is not set" } ``` {% endtab %} {% tab title="403 Authentication credentials were not provided" %} ```json { "detail": "Authentication credentials were not provided." } ``` {% endtab %} {% tab title="JSON parse error" %} ```json { "detail":"JSON parse error - Expecting value: line 2 column 13 (char 14)" } ``` {% endtab %} {% endtabs %} ### **Possible Errors** If the merchant account does not have a payout address configured, the server will return a **400** response. If the request does not contain a valid API key in the header or IP address is not in Whitelist, the server will return a **403** response. If the request body contains invalid data, the server will return an error response indicating which field caused the error. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://goodpayments.gitbook.io/docs/api-reference/api-methods-overview-request-response-structure/create-an-invoice.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.