Create a PayOUT payment

PayOUT allows a merchant to send payments to beneficiaries through Orkestral. The platform validates the request, sends the payment to the specified Payment Service Provider (PSP), and tracks the transaction until its final state.

Before you start

You need:

• an active Orkestral account;
• a registered and configured PSP that supports PayOUT;
• an OAuth/JWT access token;
• the merchant UUID (merchantId);
• a public HTTPS URL for notifications;
• validated beneficiary identity and bank details.

Environments

Environment	Base URL
QAS	https://api-qas.orkestralpay.com.br

Ask the Orkestral team for the production URL and credentials. Do not reuse tokens, PSP credentials, or beneficiary data across environments.

Authentication

Send the token and source IP address in the headers:

Authorization: Bearer <access_token>
Content-Type: application/json
IP: <source_ip_address>

Keep tokens and credentials in backend services only. Never expose them in a frontend, repository, or log.

Endpoint

POST /transaction/payout/{merchantId}

The psp field selects the provider. Unlike PayIN, this selection is not made by a payment flow.

Request fields

Field	Type	Required	Description
transaction_id	UUID	Yes	Unique identifier assigned by the merchant.
amount	integer	Yes	Positive value in the currency's minor unit. Example: 100 = 1.00.
currency	string	Yes	Uppercase currency code.
name	string	Yes	Beneficiary's first name.
last_name	string	Yes	Beneficiary's last name.
email	string	Conditional	Beneficiary email required by some PSPs.
birth_date	string	Conditional	Birth date in YYYY-MM-DD format.
document	string	Yes	Beneficiary document number.
document_type	string	Yes	Document type accepted by the country and PSP.
bank_name	string	Conditional	Bank name.
bank_code	string	Conditional	Bank code.
agency_code	integer	Conditional	Branch code.
agency_digit	integer	Conditional	Branch check digit.
account_code	string	Conditional	Account number.
account_digit	string	Conditional	Account check digit.
account_type	string	Conditional	Account type accepted by the PSP.
psp	string	Yes	Kushki, Payvalida, WePayments, or PayU.
pix_key	string	Conditional	PIX key. When present, the payment is processed as PIX.

Conditional fields vary by PSP, country, and method. Confirm the bank catalog enabled for your agreement before sending a payment.

Bank transfer

For a bank transfer, omit pix_key and send the bank details required by the PSP:

curl --request POST \
  --url "https://api-qas.orkestralpay.com.br/transaction/payout/<merchantId>" \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --header "IP: 192.0.2.10" \
  --data '{
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
    "amount": 10000,
    "currency": "COP",
    "name": "María",
    "last_name": "García",
    "email": "maria.garcia@example.com",
    "birth_date": "1990-01-01",
    "document": "123456789",
    "document_type": "CC",
    "bank_name": "BANCOLOMBIA",
    "bank_code": "000007",
    "agency_code": 1234,
    "agency_digit": 5,
    "account_code": "987654321",
    "account_digit": "0",
    "account_type": "CA",
    "psp": "Kushki"
  }'

Replace identifiers, beneficiary data, bank, IP address, and credentials with values from your environment.

PIX

PIX PayOUT is available with WePayments. Send a valid pix_key; bank fields may be omitted:

{
  "transaction_id": "123e4567-e89b-12d3-a456-426614174001",
  "amount": 10000,
  "currency": "BRL",
  "name": "João",
  "last_name": "Silva",
  "email": "joao.silva@example.com",
  "document": "52998224725",
  "document_type": "CPF",
  "psp": "WePayments",
  "pix_key": "joao.silva@example.com"
}

caution

Do not send a production PIX key during testing. Use only beneficiaries and keys provided for the QAS environment.

PSP rules

