/cashout/pix/create-partner Create PIX Out

Background

/cashout/pix/create-partner is the payout creation API provided to partners, currently used to initiate Brazilian PIX payouts. currency supports BRL; the payee is ultimately paid in the local currency.

Payout Transaction Flow

A payout transaction consists of two connected phases:

• Synchronous acceptance phase: the partner submits the payout request to Adopay; after Adopay completes integration validation, business validation, idempotency control, and order persistence, it returns the acceptance result to the partner.
• Asynchronous disbursement phase: Adopay issues a PIX payout instruction to the Central Bank (BCB) in the background, and the Central Bank (BCB) instructs the receiving bank to credit the user's account.

A synchronous status = 200 only means the payout request was accepted by Adopay, not that the funds have reached the user's account. The final payout result is determined by the asynchronous notification or the order query result.

Transaction Flow Among the User, Partner, Adopay, Paying Bank, and Central Bank (BCB)

sequenceDiagram
    autonumber
    actor U as User (payee)
    participant M as Partner
    participant A as Adopay
    participant PB as Central Bank (BCB)
    participant BCB as Receiving Bank

    Note over U,A: Payout request and Adopay acceptance (synchronous)
    opt Payout triggered by user activity
        U->>M: Triggers a collection scenario such as withdrawal, refund, or settlement
    end
    M->>M: Creates the merchant payout order
    M->>A: POST /cashout/pix/create-partner
    A->>A: Signature verification, digest check, timestamp and anti-replay checks
    A->>A: Parameter, partner permission, account, and risk-control validation
    A->>A: Idempotency check and Adopay payout order creation
    A->>A: Creates the background disbursement task
    A-->>M: Returns platOrderNo, orderStatus = PENDING
    M-->>U: Shows the payout request accepted or in progress

    Note over A,BCB: PIX payout execution (asynchronous)
    A->>PB: Submits the PIX payout instruction
    PB->>BCB: Initiates the PIX transfer
    BCB-->>U: Credits the funds to the user's account via the receiving bank

    Note over M,BCB: Final result return and partner notification (asynchronous)
    BCB-->>PB: Returns the credit result
    PB-->>A: Notifies the payout success or failure result
    A->>A: Verifies the result and idempotently updates the payout order to its final state
    A-->>M: POSTs the payout result to notifyUrl
    alt Partner acknowledges successfully
        M-->>A: Returns a success acknowledgment
        M-->>U: Updates the business order and shows the payout result
    else Partner does not acknowledge successfully
        A-->>M: Retries per the notification task policy
    end

Endpoint

Item	Value
Method	POST
Path	/cashout/pix/create-partner
Content-Type	application/json
Purpose	Create a PIX payout order

Access Requirements

• Common specifications

Request Fields

Field	Location	Type	Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Primary merchant ID, read from the request header.
X-Timestamp	Header	int	19	Yes	Unix request timestamp in seconds.
X-Nonce	Header	string	64	Yes	Anti-replay random string for the request.
Digest	Header	string	52	Yes	Request body digest in the format SHA-256=<Base64 digest>.
Authorization	Header	string	Variable	Yes	ES256 request signature information, where keyId is the partner key version.
merchantOrderNo	Body	string	64	Yes	Merchant order number; unique among payout orders under the same merchant, used for duplicate prevention and later queries. Cashin and cashout idempotency are independent: 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's tax ID; CPF has 11 digits and CNPJ has 14 digits.
payeePixKey	Body	string	64	Yes	Payee's Pix key.
subMerchantNo	Body	string	64	Yes	Sub-merchant ID.
notifyUrl	Body	string	255	No	URL where the partner receives the payout result notification; the submitted value takes priority, otherwise the partner's configured URL is used.
attach	Body	string	128	No	Data passed through by the partner; 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 transaction statement, up to 128 characters.
displayName	Body	string	128	No	Name to display on the payment proof.

Request Header Example

POST /cashout/pix/create-partner HTTP/1.1
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,
  "payeeTaxNo": "12345678901",
  "payeePixKey": "maria.oliveira@example.com",
  "subMerchantNo": "SUBMERCHANT0001",
  "notifyUrl": "https://merchant.example.com/callback/cashout",
  "attach": "merchant-data-001",
  "reference": "Supplier payment",
  "displayName": "Maria Oliveira"
}

Response Fields

The API uses the standard status, msg, and data response structure. status = 200 means the request was accepted, but it does not mean the payout transaction finally succeeded; the final result is 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	Message corresponding to status
data	object	N/A	No	Payout acceptance result; may be omitted when the request fails before entering business processing.
data.subMerchantNo	string	64	Yes	Sub-merchant ID, identical to the subMerchantNo in the request.
data.merchantOrderNo	string	64	Yes	Merchant order number.
data.platOrderNo	string	64	Yes	Platform payout order number, used for platform-side order tracking and queries.
data.amount	decimal	25,2	Yes	Payout amount submitted by the partner.
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 payout order; successful API acceptance does not mean this field is in a success state.

orderStatus Enum

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

Response Example

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

Response Error Codes

• Response Status

Transaction Result Handling Principles

• status = 200 means the request was accepted; it must not be taken as proof that the payout succeeded or that funds reached the user.
• orderStatus = PENDING means the order is still processing; only SUCCESS or FAILED are final states in the current payout flow.
• The partner should integrate both the asynchronous notification and the order query: the notification keeps orders up to date, and the query covers synchronous timeouts, missed notifications, and status reconciliation.
• When the bank or network returns a timeout or an unknown result, the partner must not create a new order directly; query or retry with the original merchant order number to avoid duplicate payouts.
• Asynchronous notifications may be delivered more than once due to network retries. The partner must use platOrderNo as the primary key and apply idempotent processing together with merchantOrderNo and the order status; duplicate notifications must not lead to duplicate accounting.
• The merchant order number is the payout idempotency key with a validity window of 3 months: resubmitting the same order number within the window returns the result of the first acceptance and does not create a duplicate payout order.
• Cashin and cashout idempotency are independent of each other: a merchant order number already submitted for payout can still be submitted for cashin; an order number only needs to be unique within the same business direction.
• Upon receiving a success notification, the partner should first verify the signature, then check the merchant order number, platform order number, amount, currency, and order status; only after everything matches should it complete the withdrawal, refund, settlement, or other business state updates.