> For the complete documentation index, see [llms.txt](https://docs.bitnbox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitnbox.com/bitnbox-pay-api-reference/create-payment.md).

# Create payment

{% hint style="warning" %}
To test the API, make sure to include `x-api-key` in the header with your API key.
{% endhint %}

## Create payment

> Creates a payment link. You need to provide the amount and the currency of the payment in the request.

```json
{"openapi":"3.0.2","info":{"title":"Bitnbox API","version":"0.1.0"},"servers":[{"url":"https://api.bitnbox.com"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}}},"paths":{"/v1/payment":{"post":{"description":"Creates a payment link. You need to provide the amount and the currency of the payment in the request.","summary":"Create payment","tags":["v1"],"parameters":[],"operationId":"apiCreatePayment","requestBody":{"description":"Body","content":{"application/json":{"schema":{"description":"Payment creation request body","type":"object","properties":{"method":{"default":"crypto","type":"string","enum":["crypto","direct","binancepay"],"description":"A method to receive a payment."},"amount":{"type":"number","minimum":0,"description":"The amount you want to receive from your customer."},"processingFeeByUser":{"type":"boolean","description":"If true, the initial amount will be increased to cover the platform fee."},"platformFeeByUser":{"type":"boolean","description":"Deprecated!, use processingFeeByUser"},"currency":{"type":"string","minLength":1,"description":"Specifies the cryptocurrency for the payment via tickers (refer to API glossary)."},"network":{"type":"string","enum":["eth","polygon","bsc","binancepay","tron","sepolia","amoy","bsctestnet","nile","kucoinpay","btc"],"description":"Specifies the blockchain network for the payment via tickers (refer to API glossary)."},"customerId":{"type":"string","description":"Customer's ID for security purposes."},"customerIp":{"type":"string","minLength":1,"description":"The customer's IP address, recorded for compliance purposes."},"orderId":{"type":"string","minLength":1},"orderDescription":{"type":"string","description":"Order description"},"additionalData":{"type":"string","description":"Additional information related to the payment, if needed."},"webhookUrl":{"oneOf":[{"type":"string","format":"uri"},{"type":"string","enum":[""]}],"description":"An optional URL where transaction status updates and payment notifications will be sent."},"successUrl":{"type":"string","format":"uri","pattern":"^https?:\\/\\/","maxLength":256,"description":"The URL to redirect to when the payment is successful."},"cancelUrl":{"type":"string","format":"uri","pattern":"^https?:\\/\\/","maxLength":256,"description":"The URL to redirect to when the payment is failed."}},"required":["amount","currency","network","customerIp","orderId","orderDescription","customerId"]}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","description":"Optional identifier for the order linked to the payment."},"status":{"type":"string","enum":["waiting","confirming","failed","locked","expired","paid","paid_over","paid_partial","settling","on_hold"],"description":"Current status of the payment."},"method":{"default":"crypto","type":"string","enum":["crypto","direct","binancepay"],"description":"Payment method, default `crypto`"},"currency":{"type":"string","minLength":1,"description":"Cryptocurrency associated with the payment (e.g., usdt, usdc)."},"network":{"type":"string","description":"Blockchain network associated with the payment."},"payAmount":{"type":"number","description":"Amount to be paid."},"paymentId":{"type":"string","format":"uuid","description":"Unique payment identifier."},"checkoutUrl":{"type":"string","description":"Link to the Binance-hosted checkout page."},"appRedirectUrl":{"type":"string","description":"CEX redirect url"},"payAddress":{"type":"string","description":"The address to send the payment to."},"payQrCodeUri":{"type":"string","description":"URI for generating the payment QR code."},"customerId":{"type":"string","minLength":1,"description":"Customer's ID for security purposes."},"customerIp":{"type":"string","minLength":1,"description":"The customer's IP address, recorded for compliance purposes."},"processingFeeByUser":{"type":"boolean","description":"Indicates whether the platform fee should be covered by the user or the merchant."},"products":{"type":"array","items":{"nullable":true}},"additionalData":{"type":"string","description":"Extra information related to the payment."},"webhookUrl":{"type":"string","format":"uri","description":"URL where transaction updates and payment notifications will be sent."},"createdAt":{"type":"string","format":"date-time","description":"Date and time when the payment was created."},"updatedAt":{"type":"string","format":"date-time","description":"Date and time of the last update to the payment information."},"expiredAt":{"type":"string","format":"date-time","description":"Date and time when the payment expires. Currently set to 15 minutes from the creation time."},"condition":{"type":"string","description":"Reason why payment is in ON_HOLD status"}},"required":["orderId","status","currency","network","payAmount","paymentId","checkoutUrl","payQrCodeUri","customerId","customerIp","processingFeeByUser","products","webhookUrl","createdAt","updatedAt","expiredAt"],"description":"Payment link creation successful"}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"}},"required":["code","message"],"description":"Server error response"}}}}}}}}}
```

{% hint style="info" %}
**appRedirectUrl** - а link for the user to proceed to payment on the exchange side.

For web integration, it is recommended to open appRedirectUrl in a new browser tab (target=“\_blank”) to ensure a correct user experience and avoid redirect blocking.
{% endhint %}