PSP	Reference countries and currencies	Main documents	Main method and rules
Kushki	CO/COP, CL/CLP or UF, EC/USD, PE/PEN or USD, MX/MXN	CC, NIT, CE, TI, PP, RUC, CURP, RFC, RUT, DNI, PAS, CI	Transfer; requires bank, account, and account type compatible with the country.
Payvalida	CO/COP, GT/GTQ, PE/PEN	CO: CC, CE, PS, TI; GT: DPI; PE: DNI, CE	Transfer; email, bank, account number, and account type are required.
WePayments	BR/BRL	CPF, CNPJ	PIX or transfer; document must be valid. Transfers require complete bank details.
PayU	CO/COP	Types accepted by the PayU agreement	Transfer; requires birth_date, bank_code, account_code, and account_type.

Account types

PSP	Values
Kushki	CC, CA, CB, TD, NC, CV, DE, CM, depending on the country
Payvalida	Colombia and Peru: Ahorro, Corriente; Guatemala: Ahorro, Monetaria
WePayments	Use the value enabled by your agreement, such as CHECKING or SAVINGS; confirm the catalog with the Orkestral team
PayU	Use the account type accepted by the merchant's PayU configuration

For Kushki in Peru, accounts at bank 002 use 13 digits for CC and 14 for CA; accounts at other banks use 20 digits. For PayU, bank_code must be an enabled Colombian bank code. Ask the Orkestral team for the current catalog when a bank is unavailable in the environment.

How to fill in and test bank details

The bank_code value does not use the same format for every PSP. Send it as a string to preserve leading zeros.

Kushki

Orkestral forwards bank_code to Kushki as BankId. The identifier varies by country, so do not reuse a code from another country merely because the digits look similar.

In Colombia, the PSP reference uses six digits. Useful QAS codes include:

bank_code	Institution
000001	Banco de Bogotá
000002	Banco Popular
000007	Bancolombia
000013	BBVA Colombia
000051	Davivienda
000052	Banco AV Villas
000507	Nequi

In Peru, BankId also determines the length of account_code:

BankId	account_type	account_code length
002	CC	13 digits
002	CA	14 digits
Other than 002	Any accepted type	20 digits

warning

Peruvian BankId 002 is not Colombian code 000002 (Banco Popular). Country, currency, document, bank, account type, and account length must belong to the same test scenario.

Payvalida

For Payvalida, bank_code receives the institution name from the country's catalog, not a numeric Kushki code. Use the exact spelling returned for the merchant. The reference lists:

• Peru: BBVA CONTINENTAL, INTERBANK, BCP, and SCOTIABANK PERU;
• Guatemala: BAM, BANCO AZTECA, BANCO DE AMERICA CENTRAL, BANCO DE ANTIGUA, BANCO DE CREDITO, BANCO DE DESARROLLO RURAL, BANCO DE GUATEMALA, BANCO DE LOS TRABAJADORES, BANCO FICOHSA, BANCO GYT CONTINENTAL, BANCO INDUSTRIAL, BANCO INMOBILIARIO, BANCO INTERNACIONAL, BANCO INV, BANCO PROMERICA DE GUATEMALA, BANCO PROMERICA, CITIBANK SUCURSAL GUATEMALA, CREDITO HIPOTECARIO NACIONAL, and VIVIBANCO;
• Colombia: use the exact name enabled in the merchant catalog, such as BANCOLOMBIA, BANCO DE BOGOTA, DAVIVIENDA, NEQUI, or BBVA.

Match the bank with the country's account type: Ahorro or Corriente for Colombia and Peru; Ahorro or Monetaria for Guatemala.

:::tip Minimum QAS checklist

1. Confirm the country, currency, and PSP configured for the merchant.
2. Get bank_code from the same environment's catalog and keep it as a string.
3. Select a document_type and account_type accepted in that country.
4. For Kushki in Peru, adjust account_code according to BankId before sending the request.
5. Use a new transaction_id for each scenario and follow it to a final status.

:::

Glossary

An abbreviation's meaning depends on the field in which it is sent. For example, CC means identity document in document_type, but checking account in account_type.

