Criar pagamento PIX

POST/v1/payouts

Paga uma chave PIX com o saldo disponível. Valor e tarifa saem do disponível na hora em que o pedido é aceito, e voltam se o pagamento não for concluído. Escopo da chave: payouts em write.

Cabeçalhos

  • AuthorizationtextoobrigatórioBearer com a sua chave: sk_test_… no teste, sk_live_… em produção.
  • Idempotency-KeytextoobrigatórioUm valor único por pedido (ex.: o número do pedido), até 255 caracteres visíveis, sem espaços. Mesmo corpo de novo: a resposta guardada, com Idempotent-Replayed: true. Outro corpo: 409. Vale por 7 dias.
  • Content-Typetextoobrigatórioapplication/json

Corpo

  • amounttextoobrigatórioValor em texto decimal com ponto, ex.: "80.00", maior que zero e com até 2 casas em BRL.
  • currencytextoobrigatório"BRL" para PIX. SPEI (MXN) e COP (Colômbia, em pesos inteiros): em breve.
  • destinationobjetoobrigatórioPara onde vai: um destino avulso, um beneficiário salvo ou uma conta de saque da empresa (veja abaixo).
  • descriptiontextoopcionalAté 140 caracteres. Aparece no extrato.
  • externalIdtextoopcionalO id do pagamento no seu sistema, até 100 caracteres, único por empresa e ambiente. Repetir responde 409 EXTERNAL_ID_CONFLICT (não devolve o existente: busque com GET /v1/payouts?externalId=).

Destino

Mande uma das três formas. A avulsa, com a chave PIX:

  • railtextoobrigatório"PIX".
  • keyTypetextoobrigatório"CPF", "CNPJ", "EMAIL", "PHONE" ou "EVP" (chave aleatória).
  • keytextoobrigatórioA chave, conferida pelo tipo: CPF/CNPJ com ou sem pontuação, e-mail, telefone brasileiro com DDD (vira +55…) ou a chave aleatória.
  • holderNametextoobrigatórioNome do titular, de 2 a 160 caracteres.
  • holderDocumenttextoopcionalCPF ou CNPJ do titular. Há provedores que exigem para pagar.
Formas de destino
// Destino avulso, chave PIX
{ "rail": "PIX", "keyType": "CPF", "key": "111.444.777-35", "holderName": "Carla Lima" }

// Beneficiário salvo (POST /v1/beneficiaries)
{ "beneficiaryId": "ben_7Rq2Lt5Wx9Pd" }

// Conta de saque da própria empresa (cadastrada no painel)
{ "settlementAccountId": "sa_2Vn6Hk9Qs3Zm" }

Na Colômbia (em breve), o destino avulso é uma chave Bre-B ou uma conta bancária; os provedores exigem celular e e-mail do titular sempre:

  • railtextoobrigatório"BREB" (em COP).
  • targettextoobrigatório"KEY" (chave Bre-B) ou "ACCOUNT" (conta bancária).
  • keytextoopcionalCom KEY: a chave Bre-B do recebedor (celular, e-mail, documento ou chave com @).
  • accounttextoopcionalCom ACCOUNT: o número da conta, de 4 a 20 dígitos.
  • bankCodetextoopcionalCom ACCOUNT, obrigatório: o banco da conta, um código de GET /v1/banks?method=PSE.
  • holderNametextoobrigatórioNome do titular, de 2 a 160 caracteres.
  • holderPhonetextoobrigatórioCelular colombiano do titular: 10 dígitos começando com 3, com ou sem +57.
  • holderEmailtextoobrigatórioE-mail do titular.
  • holderDocumentTypetextoopcionalCom ACCOUNT, obrigatório: "CC", "CE", "NIT", "PA", "PPT", "TI", "RC", "TE" ou "DIE".
  • holderDocumenttextoopcionalCom ACCOUNT, obrigatório: o número do documento (o NIT pode vir com o dígito verificador, que é conferido).
  • Beneficiários (destinos de terceiros que você paga sempre) se salvam com POST /v1/beneficiaries, com os mesmos campos do destino avulso; o mesmo destino de novo responde 409 CONFLICT com o id do existente em error.details.beneficiaryId.
  • Contas de saque são da própria empresa e só se cadastram no painel; pela API, GET /v1/settlement-accounts lista os ids.

Status

Status do pagamento
StatusO que significa
PENDING_APPROVALEsperando outra pessoa da empresa aprovar (regra de aprovação).
IN_REVIEWEsperando a análise da plataforma.
QUEUEDNa fila para ir ao provedor. Ainda dá para cancelar.
PROCESSINGAceito pelo provedor, esperando o resultado.
UNKNOWNO envio não teve resposta clara: a plataforma consulta o provedor antes de qualquer nova tentativa. Para você, é "processando".
PAIDPago. endToEndId e paidAt preenchidos.
FAILEDNão foi concluído; valor e tarifa voltaram ao disponível. statusReason diz o motivo.
REJECTEDRecusado na aprovação (empresa ou plataforma); valor e tarifa voltaram.
CANCELEDCancelado antes do envio; valor e tarifa voltaram.
RETURNEDPago e devolvido depois pelo banco de destino; valor e tarifa voltaram.

A resposta traz fee (a tarifa) e total (valor + tarifa, o que saiu do disponível). Se o pedido vai para aprovação, veja Aprovações.

Erros

Códigos de erro
CódigoHTTPQuando acontece
VALIDATION_ERROR422Valor, moeda ou destino fora do formato: chave que não bate com o tipo, documento do titular inválido. error.details aponta o campo.
NOT_FOUND404O beneficiário ou a conta de saque não existe neste ambiente (ou foi arquivado).
PAYMENT_METHOD_UNAVAILABLE422A moeda não é a do trilho (PIX paga em BRL).
INSUFFICIENT_BALANCE422O disponível não cobre valor + tarifa. Nada foi criado.
EXTERNAL_ID_CONFLICT409Já existe um pagamento com este externalId.
RISK_DECLINED422Recusado pela análise de risco. A resposta não diz o motivo.
IDEMPOTENCY_KEY_REUSED409A Idempotency-Key já foi usada com outro corpo.
PAYOUTS_DISABLED503Pagamentos pausados pela plataforma. Tente mais tarde com a mesma Idempotency-Key.
PROVIDER_UNAVAILABLE503Nenhum provedor de saída disponível agora. Tente de novo com a mesma Idempotency-Key.

Acompanhar e cancelar

  • payout.created
  • payout.approved
  • payout.paid
  • payout.failed
  • payout.returned

payout.failed vale para falha, recusa e cancelamento: confira data.status. Consulte com GET /v1/payouts/:id ou liste com GET /v1/payouts (filtros status e externalId, com cursor).

Para cancelar, POST /v1/payouts/:id/cancel (escopo payouts em write): vale enquanto o pagamento ainda não foi enviado (PENDING_APPROVAL, IN_REVIEW ou QUEUED). Depois disso, a resposta é 409 CONFLICT.

Cancelar
curl -X POST https://api.averopay.io/v1/payouts/po_8Kd3Mq7Zs2Vb/cancel \
  -H "Authorization: Bearer sk_test_..."

No ambiente de teste, uma chave PIX com "falha" no texto termina em falha, para você testar o estorno ao saldo.