Criar pagamento PayOUT

O PayOUT permite que um merchant envie pagamentos a beneficiários por meio da Orkestral. A plataforma valida a solicitação, encaminha o pagamento ao Provedor de Serviços de Pagamento (PSP) informado e acompanha a transação até seu estado final.

Antes de começar

Você precisa:

ter um cadastro ativo na plataforma Orkestral;
cadastrar e configurar um PSP compatível com PayOUT;
obter um token OAuth/JWT;
conhecer o UUID do merchant (merchantId);
cadastrar uma URL HTTPS pública para receber notificações;
validar os dados bancários e a identificação do beneficiário.

Ambientes

Ambiente	URL base
Homologação (QAS)	`https://api-qas.orkestralpay.com.br`

Solicite ao time Orkestral a URL de produção e as credenciais correspondentes. Não reutilize tokens, credenciais de PSP ou dados de beneficiários entre ambientes.

Autenticação

Envie o token e o endereço IP de origem nos headers:

Authorization: Bearer <access_token>
Content-Type: application/json
IP: <endereço_ip_de_origem>

Tokens e credenciais são dados sensíveis. Mantenha-os apenas em serviços de backend e nunca os exponha no frontend, em repositórios ou em logs.

Endpoint

POST /transaction/payout/{merchantId}

O campo psp seleciona o provedor. Diferentemente do PayIN, a seleção não é feita por um fluxo de pagamento.

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`transaction_id`	UUID	Sim	Identificador único definido pelo merchant.
`amount`	inteiro	Sim	Valor positivo na menor unidade da moeda. Ex.: `100` = 1,00.
`currency`	string	Sim	Código da moeda em letras maiúsculas.
`name`	string	Sim	Nome do beneficiário.
`last_name`	string	Sim	Sobrenome do beneficiário.
`email`	string	Condicional	E-mail do beneficiário, exigido por alguns PSPs.
`birth_date`	string	Condicional	Data de nascimento no formato `AAAA-MM-DD`.
`document`	string	Sim	Número do documento do beneficiário.
`document_type`	string	Sim	Tipo de documento aceito pelo país e pelo PSP.
`bank_name`	string	Condicional	Nome do banco.
`bank_code`	string	Condicional	Código do banco.
`agency_code`	inteiro	Condicional	Código da agência.
`agency_digit`	inteiro	Condicional	Dígito da agência.
`account_code`	string	Condicional	Número da conta.
`account_digit`	string	Condicional	Dígito da conta.
`account_type`	string	Condicional	Tipo de conta aceito pelo PSP.
`psp`	string	Sim	`Kushki`, `Payvalida`, `WePayments` ou `PayU`.
`pix_key`	string	Condicional	Chave PIX. Quando informada, o pagamento é processado como PIX.

Os campos condicionais variam conforme o PSP, o país e o método. Confirme o catálogo de bancos habilitado para seu contrato antes de enviar o pagamento.

Transferência bancária

Para criar uma transferência, omita pix_key e envie os dados bancários exigidos pelo 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"
  }'

Substitua identificadores, dados do beneficiário, banco, IP e credenciais pelos valores do seu ambiente.

PIX

O PIX está disponível para PayOUT com WePayments. Informe uma chave válida em pix_key; os campos bancários podem ser omitidos:

{
  "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"
}

cuidado

Não envie uma chave PIX de produção durante testes. Use somente beneficiários e chaves disponibilizados para o ambiente de homologação.

Regras por PSP

PSP	Países e moedas da referência	Documentos principais	Método e regras principais
`Kushki`	CO/COP, CL/CLP ou UF, EC/USD, PE/PEN ou USD, MX/MXN	`CC`, `NIT`, `CE`, `TI`, `PP`, `RUC`, `CURP`, `RFC`, `RUT`, `DNI`, `PAS`, `CI`	Transferência; exige banco, conta e tipo de conta compatíveis com o país.
`Payvalida`	CO/COP, GT/GTQ, PE/PEN	CO: `CC`, `CE`, `PS`, `TI`; GT: `DPI`; PE: `DNI`, `CE`	Transferência; `email`, banco, número e tipo de conta são necessários.
`WePayments`	BR/BRL	`CPF`, `CNPJ`	PIX ou transferência; o documento deve ser válido. Transferências exigem os dados bancários completos.
`PayU`	CO/COP	Tipos aceitos pelo contrato PayU	Transferência; exige `birth_date`, `bank_code`, `account_code` e `account_type`.

