Skip to main content
PUT
Approve payment order
Approves an outbound payment order awaiting approval. Transitions status from AWAITING_APPROVAL to PENDING and submits the order to the provider network.
Approval is a one-way commit. Once approved, the order moves to PENDING and cannot be canceled — it will reach a final state (SUCCESS or FAILED) on the provider’s timeline. Verify amounts, recipients, and business rules before calling this endpoint.

Preconditions

Verify state via Get payment order before approving if you cannot guarantee single-writer semantics in your caller.

Effect

  • statusPENDING
  • locked on the wallet increases by amount
  • The order is submitted to the provider; settlement is asynchronous
For the alternative to approval, see Cancel payment order.

Authorizations

X-Access-Key
string
header
required

Opaque credential identifier provisioned during onboarding. See the Integration Guide for the request-signing protocol.

X-Access-Timestamp
string
header
required

Unix epoch timestamp in UTC milliseconds. See the Integration Guide for skew tolerance.

X-Access-Request-Id
string
header
required

Unique identifier per request (UUID v4 recommended). The (accessKey, requestId) tuple must be unique within the replay window defined by the Integration Guide.

X-Access-Signature
string
header
required

Base64-encoded ECDSA signature of the canonical request, computed with the private key paired to X-Access-Key. See the Integration Guide for canonicalization rules and reference implementations.

Path Parameters

wallet
string
required

Wallet name (RFC 1035 DNS label).

Required string length: 1 - 63
Pattern: ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$
paymentOrder
string
required

Payment order identifier.

Pattern: ^ord_[A-Za-z0-9]+$

Response

The approved payment order.

An inbound (cash-in) or outbound (cash-out) payment request routed through a provider network on behalf of a wallet.

id
string
required
read-only
Pattern: ^ord_[A-Za-z0-9]+$
Example:

"ord_3KpFvBwYzNqMxA7eHbRdJ"

kind
enum<string>
required
read-only
Available options:
Payment.Order
wallet
string
required
read-only

The wallet that owns this order (DNS label name).

Example:

"production-main"

ordVersion
integer
required
read-only

Snapshot version, incremented on every content mutation.

Required range: x >= 1
direction
enum<string>
required

Direction of value flow.

Available options:
IN,
OUT
status
enum<string>
required

Lifecycle status of a payment order.

Available options:
AWAITING_APPROVAL,
PENDING,
PROCESSING,
SUCCESS,
FAILED,
CANCELED,
EXPIRED,
REFUNDED
network
enum<string>
required

Payment network identifier.

Available options:
br.gov.bcb.pix,
tron.mainnet,
solana.mainnet,
bitcoin.mainnet,
ethereum.mainnet
idempotencyKey
string
required

Client-supplied opaque key. The (wallet, idempotencyKey) tuple is globally unique; identical retries return the existing order, divergent retries return IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS.

Required string length: 1 - 64
Example:

"invoice-2026-0184"

amount
integer<int64>
required

Amount in minor units of the order currency.

Required range: x >= 1
Example:

25000

currency
enum<string>
required

Currency or asset code.

Available options:
BRL,
USD,
TRX,
SOL,
BTC,
ETH,
USDT
instrument
object
required

Inbound PIX instrument backed by a long-lived, reusable static EMV QR code.

createdAt
string<date-time>
required
read-only

Server-assigned creation timestamp (UTC ISO 8601).

updatedAt
string<date-time>
required
read-only

Timestamp of the last content mutation (UTC ISO 8601).

selfName
string
required
read-only

Canonical relative resource name.

Example:

"wallets/production-main/paymentOrders/ord_3KpFvBwYzNqMxA7eHbRdJ"

etag
string
required
read-only

Hex-encoded content fingerprint of the resource. Reserved for optimistic concurrency control via the If-Match request header in a future release; currently exposed for informational and audit purposes only.

Pattern: ^[a-f0-9]{64,128}$
metadata
object

Client-supplied tags. Not included in the etag computation.

Example:
errorCode
string | null
read-only

Provider-reported error code when status is FAILED.

errorMessage
string | null
read-only

Human-readable error description when status is FAILED.

processedAt
string<date-time> | null
read-only

Server processing timestamp. null until the order is submitted to (or rejected by) the underlying provider; set once the provider returns a definitive outcome.