> ## Documentation Index > Fetch the complete documentation index at: https://docs.ca.cryptoprocessing.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an invoice > [!TIP] > > Documentation for invoices: [Overview](https://docs.ca.cryptoprocessing.com/invoices), [Fees](https://docs.ca.cryptoprocessing.com/invoices/fees), [Create invoice](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/invoices-create), [Cancel invoice](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/invoices-cancel), [Callbacks](https://docs.ca.cryptoprocessing.com/api-reference/callbacks/invoice-payment-callbacks). > > For new integrations, **consider [migrating to payment requests](https://docs.ca.cryptoprocessing.com/payment-requests/migration-guide.md) instead**. > [!NOTE] > > CryptoProcessing is required to collect sender data in compliance with local regulations. For more details, see [User data collection](https://docs.ca.cryptoprocessing.com/user-data-collection.md). The `sender_data` and the `end_user_reference` you provide must be associated with the same customer. > [accordion] Errors > > **400 Bad Request** > > | Error message | What it means | > | - | - | > | `foreign_id: The foreign id has already been taken.` | The `foreign_id` was already used by one of your invoices. The check is case-insensitive. Use a new `foreign_id`. | > | `currency: The selected currency is invalid.` | The `currency` code doesn't exist. See [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md). | > | `sender_currency: Currency is invalid or unavailable` | | > | `timer: The timer has to be set up in case sender currency is defined` | `sender_currency` was sent with `timer` set to `false`. An invoice with a pre-selected payment currency needs `timer: true`. | > | `timer: The timer field must be true or false.` | `timer` isn't a boolean, for example the string `"true"`. | > | `amount: The amount must be a number.` | `amount` isn't a number or a numeric string. | > | `amount: The amount is too small. The minimum amount is .` | | > | `amount: The amount is too large. The one-time operation limit is .` | The amount is above the maximum invoice amount. ` ` is the maximum, which can be stated in another currency than the invoice's. | > | `amount: The number of decimal places needs to be less than 8` | `amount` has more than 8 decimal places. | > | `url_success: The url success format is invalid.` | `url_success` isn't a valid URL. | > | `url_failed: The url failed format is invalid.` | `url_failed` isn't a valid URL. | > | `title: The title may not be greater than 50 characters.` | `title` is longer than 50 characters. | > | `description: The description may not be greater than 1000 characters.` | `description` is longer than 1000 characters. | > | `foreign_id: The foreign id may not be greater than 255 characters.` | `foreign_id` is longer than 255 characters. | > | `end_user_reference: The end user reference may not be greater than 255 characters.` | `end_user_reference` is longer than 255 characters. | > | `title: The title must be a string.` | `title` was sent as another JSON type, such as a number. | > | `description: The description must be a string.` | `description` was sent as another JSON type, such as a number, or as an empty string. Leave it out instead of sending an empty string. | > | `currency: The currency must be a string.` | `currency` was sent as another JSON type, such as a number. | > | `sender_currency: The sender currency must be a string.` | `sender_currency` was sent as another JSON type, such as a number. | > | `foreign_id: The foreign id must be a string.` | `foreign_id` was sent as another JSON type, such as a number. Send it as a string. | > | `end_user_reference: The end user reference must be a string.` | `end_user_reference` was sent as another JSON type, such as a number. | > | `end_user_reference: The end user reference must not contain email.` | `end_user_reference` contains an email address. Use an ID from your system that contains no personal data. | > | `email_user: The email user must be a valid email address.` | `email_user` isn't a valid email address. | > | `timer: The timer field is required.` | `timer` is missing, `null` or an empty string. | > | `title: The title field is required.` | `title` is missing, `null`, an empty string, or only spaces. | > | `foreign_id: The foreign id field is required.` | `foreign_id` is missing, `null` or an empty string. | > | `currency: The currency field is required.` | `currency` is missing, `null` or an empty string. | > | `amount: The amount field is required.` | `amount` is missing, `null` or an empty string. | > | `url_success: The url success field is required.` | `url_success` is missing, `null` or an empty string. | > | `url_failed: The url failed field is required.` | `url_failed` is missing, `null` or an empty string. | > | `email_user: The email user field is required.` | `email_user` is missing, `null` or an empty string. | > | `type: The selected type is invalid.` | `type` isn't `fill_or_kill` or `good_until_expired`. | > | `Required features [invoices_enabled] not enabled.` | Invoices aren't enabled for your merchant account. | > > **422 Unprocessable Entity** > > | Error message | What it means | > | - | - | > | `Something went wrong. Please try later.` (code `internal_error`) | `amount` was sent as a string in scientific notation, such as `"1e1"`. Send it in plain decimal notation, such as `"10"`. For other causes of this error, see [Internal error](https://docs.ca.cryptoprocessing.com/api-reference/errors.md#internal-error-422-unprocessable-entity). | ## OpenAPI ````yaml POST /v2/invoices/create openapi: 3.1.0 info: title: Merchant Backend V2 version: '1.0' description: Documentation for merchant backend processing endpoints servers: - url: https://app.ca.cryptoprocessing.com/api security: - xProcessingKey: [] tags: - name: Status - name: Balance - name: Currencies - name: Deposit addresses - name: Withdrawal - name: Exchange - name: Invoices - name: Transactions paths: /v2/invoices/create: post: tags: - Invoices summary: Create an invoice operationId: post-invoices-create parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' requestBody: content: application/json: schema: type: object properties: type: type: string description: > For partial pay invoices, set this parameter to `good_until_expired`. For standard invoices, use `fill_or_kill` or leave this empty. See [Partial pay invoices](/invoices#partial-pay-invoices). enum: - fill_or_kill - good_until_expired end_user_reference: $ref: '#/components/schemas/end_user_reference.deposits' timer: type: boolean description: >- If this parameter is set to true, the invoice will expire in 15 minutes after it is created. title: type: string maxLength: 50 description: Invoice title that the customer will see. minLength: 1 description: type: string description: Invoice description that the customer will see. maxLength: 1000 foreign_id: type: string maxLength: 255 description: >- Unique ID of the invoice in your system, case-insensitive. Avoid `/` and `#`: the [cancel endpoint](/api-reference/endpoints/invoices-cancel) takes the `foreign_id` in its path and can't find an invoice whose `foreign_id` contains them. currency: type: string description: >- Currency you want to receive deposits in. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). sender_currency: type: string description: >- Currency the customer will pay in. Requires `timer: true` (otherwise the request fails with `The timer has to be set up in case sender currency is defined`). The invoice is then created with a fixed payment currency, rate and address, and the response includes `address`, `sender_amount` and `fixed_at`. Must be a cryptocurrency different from `currency`. amount: oneOf: - type: number - type: string description: "The invoice amount you want to receive from the customer, in `currency`, as a number or a decimal string, with at most\_8\_decimal places. It must be within the minimum and maximum invoice amounts." url_success: type: string format: uri description: >- The URL the customer will be redirected to in case of a successful invoice payment. url_failed: type: string description: >- The URL the customer will be redirected to in case of an unsuccessful invoice payment. format: uri email_user: type: string description: >- The customer's email address. It's filled in for the customer on the invoice page. The customer gets an email when the invoice is paid, and when a payment doesn't match the invoice (more or less than the invoice amount, a payment after the invoice has expired or failed, or a payment to an invoice you cancelled): either a link to claim a refund, or a notice that the amount is too small to be refunded. format: email sender_type: $ref: '#/components/schemas/sender_type.deposits' sender_data: $ref: '#/components/schemas/sender_data' required: - timer - title - foreign_id - end_user_reference - currency - sender_type - sender_data - amount - url_success - url_failed - email_user examples: Customer chooses the currency, no time limit: value: timer: false title: Invoice Title currency: USD amount: 100 foreign_id: invoice_123 end_user_reference: user_12345 url_success: https://example.com/success url_failed: https://example.com/failed email_user: chris.customer@example.com sender_type: natural sender_data: first_name: Chris last_name: Customer date_of_birth: '1970-01-01' "Customer chooses the currency within\_15\_minutes": value: timer: true title: Invoice Title currency: USD amount: 100 foreign_id: invoice_123 end_user_reference: user_12345 url_success: https://example.com/success url_failed: https://example.com/failed email_user: chris.customer@example.com sender_type: natural sender_data: first_name: Chris last_name: Customer date_of_birth: '1970-01-01' "Customer pays in BTC within\_15\_minutes": value: timer: true title: Invoice Title currency: USD sender_currency: BTC amount: 100 foreign_id: invoice_123 end_user_reference: user_12345 url_success: https://example.com/success url_failed: https://example.com/failed email_user: chris.customer@example.com sender_type: natural sender_data: first_name: Chris last_name: Customer date_of_birth: '1970-01-01' "Accept partial payments in USDC within\_15\_minutes": value: type: good_until_expired timer: true title: Invoice Title currency: USD sender_currency: USDC amount: 100 foreign_id: invoice_123 end_user_reference: user_12345 url_success: https://example.com/success url_failed: https://example.com/failed email_user: chris.customer@example.com sender_type: natural sender_data: first_name: Chris last_name: Customer date_of_birth: '1970-01-01' responses: '201': description: Created content: application/json: schema: type: object properties: data: type: object required: - id - url - foreign_id - end_user_reference - address - title - status - currency - amount - sender_currency - sender_amount - fixed_at - release_at - seconds_left properties: id: type: integer description: Invoice ID. example: 123732 url: type: string format: uri description: Invoice URL. foreign_id: type: string description: This invoice's unique ID in your system. end_user_reference: type: string description: >- The unique ID of the customer this invoice is for. You can use it to group invoices by customer. address: type: - string - 'null' description: >- The address the customer pays to. Assigned right away for invoices created with `sender_currency`; otherwise `null` until the customer chooses a payment currency on the invoice page. example: 2N2xtaZCNygY3iq6XKPJsdoPMDX85LUc8SM tag: type: - string - 'null' description: >- Destination tag/memo. Present only for currencies that support tags (e.g., XRP). title: type: string minLength: 1 description: Invoice title. status: type: string description: >- `pending` for invoices with a timer, `created` for invoices without one. enum: - created - pending currency: type: string description: Invoice currency. amount: type: string description: Invoice amount. example: '0.01230000' sender_currency: type: - string - 'null' description: >- The currency the customer will pay in. `null` for invoices without a pre-selected currency. sender_amount: type: - string - 'null' example: '0.01230000' description: >- The amount the customer needs to pay in `sender_currency`. `null` for invoices without a pre-selected currency. fixed_at: type: - integer - 'null' description: >- Unix time in seconds when the payment rate was fixed. For invoices with a pre-selected currency, this is the creation time. Otherwise it's `null`, and the rate is fixed later, when the customer chooses a payment currency on the invoice page. release_at: type: - integer - 'null' description: >- Unix time in seconds when the invoice will expire. `null` for invoices without a timer. seconds_left: type: - integer - 'null' description: >- The number of seconds left until the invoice expires. `null` for invoices without a timer. example: 899 examples: Customer chooses the currency, no time limit: value: data: id: 826900 url: https://invoices.ca.cryptoprocessing.com/invoice/Jyf1cQ foreign_id: invoice_123 end_user_reference: user_12345 address: null title: Invoice Title status: created currency: USD amount: '100.00000000' sender_currency: null sender_amount: null fixed_at: null release_at: null seconds_left: null "Customer chooses the currency within\_15\_minutes": value: data: id: 826904 url: https://invoices.ca.cryptoprocessing.com/invoice/o6t4I8 foreign_id: invoice_123 end_user_reference: user_12345 address: null title: Invoice Title status: pending currency: USD amount: '100.00000000' sender_currency: null sender_amount: null fixed_at: null release_at: 1775178385 seconds_left: 899 "Customer pays in BTC within\_15\_minutes": value: data: id: 826906 url: https://invoices.ca.cryptoprocessing.com/invoice/ZKeDtw foreign_id: invoice_123 end_user_reference: user_12345 address: bc1qr9m5urrm2wuypa9zqzufpm0hhzmj5zgh0lstyk title: Invoice Title status: pending currency: USD amount: '100.00000000' sender_currency: BTC sender_amount: '0.00124338' fixed_at: 1775177497 release_at: 1775178397 seconds_left: 899 "Accept partial payments in USDC within\_15\_minutes": value: data: id: 826908 url: https://invoices.ca.cryptoprocessing.com/invoice/Q7mXv2 foreign_id: invoice_123 end_user_reference: user_12345 address: '0x5a1C3E9b7d2F4c6A8e0B1d3F5A7C9E2B4d6F8a0c' title: Invoice Title status: pending currency: USD amount: '100.00000000' sender_currency: USDC sender_amount: '100.25000000' fixed_at: 1775177510 release_at: 1775178410 seconds_left: 899 '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Foreign ID already used: value: errors: foreign_id: The foreign id has already been taken. Currency doesn't exist: value: errors: currency: The selected currency is invalid. Payment currency doesn't exist: value: errors: sender_currency: Currency is invalid or unavailable Payment currency the same as the invoice currency: value: errors: sender_currency: Currency is invalid or unavailable Payment currency is a fiat currency: value: errors: sender_currency: Currency is invalid or unavailable Payment currency without a timer: value: errors: timer: >- The timer has to be set up in case sender currency is defined Timer not true or false: value: errors: timer: The timer field must be true or false. Amount not a number: value: errors: amount: The amount must be a number. Amount below the minimum: value: errors: amount: >- The amount is too small. The minimum amount is . Amount below the minimum in the payment currency: value: errors: amount: >- The amount is too small. The minimum amount is . Amount above the maximum: value: errors: amount: >- The amount is too large. The one-time operation limit is . "Amount with more than\_8\_decimals": value: errors: amount: The number of decimal places needs to be less than 8 Success URL not valid: value: errors: url_success: The url success format is invalid. Failure URL not valid: value: errors: url_failed: The url failed format is invalid. "Title longer than\_50\_characters": value: errors: title: The title may not be greater than 50 characters. "Description longer than\_1000\_characters": value: errors: description: The description may not be greater than 1000 characters. "Foreign ID longer than\_255\_characters": value: errors: foreign_id: The foreign id may not be greater than 255 characters. "End-user reference longer than\_255\_characters": value: errors: end_user_reference: >- The end user reference may not be greater than 255 characters. Title not a string: value: errors: title: The title must be a string. Description not a string: value: errors: description: The description must be a string. Currency not a string: value: errors: currency: The currency must be a string. Payment currency not a string: value: errors: sender_currency: The sender currency must be a string. Foreign ID not a string: value: errors: foreign_id: The foreign id must be a string. End-user reference not a string: value: errors: end_user_reference: The end user reference must be a string. Email in the end-user reference: value: errors: end_user_reference: The end user reference must not contain email. Email address not valid: value: errors: email_user: The email user must be a valid email address. Missing required fields: value: errors: timer: The timer field is required. title: The title field is required. foreign_id: The foreign id field is required. currency: The currency field is required. amount: The amount field is required. url_success: The url success field is required. url_failed: The url failed field is required. email_user: The email user field is required. Invoice type not valid: value: errors: type: The selected type is invalid. Invoices not enabled: value: message: Required features [invoices_enabled] not enabled. Malformed JSON: value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/HeaderAuthorization' '422': description: > Unprocessable entity. An internal error occurred during processing. The request was understood but could not be completed. The `errors` field is an array of error messages. The `error_code` is always the string `"internal_error"`. For other causes of this error, see [Internal error](/api-reference/errors#internal-error-422-unprocessable-entity). content: application/json: schema: type: object required: - errors - error_code properties: errors: type: array description: Array of error messages items: type: string error_code: type: string description: Error code identifier examples: Amount as a string in scientific notation: value: errors: - Something went wrong. Please try later. error_code: internal_error '429': $ref: '#/components/responses/TooManyRequests' components: parameters: XProcessingSignatureHeader: name: X-Processing-Signature in: header required: true description: >- Hex-encoded HMAC-SHA512 signature of the request body, [generated using your secret key](/api-reference/authentication). schema: type: string schemas: end_user_reference.deposits: type: string description: > Permanent ID of the customer in your system. Used to group, track, and analyze transactions made by a specific customer. Must not contain personal data, such as the user's name or email address. sender_type.deposits: type: string enum: - natural - legal description: > Type of the merchant's customer who sends the funds. Use `natural` if the sender is an individual person and `legal` if the sender is a legal entity. The selected type determines which fields must be included in `sender_data`. sender_data: description: > Must contain the details of the merchant's customer who sends the funds. Which fields are required depends on `sender_type`. oneOf: - title: Natural person type: object required: - first_name - last_name properties: first_name: type: string maxLength: 255 description: The sender's first name. last_name: type: string maxLength: 255 description: The sender's last name. date_of_birth: type: string description: >- The sender's date of birth, YYYY-MM-DD. Optional for a natural person. - title: Legal entity type: object required: - legal_name - country_of_registration properties: legal_name: type: string maxLength: 255 description: The company's name. country_of_registration: type: string description: >- The company's country of registration (ISO alpha-3 format, three characters). ValidationOrMalformedJson: oneOf: - type: object title: ValidationError description: One or more request parameters failed validation. properties: errors: type: object description: > A map of request field names to a human-readable validation error message for that field. The exact set of possible keys and messages is endpoint-specific — see [API errors](/api-reference/errors#errors-by-endpoint) for the full reference. additionalProperties: type: string description: Human-readable validation error message for this field. - type: object title: MalformedJson description: >- The request body is not valid JSON or the Content-Type header is not set to `application/json`. properties: error: type: string code: type: string responses: HeaderAuthorization: description: | Forbidden content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. code: type: string description: Error code. description: >- Invalid or missing headers, or the API key does not have access to the endpoint. Refer to [Errors](/api-reference/errors#general-errors) for troubleshooting steps. examples: Bad signature header: value: error: Bad signature header code: bad_header_signature API key does not have the required ability: value: error: The API key does not have access to this endpoint. code: api_key_ability_required No signature header: value: error: No signature header code: required_header_signature No key header: value: error: No key header code: required_header_key TooManyRequests: description: > Too Many Requests You sent too many requests in a short time. The limit is counted per API key, so requests from all your servers that use the same key count together. Wait before you send the request again, increasing the delay if you get `429` again, and handle this error by its status code, not by a particular response body. See [Too many requests](/api-reference/errors#too-many-requests-429-too-many-requests). securitySchemes: xProcessingKey: type: apiKey description: Your [API key](/merchant-administration/generate-and-activate-api-keys). in: header name: X-Processing-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.