Create PIX Out

Create a PIX payout order.

Endpoint

POST /cashout/pix/create

Authentication

Merchant Credential. See Authentication.

Background

This API initiates a Brazilian Pix payout transaction. The merchant submits its own cashout order, amount, and payee information; currency supports BRL, and the payee is ultimately paid in the local currency.

A synchronous return of status = 200 only means the payout request has been accepted by Adopay, not that the funds have reached the payee's account. The final result is determined by the asynchronous notification or the Query cashout by Order SN result.

The merchant must ensure that cashout order numbers are unique under the same merchant, for order de-duplication and subsequent queries. The merchant order number serves as the idempotency key, with an idempotency validity period of 3 months: within this period, resubmitting the same order number will not create a duplicate cashout order. Idempotency for cashin and cashout does not exclude each other; an order number submitted for cashout may be reused in cashin.

Cashout Transaction Flow

• Synchronous acceptance phase: The merchant submits the payout request; Adopay performs integration checks, business validation, idempotency control, and order persistence, then returns the acceptance result.
• Asynchronous disbursement phase: Adopay initiates the Pix payout instruction to the central bank BCB in the background; the funds are credited through the receiving bank, and Adopay notifies the merchant of the final result.

sequenceDiagram
    autonumber
    actor U as User (payee)
    participant M as Merchant
    participant A as Adopay
    participant BCB as Central Bank BCB
    participant RB as Receiving Bank
    U->>M: Trigger the payout business scenario
    M->>A: POST /cashout/pix/create
    A->>A: Verify signature, validate business rules and idempotency, create cashout order and disbursement task
    A-->>M: Return platOrderNo, orderStatus = PENDING
    M-->>U: Show that the request is accepted or in progress
    A->>BCB: Submit the Pix payout instruction
    BCB->>RB: Initiate the Pix transfer
    RB-->>U: Credit the receiving account
    RB-->>BCB: Return the credit result
    BCB-->>A: Notify the payout success or failure result
    A->>A: Verify the result and idempotently update the order to its final state
    A-->>M: POST the payout result to notifyUrl
    alt Merchant confirms successfully
        M-->>A: Return success confirmation
        M-->>U: Update the business order and display the payout result
    else Merchant does not confirm successfully
        A-->>M: Retry according to the notification task policy
    end

Request Fields

Field	Location	Type	Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Merchant ID, read from the request header.
X-Timestamp	Header	int	19	Yes	Unix request timestamp in seconds.
X-Nonce	Header	string	64	Yes	Random string for request anti-replay protection.
Digest	Header	string	52	Yes	Digest of the request body. Format: SHA-256=<Base64Digest>.
Authorization	Header	string	Variable	Yes	ES256 request signature, where keyId is the merchant key version.
merchantOrderNo	Body	string	64	Yes	Merchant order number; unique among the same merchant's cashout orders, used for order de-duplication and subsequent queries. Cashin and cashout idempotency are not mutually exclusive; cashin may reuse the same order number.
amount	Body	decimal	25,2	Yes	Payment amount in BRL; must be greater than zero, with at most two decimal places.
payeeTaxNo	Body	string	64	Yes	Payee tax ID; CPF is 11 digits, CNPJ is 14 digits.
payeePixKey	Body	string	64	Yes	Payee Pix Key.
notifyUrl	Body	string	255	No	URL where the merchant receives cashout result notifications; the submitted value takes precedence, otherwise the merchant-configured URL is used.
attach	Body	string	128	No	Opaque data passed through by the merchant; returned as-is in callback notifications or retrieval queries, invisible to the paying user.
reference	Body	string	128	No	Description visible in the user's bank statement details, up to 128 characters.
displayName	Body	string	128	No	Name to be displayed on the payment proof.

Request Header Example

Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786838400
X-Nonce: 8f6e17d07f8b4fe19318d9c4dd6fc001
Digest: SHA-256=<REQUEST_BODY_SHA256_BASE64>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

Here, Digest must be computed over the raw request body actually sent, and the signature value in Authorization must be generated dynamically from the actual request path, timestamp, nonce, and digest.

Request Body Example

{
  "merchantOrderNo": "CASHOUT202608160001",
  "amount": 100.25,
  "payeePixKey": "maria.oliveira@example.com",
  "notifyUrl": "https://merchant.example.com/callback/cashout",
  "attach": "merchant-data-001",
  "reference": "Supplier payment",
  "displayName": "Maria Oliveira",
  "payeeTaxNo": "12345678901"
}

Response Fields

The API uses a unified status, msg, data response structure. A status of 200 means the request was accepted, but does not mean the cashout transaction ultimately succeeded; the final result should be determined by orderStatus, the asynchronous notification, or the order query result.

Field	Type	Length	Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Corresponds to status
data	object	N/A	No	cashout acceptance result; may be absent when the request fails before entering business processing.
data.merchantOrderNo	string	64	Yes	Merchant order number.
data.platOrderNo	string	64	Yes	Platform cashout order number, used for platform-side order tracking and queries.
data.amount	decimal	25,2	Yes	cashout amount submitted by the merchant.
data.receivedAmount	decimal	25,2	Yes	Amount actually credited to the payee; may be 0 before the transaction completes.
data.orderStatus	string	16	Yes	Current status of the cashout order; successful API acceptance does not mean this field holds a success status.

orderStatus Enum

Enum Value	Description	Final State
PENDING	Processing; the cashout request has been accepted and the fund processing is not yet complete.	No
SUCCESS	cashout succeeded; the payee has been credited.	Yes
FAILED	cashout failed; this cashout has ended and the funds will not be credited.	Yes

Response Example

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "merchantOrderNo": "CASHOUT202608160001",
    "platOrderNo": "APS202608160000000001",
    "amount": 100.25,
    "receivedAmount": 0,
    "orderStatus": "PENDING"
  }
}