Enviar um pagamento Pix

Enviar um Pix é um fluxo de etapas separadas. Você cria o pagamento, o que identifica quem você está pagando e o valor; define os detalhes, se faltar algum; e então o confirma — só aí o dinheiro é movimentado. Se as políticas de negócio da sua organização exigirem aprovação para o pagamento, você o envia para aprovação em vez de confirmá-lo — veja Políticas de negócio e aprovações.

Fluxo

Etapa 1: Criar o pagamento

Identifique o destinatário por uma chave Pix, um Pix Copia e Cola / QR Code ou pelos dados bancários do destinatário.

Por chave Pix
Por QR Code
Por dados bancários

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiationType": "DICT",
    "dict": "CNPJ",
    "key": "12345678000195",
    "amount": 123000,
    "category": "FLEX_INTERNATIONAL",
    "description": "Order 4821"
  }'

Campo	Observações
`initiationType`	`DICT` para uma chave.
`dict`	Tipo de chave: `PHONE`, `EMAIL`, `CPF`, `CNPJ` ou `EVP` (aleatória).
`key`	A chave. Telefone como `+55XXXXXXXXXXX`; e-mail em minúsculas; CPF com 11 dígitos; CNPJ com 14 caracteres, sem formatação e em maiúsculas — conforme a NT 49/2024 da Receita Federal, o CNPJ pode conter letras `A–Z` nas 12 primeiras posições (apenas os 2 dígitos verificadores finais permanecem numéricos).
`amount`	Em centavos. Obrigatório.
`category`	A categoria de saldo da carteira a debitar. Com ela, você pode confirmar logo depois de criar.
`description`	Vai para o destinatário junto com o pagamento.

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiationType": "COPY_PASTE",
    "emv": "00020101021226870014br.gov.bcb.pix2565...6304ABCD"
  }'

Envie o código Pix Copia e Cola, ou o código lido do QR Code, em emv — com COPY_PASTE, ou com DYNAMIC_QRCODE / STATIC_QRCODE / UNDEFINED_QRCODE quando você lê um QR Code. O valor vem do próprio QR Code: leia-o em txnUpdatedAmount. Quando o QR Code deixa o pagador escolher o valor (txnAllowAmountChange: true), ele é 0 e você o define na etapa 2.

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiationType": "FULL_BANK_DETAILS",
    "credit_party": {
      "name": "Gráfica Aurora Ltda",
      "document": "12345678000195",
      "bank_ispb": "60746948",
      "branch": "0001",
      "accountNumber": "123456",
      "accountType": "CACC"
    },
    "amount": 123000,
    "category": "FLEX_INTERNATIONAL"
  }'

accountType é CACC (conta corrente), SLRY (conta salário), SVGS (poupança) ou TRAN (conta de pagamento).

O pagamento é criado como REQUESTED — nada é pago ainda. Revise quem você está pagando (creditParty) e quanto (txnUpdatedAmount) antes de continuar:

{
  "_id": "6726a4f1b4d3e80012c9a3f1",
  "status": "REQUESTED",
  "initiationType": "DICT",
  "txnUpdatedAmount": 123000,
  "creditParty": { "name": "Gráfica Aurora Ltda", "document": "12345678000195", "bankIspb": "60746948", "key": "12345678000195", "keyType": "CNPJ" },
  "receipt": { "endToEndId": "E12345678202611021312k7Q2mX9pL4w" },
  "pendingConfirmation": { "amount": 123000, "category": "FLEX_INTERNATIONAL", "description": "Order 4821" },
  "policy": { "actions": { "autoAction": "APPROVE" } }
}

Guarde o _id do pagamento — ele é o {pixId} de todas as próximas etapas. pendingConfirmation guarda o que será pago, e policy, o que as políticas de negócio da sua organização dizem sobre ele. Referência: Criar um pagamento Pix

Etapa 2: Definir os detalhes, se faltar algum

A confirmação paga exatamente o que está em pendingConfirmation, então exige o valor e a categoria de saldo. Se você enviou os dois na criação, pule esta etapa. Caso contrário — um QR Code, ou uma criação sem category —, defina-os:

curl -X PUT \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 123000,
    "category": "FLEX_INTERNATIONAL"
  }'

A menos que o QR Code tenha valor aberto, amount deve ser o txnUpdatedAmount do pagamento (uma cobrança COBV agendada para o vencimento também pode pagar o seu txnOriginalAmount). A resposta traz uma policy atualizada. Referência: Definir os detalhes de um pagamento Pix

Etapa 3: Confirmar o pagamento

Quando policy.actions.autoAction for APPROVE, confirme o pagamento — sem corpo:

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}/confirm' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

Uma confirmação bem-sucedida responde 200 com o pagamento CONFIRMED; ele passa a PAID quando a rede Pix o liquida, e receipt.endToEndId é o ID que o banco do destinatário exibe. Se o pagamento for recusado — por saldo insuficiente ou por um limite, por exemplo —, ele passa a FAILED, com o motivo em failReason, e você recebe o erro. Quando autoAction for NONE, o pagamento precisa de aprovação: envie-o para aprovação em vez de confirmá-lo. Com DENY, as políticas o recusam. Referência: Confirmar um pagamento Pix

Pagar em um dia futuro

Envie scheduledAt (YYYY-MM-DD) ao criar o pagamento, ou com PUT, para pagar em um dia futuro. A confirmação então responde 201 com o agendamento, e o pagamento passa a SCHEDULED; nesse dia, um novo pagamento é criado e pago. O pagamento do dia não leva os campos personalizados: numa organização com um campo personalizado de transação obrigatório, ele falha. Uma cobrança por QR Code com vencimento só pode ser paga hoje ou na data de vencimento, e só pagamentos por chave Pix ou QR Code podem ser agendados — um pagamento por dados bancários para um dia futuro é recusado na confirmação.

Cancelar um pagamento

Um pagamento que ainda não foi pago — REQUESTED, aguardando aprovação ou SCHEDULED — pode ser cancelado:

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}/cancel' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

Próximos passos

Políticas de negócio e aprovações

Envie pagamentos para aprovação quando as políticas da sua organização exigirem.

Cobrar com PIX

Gere um QR Code para receber dinheiro em vez de enviar.

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Enviar um pagamento Pix

Fluxo

Etapa 1: Criar o pagamento

Etapa 2: Definir os detalhes, se faltar algum

Etapa 3: Confirmar o pagamento

Pagar em um dia futuro

Cancelar um pagamento

Próximos passos

Políticas de negócio e aprovações

Cobrar com PIX

​Fluxo

​Etapa 1: Criar o pagamento

​Etapa 2: Definir os detalhes, se faltar algum

​Etapa 3: Confirmar o pagamento

​Pagar em um dia futuro

​Cancelar um pagamento

​Próximos passos

Políticas de negócio e aprovações

Cobrar com PIX

Fluxo

Etapa 1: Criar o pagamento

Etapa 2: Definir os detalhes, se faltar algum

Etapa 3: Confirmar o pagamento

Pagar em um dia futuro

Cancelar um pagamento

Próximos passos