Document types

Abbreviation	Meaning
CC	Identity document
NIT	Colombian tax identification number
CE	Foreign resident card in Colombia or Peru
TI	Colombian identity card
PP	Passport
RUC	Tax identification number in Ecuador or Peru
CURP	Mexican Unique Population Registry Code
RFC	Mexican Federal Taxpayer Registry
RUT	Chilean Unique Tax Registry
DNI	Peruvian National Identity Document
PAS	Passport in Peru or Ecuador
CI	Ecuadorian identity card
PS	Passport, as named by Payvalida in Colombia
DPI	Guatemalan Personal Identification Document
CPF	Brazilian Individual Taxpayer Registry
CNPJ	Brazilian National Registry of Legal Entities

Kushki account types

Abbreviation	Meaning
CC	Checking account in Colombia, Chile, and Peru
CA	Savings account in Colombia, Chile, and Peru
CB	CLABE account, Mexico only
TD	Debit card, Mexico only
NC	Mobile phone number, Mexico only
CV	Sight account in Chile
DE	Electronic deposit in Colombia
CM	Master account in Peru

info

Available combinations depend on the agreement and credentials registered for the merchant. A listed currency is not necessarily enabled for every account.

Success response

An accepted request returns 200 OK. Optional fields vary by PSP:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "amount": 10000,
  "currency": "COP",
  "payment_method": "TRANSFER",
  "status": "WAITING_PSP_PAYMENT",
  "custom_code": "123e4567-e89b-12d3-a456-426614174000",
  "created_date": "2026-07-31T15:00:00",
  "country": "CO",
  "psp_information": {
    "psp_id": "<psp_uuid>",
    "psp_name": "Kushki"
  },
  "psp_transaction_identification": "<psp_transaction_id>"
}

Store id and psp_transaction_identification for reconciliation. WAITING_PSP_PAYMENT means the PSP received the request; it does not confirm that the beneficiary has received the funds.

PayOUT statuses

Status	Meaning
WAITING_PSP_PAYMENT	The payment was sent and awaits PSP confirmation.
SETTLED	The PSP confirmed settlement.
DENIED	The PSP denied the payment.
ERROR	A validation, configuration, or processing failure occurred.

Webhooks

Register the merchant's Notification URL to receive status changes. Orkestral sends a PATCH request to the registered URL:

PATCH <notification_url>
Content-Type: application/json
IP: <notifier_service_address>

{
  "status": {
    "paymentStatusId": 6,
    "name": "SETTLED"
  },
  "message": "Payment settled"
}

Return an HTTP 2xx response promptly and process notifications idempotently. The IP header is not a cryptographic signature and must not be the only way to authenticate the source.

See Secret Key and Notification URL for configuration and security guidance.

Error handling

HTTP	Common situation	Recommended action
400	Invalid field or unsupported PSP combination	Fix the payload before retrying.
401	Missing, invalid, or expired token	Obtain a valid token.
403	Credential cannot access the resource	Check merchant permissions.
404	Merchant, PSP, or configuration not found	Check the environment and registrations.
409	transaction_id already used	Reconcile the original request.
422	Business rule or invalid PSP credential	Review currency, beneficiary, bank, and configuration.
5xx	Temporary failure	Query the transaction before retrying and use backoff.

Do not retry a PayOUT with a different transaction_id after a timeout or 5xx until you confirm whether the first request was processed. An incorrect retry may create a duplicate payment.

Security and best practices

• Validate the beneficiary, document, bank, account, currency, and amount;
• Use a unique transaction_id and retain it for reconciliation;
• Restrict tokens and credentials to backend services;
• Do not log tokens, full documents, accounts, or PIX keys;
• Use TLS and valid HTTPS certificates;
• Treat the initial response as asynchronous and wait for a final state;
• Validate and process webhooks idempotently;
• Keep QAS and production data and credentials separate.