Skip to content
Gowd Platform Production

Create banking payout

POST
/order/v1/banking/order-payouts

Create a PIX or TED payout using accountId as payer. The initiation type is inferred from paymentData: pixKey (KEY), qrcodeData (STATIC/DYNAMIC_QRCODE) or bankAccount (MANUAL). For TED, only bankAccount is accepted.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
idempotency-key
required
string

Unique key for idempotent requests

Request Body required

Section titled “Request Body required ”
object
externalId
required

External identifier of the payout

string
Example
payout-123
accountId
required

Payer account identifier

string format: uuid
Example
f288ae0d-47fd-4207-aee4-0a384888bd96
paymentMethod
required

Payment method

string
Allowed values: PIX TED
Example
TED
receiver

Receiver information. Required for TED and manual bankAccount payouts. Optional for pixKey and qrcodeData payouts, where it is resolved from the DICT key or the decoded QR Code; when provided, the receiver document is compared against the key/QR Code owner.

object
name
required

Receiver full name

string
document
required

Receiver document

object
type
required

Document type

string
Allowed values: CPF CNPJ
Example
CPF
number
required

Document number

string
Example
12345678901
Example
{
  "name": "Maria Silva",
  "document": {
    "type": "CPF",
    "number": "12345678901"
  }
}
paymentData
required

Payment data. Provide exactly one field: pixKey (KEY initiation), qrcodeData (STATIC or DYNAMIC QR Code, determined automatically) or bankAccount (MANUAL initiation). For TED, only bankAccount is accepted.

object
pixKey

Pix key for KEY initiation

string
qrcodeData

QR Code data for STATIC/DYNAMIC initiation

string
bankAccount

Bank account data (required for MANUAL initiation)

object
ispb

ISPB code of the receiving bank. Provide either ispb or bankNumber.

string
bankNumber

COMPE bank number of the receiving bank, resolved to an ISPB via SPI. Provide either ispb or bankNumber.

string
Example
341
accountType
required

Account type

string
Allowed values: CHECKING_ACCOUNT WAGE_ACCOUNT SAVINGS_ACCOUNT PAYMENT_ACCOUNT
Example
CHECKING_ACCOUNT
branchNumber
required

Branch number

string
accountNumber
required

Account number

string
Example
{
  "bankAccount": {
    "ispb": "12345678",
    "branchNumber": "0001",
    "accountNumber": "123456",
    "accountType": "CHECKING_ACCOUNT"
  }
}
amount
required

Payout amount

object
currency
required

Currency code

string
Allowed values: BRL
Example
BRL
value
required

Amount value as a numeric string. A JSON number is also accepted.

string
Example
10.00
Example
{
  "currency": "BRL",
  "value": "50.00"
}
description
required

Description of the payout

string
Example
Invoice 123 payout
Examples

PIX payout

{
  "externalId": "payout-123",
  "accountId": "f288ae0d-47fd-4207-aee4-0a384888bd96",
  "paymentMethod": "PIX",
  "receiver": {
    "name": "Maria Silva",
    "document": {
      "type": "CPF",
      "number": "12345678901"
    }
  },
  "paymentData": {
    "pixKey": "[email protected]"
  },
  "amount": {
    "currency": "BRL",
    "value": "50.00"
  },
  "description": "Invoice 123 payout"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”
object
id
required

Payout identifier

string
Example
c1c4c0b1-3bb8-4b1c-9e47-3f4a6f3a1b2c
externalId
required

External identifier

string
Example
payout-123
status
required

Status of the payout

string
Example
PENDING
amount
required

Amount value as string

string
Example
50.00
currency
required

Currency

string
Allowed values: BRL USD ARS EUR CLP COP MXN PEN BUSD USDT
Example
BRL
description
required

Payout description

string
Example
Invoice 123
endToEndId
required

EndToEnd identifier (PIX)

string
Example
E12345678920240101120000abcd
controlNumber

Control number of the transfer (TED)

string
Example
20260810001234567
batch

Batch information when this payout was split into a batch

object
id
required

Id of the batch

string
Example
5160c73e-8b9b-4f1f-8c64-0edcbb97c335
transactionsCount
required

Total number of child transactions in the batch

number
Example
3
paidCount
required

Number of child transactions already paid

number
Example
2
failedCount
required

Number of child transactions that failed

number
Example
1
pendingCount
required

Number of child transactions still pending

number
0
paidAmount
required

Amount already paid across all child transactions

string
Example
30000.00
pendingAmount
required

Amount still pending across all child transactions

string
Example
15000.00
transactions
required

Child transactions the batch was split into

Array<object>
object
id
required

Id of this child transaction

string
Example
a4cf980e-f66d-4321-b0f2-95c7eecca7ce
idempotencyKey
required

Idempotency key of this child transaction - the first child reuses the batch idempotencyKey verbatim, later ones suffix it

string
Example
bf8b0b1f-f444-40c5-b657-d236ee03e6ba-01
sequence
required

Ordering position of this child transaction within the batch

number
Example
1
amount
required

Amount of this child transaction

string
Example
15000.00
status
required

Status of this child transaction

string
Allowed values: INITIAL PENDING PAID EXPIRED ANALYSIS REFUNDED PARTIAL_REFUNDED PARTIALLY_PAID CANCELED ERROR
Example
PAID
endToEndId

End-to-end id of this child transaction

string
Example
E69467793202607101200Je8IkFT5JQS
paidAt

Date this child transaction was paid

string
Example
2026-07-10T12:01:03.000Z
errorMessage

Error message when this child transaction failed

string
Example
An unexpected error occurred
errorMessage

Payout error message

string
Examples

PIX payout created

{
  "id": "c1c4c0b1-3bb8-4b1c-9e47-3f4a6f3a1b2c",
  "externalId": "payout-123",
  "status": "PENDING",
  "amount": "50.00",
  "currency": "BRL",
  "description": "Invoice 123 payout",
  "endToEndId": "E12345678920240101120000abcd"
}

400

Section titled “400 ”

Bad request

403

Section titled “403 ”

Forbidden

500

Section titled “500 ”

Internal error