Pull e Push em uma Única Etapa

O tipo de pagamento PULLPUSH combina a coleta e o desembolso de fundos em uma única chamada de API. Os fundos são debitados do cartão ou da conta bancária do remetente e, simultaneamente, enviados ao destino do destinatário.

Isso reduz a latência e simplifica fluxos em que os fundos precisam se mover entre duas partes em uma única transação.

Endpoint

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

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Estrutura da Requisição

Objeto Raiz

Campo	Tipo	Obrigatório	Descrição
`externalPaymentId`	string	Sim	Seu identificador único do pagamento
`ipAddress`	string	Sim	Endereço IPv4 ou IPv6 do originador
`paymentType`	string	Sim	`"PULLPUSH"`
`amount`	object	Sim	Valor do pull (lado do remetente, em USD)
`recipientAmount`	object	Sim	Valor do push (lado do destinatário, qualquer moeda)
`exchangeRate`	number	Sim	Taxa de câmbio entre as moedas de origem e destino
`sender`	object	Sim	Dados do remetente e origem do pagamento
`recipient`	object	Sim	Dados do destinatário e destino do payout

Sender

A estrutura do sender é idêntica à de um pagamento Pull — inclui customer, customerAddress e source:

`sender.source` — Cartão

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"CARD"`
`card.token`	string	Sim	UUID do token do cartão gerado pelo tokenizador

`sender.source` — Conta Bancária

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"BANK_ACCOUNT"`
`accountType`	string	Sim	`"savings"`, `"checking"`, etc.
`accountNumber`	string	Sim	Número da conta bancária
`routingNumber`	string	Sim	Número de roteamento ABA
`accountHolder`	object	Sim	`{ type, firstName, lastName }`

Recipient

A estrutura do recipient é idêntica à de um pagamento Push — inclui customer, customerAddress e destination.

Exemplo — PULLPUSH (Cartão → Carteira)

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "pullpush-001",
    "ipAddress": "203.0.113.42",
    "paymentType": "PULLPUSH",
    "amount": {
      "total": 100.00,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 497.50,
      "currency": "BRL"
    },
    "exchangeRate": 4.975,
    "sender": {
      "customer": {
        "firstName": "Lucas",
        "lastName": "Silva",
        "phoneNumber": "11999999999",
        "documentNumber": "12345678900",
        "documentType": "NATIONAL_ID",
        "email": "[email protected]",
        "countryCodeAlpha3": "USA"
      },
      "customerAddress": {
        "stateCode": "CA",
        "city": "San Francisco",
        "line1": "123 Mission St",
        "line2": "Suite 900",
        "state": "California",
        "zipCode": "94105"
      },
      "source": {
        "type": "CARD",
        "card": {
          "token": "ab5fc589-8b48-4531-94c0-68b0629c13fe"
        }
      }
    },
    "recipient": {
      "customer": {
        "firstName": "Ana",
        "lastName": "Souza",
        "phoneNumber": "21987654321",
        "documentNumber": "10987654321",
        "documentType": "PASSPORT",
        "email": "[email protected]",
        "countryCodeAlpha3": "BRA"
      },
      "customerAddress": {
        "stateCode": "RJ",
        "city": "Rio de Janeiro",
        "line1": "Rua da Alfândega 45",
        "state": "Rio de Janeiro",
        "zipCode": "20010-030"
      },
      "destination": {
        "type": "WALLET",
        "wallet": {
          "walletId": "[email protected]"
        }
      }
    }
  }'

Exemplo — PULLPUSH (Conta Bancária → PIX)

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "pullpush-002",
    "ipAddress": "203.0.113.42",
    "paymentType": "PULLPUSH",
    "amount": {
      "total": 200.00,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 995.00,
      "currency": "BRL"
    },
    "exchangeRate": 4.975,
    "sender": {
      "customer": {
        "firstName": "Maria",
        "lastName": "Johnson",
        "phoneNumber": "5551234567",
        "documentNumber": "987654321",
        "documentType": "DRIVER_LICENSE",
        "email": "[email protected]",
        "countryCodeAlpha3": "USA"
      },
      "customerAddress": {
        "stateCode": "TX",
        "city": "Austin",
        "line1": "789 Congress Ave",
        "state": "Texas",
        "zipCode": "78701"
      },
      "source": {
        "type": "BANK_ACCOUNT",
        "accountType": "checking",
        "accountNumber": "123456789",
        "routingNumber": "021000021",
        "accountHolder": {
          "type": "personal",
          "firstName": "Maria",
          "lastName": "Johnson"
        }
      }
    },
    "recipient": {
      "customer": {
        "firstName": "Pedro",
        "lastName": "Santos",
        "phoneNumber": "11987654321",
        "documentNumber": "98765432100",
        "documentType": "NATIONAL_ID",
        "email": "[email protected]",
        "countryCodeAlpha3": "BRA"
      },
      "customerAddress": {
        "stateCode": "SP",
        "city": "São Paulo",
        "line1": "Av Paulista 1000",
        "state": "São Paulo",
        "zipCode": "01311-100"
      },
      "destination": {
        "type": "PIX",
        "pix": {
          "keyType": "EMAIL",
          "key": "[email protected]"
        }
      }
    }
  }'

Principais Diferenças em Relação a Pull + Push Separados

Aspecto	Chamadas separadas	PULLPUSH
Chamadas de API	2 (um pull, um push)	1
Atomicidade	Independentes — o push pode falhar após o pull ter sucesso	Transação única
Taxa de câmbio	Deve ser gerenciada separadamente	Especificada na mesma requisição
Caso de uso	Fluxos complexos com lógica intermediária	Remessa direta de ponta a ponta