Push Transaction

Transações push (payout) transferem fundos para um destinatário — para uma conta bancária, carteira, chave PIX, endereço UPI ou cartão.

Endpoint

POST https://{FQDN}/v2/payment

Headers:

O schema do país é o contrato

Cada país de payout tem seu próprio JSON Schema draft-07. Ele decide quais campos de paymentMethod existem, quais são obrigatórios, o pattern que cada um deve casar, os valores permitidos de walletOperator, se recipient.documents é obrigatório e qual moeda o recipientAmount pode carregar. Essas regras diferem por corredor e mudam conforme corredores são adicionados — um recipient fixado para um país será rejeitado pelo próximo.

Busque o schema do país de destino e construa a requisição a partir dele:

GET https://{FQDN}/schema/{countryCode}

O countryCode é ISO 3166-1 alpha-3 (BRA, IND, PHL). A resposta cobre recipient, recipientAmount e additionalData — e, nos corredores que o restringem, sender. Veja Schemas para a referência completa do endpoint.

O sender está presente em alguns schemas de país e ausente em outros. Onde aparece, ele aperta as regras do lado do remetente além do schema genérico de push; onde está ausente, valem apenas as regras genéricas. Isso está sendo preenchido — trate um bloco sender ausente como "ainda não restrito aqui", não como "nunca será restrito". Ler o bloco no momento da requisição, em vez de guardar uma cópia, é o que mantém você à frente disso.

Este é o schema contra o qual o gateway valida o POST /v2/payment, então é o único que responde "esse payload vai ser aceito?" para um push.

flowchart TD
  A[Escolha o país de destino] --> B["GET /schema/{countryCode}"]
  B --> C{"paymentMethod.type<br/>oferecido pelo corredor"}
  C -->|BANK_DEPOSIT| D["accountNumber + os<br/>campos que o schema exige"]
  C -->|WALLET| E["walletId + walletType<br/>+ walletOperator"]
  C -->|PIX| F["key + keyType"]
  C -->|CARD| G["cardTokenId"]
  D --> H["Inclua recipient.documents e<br/>additionalData.paymentPurpose<br/>se o schema exigir"]
  E --> H
  F --> H
  G --> H
  H --> I["POST /v2/foreign-exchange<br/>para um fxId cotado"]
  I --> J["POST /v2/payment"]

Estrutura da Requisição

Objeto Raiz

Cote uma taxa de câmbio e envie o fxId dela em todo push. É ele que vincula o pagamento à taxa que você cotou; sem ele o gateway precifica a conversão por conta própria e o destinatário pode receber um valor diferente do que você mostrou ao seu usuário. O mesmo vale para o PULLPUSH.

Não existe campo capture num push. Captura e pré-autorização são conceitos do lado pull; um push não tem autorização a segurar.

amount / recipientAmount

O amount é o lado de origem, o recipientAmount o de destino. A moeda de destino é fixa por país — cada schema de país trava o recipientAmount.currency num enum, então BRA aceita apenas BRL e DEU apenas EUR. A única exceção é a Guiné (GIN), que aceita GNF ou XOF.

Objeto sender

Objeto sender.address

O schema genérico de push exige o objeto address mas não marca nenhum campo dentro dele como obrigatório. Vários países de destino sobrescrevem isso e exigem countryCode, city e line1:

BGD, CHL, CHN, CIV, GIN, IDN, KEN, LKA, MDG, MLI, MYS, NGA, PAK, PHL, SGP, TUR

A Coreia do Sul (KOR) é a exceção no formato: ela adiciona sender.birthDate e sender.birthCountryCode — ambos validados por pattern — em vez de apertar o endereço. A China (CHN) aceita um sender.birthDate opcional além da regra de endereço.

Preencher countryCode, city e line1 em todo push é o padrão mais seguro. Não custam nada nos corredores que não os exigem, e são justamente o que a lista acima vai continuar crescendo para abranger.

Objeto recipient

O schema do país é a autoridade em toda linha "Varia" acima.

Array recipient.documents

Cada entrada:

O campo se chama document, não value. Tipos aceitos por país:

additionalData

O paymentPurpose é sempre obrigatório em CAN, CHN, COL, EGY, GMB, IDN, IND, KOR, MYS, NPL, PAK, SGP, THA, VNM, e obrigatório em BANK_DEPOSIT para BGD e PHL. Leia os códigos aceitos direto do schema do país — não são uma lista compartilhada, e um código válido na Tailândia não vale na Malásia.

Vários corredores exigem o objeto additionalData presente mesmo sem nada dentro. O schema pede a chave mas não obriga propriedade alguma, então um payload sem "additionalData": {} é rejeitado com VE_001 — additionalData can't be empty enquanto um objeto vazio passa. A Cobertura por país marca esses casos.

Câmbio (FX)

Para pushes entre moedas, busque uma taxa antes de enviar e passe o fxId retornado — o gateway então aplica a taxa vinculada àquela cotação.

As taxas diferem por método de pagamento, então cote para o método pelo qual você vai pagar. Veja Foreign Exchange para os schemas completos de requisição/resposta.

Exemplo rápido:

curl -X POST https://{FQDN}/v2/foreign-exchange \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceCurrencyCode": "USD",
    "destinationCurrencyCode": "BRL",
    "paymentMethod": "BANK_ACCOUNT"
  }'

{
  "fxId": "b2c3d4e5-...",
  "conversionRate": 4.975,
  "sourceCurrencyCode": "USD",
  "destinationCurrencyCode": "BRL",
  "paymentMethod": "BANK_ACCOUNT",
  "quoteIdExpiryDateTime": "2025-03-31T15:30:00Z"
}

Nota: cotações de câmbio têm validade limitada. Verifique o quoteIdExpiryDateTime e renove se expirou.

Resposta

Um push é aceito de forma assíncrona. Um 200 com status: "PENDING" significa que o gateway recebeu o pagamento, não que o destinatário foi pago:

{
  "paymentId": "bda24392-cac5-4fcf-af80-4a29df3ba0ff",
  "parentPaymentId": "bda24392-cac5-4fcf-af80-4a29df3ba0ff",
  "externalPaymentId": "push-bgd-001",
  "amount": 20.0,
  "created": "2026-07-15 21:29:50",
  "status": "PENDING",
  "approved": false,
  "captured": false,
  "voided": false,
  "responseCode": "01",
  "automaticReversed": false
}

Consulte GET /v2/payment/{externalId} ou aguarde o webhook para o desfecho liquidado. Não trate approved: false num push PENDING como recusa — isso apenas reflete que nenhuma autorização foi aprovada ainda, que é o estado normal de um push em trânsito.

Próximos passos

• Métodos de payout — Referência de campos para BANK_DEPOSIT, WALLET, PIX e CARD
• Cobertura por país — Todos os corredores e o que cada um exige
• Exemplos — Corpos de requisição completos, por região
• Erros — PAY_001 e PAY_271