Tipos de conta

PSP	Valores utilizados
Kushki	`CC`, `CA`, `CB`, `TD`, `NC`, `CV`, `DE`, `CM`, conforme o país
Payvalida	Colômbia e Peru: `Ahorro`, `Corriente`; Guatemala: `Ahorro`, `Monetaria`
WePayments	Use o valor habilitado no contrato, como `CHECKING` ou `SAVINGS`; confirme o catálogo com o time Orkestral
PayU	Use o tipo de conta aceito pela configuração PayU do merchant

Para Kushki no Peru, contas do banco 002 usam 13 dígitos para CC e 14 para CA; contas de outros bancos usam 20 dígitos. Para PayU, bank_code deve ser um código colombiano habilitado. Solicite ao time Orkestral o catálogo vigente quando um banco não estiver disponível no ambiente.

Como preencher e testar os dados bancários

O valor de bank_code não segue o mesmo formato em todos os PSPs. Envie-o como string para preservar zeros à esquerda.

Kushki

A Orkestral encaminha bank_code à Kushki como BankId. O identificador varia por país; portanto, não reutilize um código de outro país apenas porque os dígitos são semelhantes.

Na Colômbia, a referência do PSP utiliza seis dígitos. Alguns códigos úteis para homologação são:

`bank_code`	Instituição
`000001`	Banco de Bogotá
`000002`	Banco Popular
`000007`	Bancolombia
`000013`	BBVA Colombia
`000051`	Davivienda
`000052`	Banco AV Villas
`000507`	Nequi

No Peru, o BankId também determina o tamanho de account_code:

`BankId`	`account_type`	Tamanho de `account_code`
`002`	`CC`	13 dígitos
`002`	`CA`	14 dígitos
diferente de `002`	Qualquer tipo aceito	20 dígitos

aviso

O BankId peruano 002 não é o código colombiano 000002 (Banco Popular). País, moeda, documento, banco, tipo e tamanho da conta precisam pertencer ao mesmo cenário de teste.

Payvalida

Para Payvalida, bank_code recebe o nome da instituição conforme o catálogo do país, e não um código numérico da Kushki. Use a grafia exata retornada para o merchant. A referência lista:

Peru: BBVA CONTINENTAL, INTERBANK, BCP e 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 e VIVIBANCO;
Colômbia: use o nome exato habilitado no catálogo do merchant, por exemplo BANCOLOMBIA, BANCO DE BOGOTA, DAVIVIENDA, NEQUI ou BBVA.

Combine o banco com o tipo de conta do país: Ahorro ou Corriente para Colômbia e Peru; Ahorro ou Monetaria para Guatemala.

:::tip Roteiro mínimo de homologação

Confirme o país, a moeda e o PSP configurados para o merchant.
Obtenha o bank_code no catálogo desse mesmo ambiente e mantenha o valor como string.
Selecione um document_type e um account_type aceitos no país.
Para Kushki no Peru, ajuste account_code de acordo com o BankId antes de enviar a requisição.
Use um novo transaction_id em cada cenário e acompanhe o resultado até o status final.

:::

Glossário

O significado de uma sigla depende do campo em que ela é enviada. Por exemplo, CC significa documento de identidade em document_type, mas conta corrente em account_type.

Tipos de documento

Sigla	Significado
`CC`	Documento de identidade
`NIT`	Número de identificação tributária da Colômbia
`CE`	Cédula de estrangeiro da Colômbia ou do Peru
`TI`	Cartão de identidade da Colômbia
`PP`	Passaporte
`RUC`	Registro tributário do Equador ou do Peru
`CURP`	Código de Registro Único da População do México
`RFC`	Registro Federal de Contribuintes do México
`RUT`	Registro Único Tributário do Chile
`DNI`	Documento Nacional de Identidade do Peru
`PAS`	Passaporte do Peru ou do Equador
`CI`	Cédula de identidade do Equador
`PS`	Passaporte, conforme a nomenclatura da Payvalida na Colômbia
`DPI`	Documento Pessoal de Identificação da Guatemala
`CPF`	Cadastro de Pessoa Física do Brasil
`CNPJ`	Cadastro Nacional da Pessoa Jurídica do Brasil

