Create a Cryptocurrency Payment

Cryptocurrency is a digital payment method that allows customers to complete transactions using their own crypto wallets.

Instructions

Follow the steps below to integrate this payment method.

Select your environment
Select the appropriate environment for your integration. Use the sandbox for testing or production for live transactions. The correct endpoint will be used for the HTTP requests in the examples below.
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
SandboxProduction
https://sandbox.ebanx.com/ws/direct

Define your API parameters

To create a cryptocurrency payment link and QR code, you must provide the required parameters in your request to the ws/direct endpoint. These parameters ensure the successful completion of transactions.

Parameter	Requirement	Description
`integration_key`	Required	EBANX Integration Key, used to authenticate and authorize API requests.
`operation`	Required	Always set to `request`.
`payment.name`	Required	Full name of the customer.
`payment.email`	Required	Customer's email address.
`payment.birth_date`	Required	Customer's date of birth in `yyyy-mm-dd` format.
`payment.document`	Optional	Customer's tax ID or document number (e.g., CPF for Brazil).
`payment.country`	Required	Two-letter code of the customer's country.
`payment.phone_number`	Optional	Customer's phone number.
`payment.payment_type_code`	Required	Specifies the cryptocurrency. Use `usdc` or `usdt`.
`payment.amount_total`	Required	Total amount to be charged.
`payment.currency_code`	Required	Three-letter code of the payment currency.
`payment.merchant_payment_code`	Required	Unique identifier for the transaction created by the merchant.

To learn more, see the

API Reference Guide.

If using checkout with Payment Page, please refer to

this guide.

Sample request

Below is an example of how to initiate a Cryptocurrency payment using the EBANX Direct API. In this example, the payment is made in BRL, using USDC as the cryptocurrency.

curl --location 'https://api.ebanx.com/ws/direct' \
--header 'Content-Type: application/json' \
--data-raw '{
        {
            "integration_key": "{{integration_key_here}}",
            "operation": "request",
            "mode": "full",
            "payment": {
            "name": "John Doe",
                "email": "john.doe@example.com",
                "birth_date": "yyyy-mm-dd",
                "document": "12345678912",
                "country": "br",
                "phone_number": "4555558888",
                "payment_type_code": "usdt",
                "amount_total": 100,
                "currency_code": "BRL",
                "merchant_payment_code": "an_unique_payment_code"
        }
    }

Sample response

A successful request returns a response similar to the example below.

    {
  "payment": {
    "hash": "{{hash_here}}",
    "country": "br",
    "merchant_payment_code": "testdepeaymentmx",
    "order_number": null,
    "status": "PE",
    "status_date": null,
    "open_date": "2025-10-17 16:41:53",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "100.00",
    "amount_ext": "100.00",
    "amount_iof": "0.00",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2025-10-17 16:56:53",
    "instalments": "1",
    "payment_type_code": "usdt",
    "pre_approved": false,
    "capture_available": null,
    "customer": {
      "document": "99999999999",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "birth_date": "1994-09-15"
    },
    "currency_ext_base": "BRL",
    "cryptocurrency": {
      "amount": "18.4612930000",
      "crypto_rate": "5.4167000000",
      "protocols": [
        {
          "qr_code_value": "data:image/png;base64,iVB...YII=",
          "address": "0x750be138124c34a1507671c5a717e74605d87bef",
          "protocol": "BEP20"
        },
        {
          "qr_code_value": "data:image/png;base64,iVB...YII=",
          "address": "0x750be138124c34a1507671c5a717e74605d87bef",
          "protocol": "ERC20"
        },
        {
          "qr_code_value": "data:image/png;base64,iVB...YII=",
          "address": "0x750be138124c34a1507671c5a717e74605d87bef",
          "protocol": "POLYGON"
        },
        {
          "qr_code_value": "data:image/png;base64,iVB...CYII=",
          "address": "TMtqiuZEuBR3A6s895YFnUdWkNeUXpQsNK",
          "protocol": "TRC20"
        }
      ]
    }
  },
  "status": "SUCCESS"
}

At this stage, the payment will appear as pending (PE) in your

EBANX Dashboard.

Display the payment details
When using the Direct API, you will receive a list of QR codes and wallet addresses, one for each supported network. You should display the option that matches the network selected by your customer at checkout.
Important Notes
- The cryptocurrency.protocols field contains all the supported networks for the selected currency.
- For each network, EBANX returns an address (destination wallet address) and a qr_code_value (a Base64-encoded image of the payment QR code).
- The merchant must choose which QR code and address to show the user based on the network selected by the customer in the checkout.
- Always make it clear which cryptocurrency and network are being used. Payments sent through the wrong network may be permanently lost.
Display Guidelines
- Show the payment amount in both local currency and the crypto equivalent.
- Clearly display the selected network (e.g., “USDC on Polygon”).
- Render the QR code using the qr_code_value returned by EBANX.
- Show the wallet address and include a copy button.
- Display the expiration time (default is 15 minutes).
- Include the crypto amount and a copy button.
- Include a network warning, reminding the customer to double-check before confirming the transfer.
Monitor payment for status changes
Notifications
EBANX will send a notification whenever a payment status changes. Ensure your system is set up to receive these notifications for any change in payment status.
Learn more about Payment Notifications.
Status
After receiving a notification, retrieve the payment status. When a payment is confirmed, the status will change from pending (PE) to confirmed (CO).
- Cryptocurrency payments expire based on either the default (15 minutes) or a value set in the expiration_time_in_seconds request parameter.
- If the customer does not complete the payment in time, the status will automatically update to cancelled (CA).
  Learn more about Retrieving Payment Status.
Congratulations!
You have successfully integrated a payment with Stablecoins.
For more information, refer to the
Direct API reference guide.

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explore

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explore

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explore

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.

Instructions​

Select your environment

Define your API parameters

Sample request

Sample response

Display the payment details

Display Guidelines​

Monitor payment for status changes

Notifications​

Status​

Congratulations!

Resources​

API Reference

Mock Customer Data

Error Codes

Still need help?

Instructions

Display Guidelines

Notifications

Status

Resources