Skip to main content

Create Your First Payment Order

Overview​

A payment order represents a financial collection request that a store or branch initiates on behalf of a payer. It defines the amount (in USD) and the currency the payer will use to settle the transaction (BRL, ARS, or USDT).

Creating a payment order starts the payment flow. Depending on the currency, the response may include a QR code or a payment reference that the payer uses to complete the transaction. The order tracks its own lifecycle from pending through completed, underpaid, cancelled, or under_dispute.

Endpoint​

POST /payment/order

API Reference: Create Payment Order

Authentication​

This endpoint requires a valid Bearer Token in the Authorization header.

Authorization: Bearer <access_token>

Both store or branch users can access to this route.

Supported Currencies​

CurrencyDescription
BRLBrazilian Real
ARSArgentine Peso
USDTTether stablecoin

Order Statuses​

StatusMeaning
pendingInitial order state
completedPayment confirmed order fulfilled
underpaidTransaction found but amount is below the required total
under_disputeOrder has an active claim

Step 1 — Create Order​

Request Examples​

BRL​

curl -X POST "/api/v1/payment/order" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "amount": "200.00",
    "currency": "BRL"
  }'

ARS​

curl -X POST "/api/v1/payment/order" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "amount": "150.00",
    "currency": "ARS",
  }'

USDT​

curl -X POST "/api/v1/payment/order" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "amount": "500.00",
    "currency": "USDT"
  }'

Response Behavior​

A successful request returns 201 Created with the created payment order object.

The response may include a qrData field containing QR code information, depending on the payment currency:

  • BRL include QR code payload.
  • ARS include QR code payload.
  • USDT orders include a blockchain wallet address.

Step 2 — Confirm Order​

After creating an order, its status must be polled until it reaches a final state.

BRL / ARS​

For BRL and ARS orders, the client should periodically check the order status using:

curl -X GET "/api/v1/payment/order/9aa9124b-f7d8-49dc-8df6-53d5348ea383" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>"

This endpoint should be used to verify payment completion state

Polling should continue until a terminal status is reached.

API Reference: Get Order By ID

USDT​

For USDT orders (settled on the Tron network), the confirmation flow is divided into two stages:

1. Webhook polling (payment detection)​

First, you must poll the webhook endpoint every 15 seconds using the order's id until the payment metadata becomes available.

curl -X POST "/api/v1/payment/webhook/{orderId}/tron" \
  -H "Authorization: Bearer <your_access_token>"
  • Continue polling until the response includes providerMetadata.
  • At this stage:
    • The payment status will still be pending
    • But providerMetadata indicates that the payment has been detected and is now being processed

⚠️ Recommended polling interval: 15 seconds

Once providerMetadata is present, you can stop polling this endpoint.

2. Database polling (payment confirmation)​

After the payment enters processing:

  • Stop calling the webhook endpoint
  • Start polling /api/v1/payment/order/{orderId} for the payment status

At this stage, you should:

  • Wait until the status changes from pending → completed
  • No further webhook calls are required

Summary​

  1. Confirm tron payment by order id → wait for providerMetadata
  2. Then poll payment order by id → wait for completed

API References

Important Notes​

  • Payment orders initiate real financial operations. Ensure all fields are accurate before submitting.