Tipos de conta Kushki

Sigla	Significado
`CC`	Conta corrente na Colômbia, no Chile e Peru
`CA`	Conta poupança na Colômbia, no Chile e Peru
`CB`	Conta CLABE, somente no México
`TD`	Cartão de débito, somente no México
`NC`	Número de celular, somente no México
`CV`	Conta vista no Chile
`DE`	Depósito eletrônico na Colômbia
`CM`	Conta mestra no Peru

informação

As combinações disponíveis dependem do contrato e das credenciais cadastradas para o merchant. Uma moeda listada não garante que ela esteja habilitada para todas as contas.

Resposta de sucesso

Uma solicitação aceita retorna 200 OK. Os campos opcionais variam conforme o 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>"
}

Guarde id e psp_transaction_identification para conciliação. O status WAITING_PSP_PAYMENT indica que o PSP recebeu a solicitação; ele não confirma que o beneficiário já recebeu o valor.

Status do PayOUT

Status	Significado
`WAITING_PSP_PAYMENT`	O pagamento foi enviado e aguarda a confirmação do PSP.
`SETTLED`	O PSP confirmou a liquidação.
`DENIED`	O PSP negou o pagamento.
`ERROR`	Ocorreu uma falha de validação, configuração ou processamento.

Webhooks

Cadastre a URL de Notificação do merchant para receber mudanças de status. A Orkestral envia uma requisição PATCH para a URL cadastrada:

PATCH <url_de_notificação>
Content-Type: application/json
IP: <endereço_do_serviço_notificador>

{
  "status": {
    "paymentStatusId": 6,
    "name": "SETTLED"
  },
  "message": "Pagamento liquidado"
}

Retorne um HTTP 2xx rapidamente e processe notificações de forma idempotente. O header IP não é uma assinatura criptográfica e não deve ser o único meio de autenticar a origem.

Consulte Chave Secreta e URL de Notificação para configurar e proteger o endpoint.

Tratamento de erros

HTTP	Situação comum	Ação recomendada
`400`	Campo inválido ou combinação não aceita pelo PSP	Corrija o payload antes de repetir.
`401`	Token ausente, inválido ou expirado	Obtenha um token válido.
`403`	Credencial sem acesso ao recurso	Confira o merchant e as permissões.
`404`	Merchant, PSP ou configuração inexistente	Verifique o ambiente e os cadastros.
`409`	`transaction_id` já utilizado	Concilie a solicitação original.
`422`	Regra de negócio ou credencial do PSP inválida	Revise moeda, beneficiário, banco e configuração.
`5xx`	Falha temporária	Consulte a transação antes de repetir e aplique backoff.

Não repita um PayOUT com outro transaction_id após timeout ou erro 5xx sem confirmar se a primeira solicitação foi processada. Uma repetição indevida pode gerar um pagamento duplicado.

Segurança e boas práticas

Valide beneficiário, documento, banco, conta, moeda e valor antes do envio;
Use um transaction_id único e mantenha-o na conciliação;
Restrinja tokens e credenciais aos serviços de backend;
Não registre tokens, documentos completos, contas ou chaves PIX em logs;
Use TLS e certificados HTTPS válidos;
Trate a resposta inicial como assíncrona e aguarde o estado final;
Valide e processe webhooks de forma idempotente;
Separe dados e credenciais de homologação e produção.

Antes de começar​

Ambientes​

Autenticação​

Endpoint​

Campos da requisição​

Transferência bancária​

PIX​

Regras por PSP​

Tipos de conta​

Como preencher e testar os dados bancários​

Kushki​

Payvalida​

Glossário​

Tipos de documento​

Tipos de conta Kushki​

Resposta de sucesso​

Status do PayOUT​

Webhooks​

Tratamento de erros​

Segurança e boas práticas​