Transações e Transferências

Esta página cobre as operações de transação de carteira: criação de transações (com retenções opcionais), confirmação de transações retidas, transferências entre carteiras e cancelamento (void) de transferências.

Criar uma Transação

Crie uma transação de débito ou crédito em uma carteira. Opcionalmente, aplique uma retenção (hold) para reservar fundos sem finalizar.

Endpoint

POST https://{FQDN}/wallets/transaction

Headers:

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

Requisição

Campo	Tipo	Obrigatório	Descrição
`walletId`	string	Sim	Identificador da carteira de destino
`externalId`	string	Sim	Seu identificador único de transação (chave de idempotência)
`amount`	number	Sim	Valor da transação
`paymentType`	string	Sim	Tipo de transação (ex.: `"DEBIT"`, `"CREDIT"`)
`description`	string	Não	Descrição legível
`hold`	boolean	Não	Defina como `true` para reservar fundos sem finalizar (padrão `false`). A transação deve ser confirmada separadamente via `POST /wallets/transaction/{transactionId}/confirm`

Exemplo — Transação Imediata

curl -X POST https://{FQDN}/wallets/transaction \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "walletId": "w-a1b2c3d4-e5f6-7890",
    "externalId": "txn-order-5001",
    "amount": 75.00,
    "paymentType": "DEBIT",
    "description": "Payment for order #5001",
    "hold": false
  }'

Exemplo — Transação com Retenção (Hold)

curl -X POST https://{FQDN}/wallets/transaction \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "walletId": "w-a1b2c3d4-e5f6-7890",
    "externalId": "txn-hold-001",
    "amount": 200.00,
    "paymentType": "DEBIT",
    "description": "Hold for reservation #8842",
    "hold": true
  }'

Resposta (200)

{
  "transactionId": "txn-7f8e9d0c-1a2b-3c4d",
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "externalId": "txn-hold-001",
  "amount": 200.00,
  "paymentType": "DEBIT",
  "status": "HELD",
  "description": "Hold for reservation #8842",
  "createdAt": "2025-03-31T12:00:00Z"
}

Status	Descrição
`COMPLETED`	Transação finalizada imediatamente (`hold: false`)
`HELD`	Fundos reservados, aguardando confirmação (`hold: true`)

Confirmar uma Transação Retida

Finalize uma transação previamente retida. Uma vez confirmada, os fundos retidos são debitados ou creditados.

Endpoint

POST https://{FQDN}/wallets/transaction/{transactionId}/confirm

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
`transactionId`	string	Sim	O ID da transação retornado na requisição de retenção

Exemplo de Requisição

curl -X POST https://{FQDN}/wallets/transaction/txn-7f8e9d0c-1a2b-3c4d/confirm \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Resposta (200)

{
  "transactionId": "txn-7f8e9d0c-1a2b-3c4d",
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "status": "COMPLETED",
  "amount": 200.00,
  "confirmedAt": "2025-03-31T12:05:00Z"
}

Transferir Entre Carteiras

Transfira fundos atomicamente de uma carteira para outra. Ambas as carteiras devem usar a mesma moeda.

Endpoint

POST https://{FQDN}/wallets/transfer

Headers:

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

Requisição

Campo	Tipo	Obrigatório	Descrição
`fromWallet`	string	Sim	Identificador da carteira de origem
`toWallet`	string	Sim	Identificador da carteira de destino
`amount`	number	Sim	Valor a transferir
`description`	string	Não	Descrição legível
`externalId`	string	Sim	Seu identificador único de transferência (também usado como parâmetro de path ao cancelar a transferência)

Exemplo de Requisição

curl -X POST https://{FQDN}/wallets/transfer \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "fromWallet": "w-a1b2c3d4-e5f6-7890",
    "toWallet": "w-x9y8z7w6-v5u4-3210",
    "amount": 150.00,
    "description": "Settlement transfer",
    "externalId": "xfer-001"
  }'

Resposta (200)

{
  "transferId": "xfer-5e6f7g8h-9i0j-1k2l",
  "externalTransferId": "xfer-001",
  "fromWallet": "w-a1b2c3d4-e5f6-7890",
  "toWallet": "w-x9y8z7w6-v5u4-3210",
  "amount": 150.00,
  "status": "COMPLETED",
  "createdAt": "2025-03-31T14:00:00Z"
}

Cancelar (Void) uma Transferência

Reverta uma transferência concluída entre carteiras. O valor total é devolvido à carteira de origem.

Endpoint

POST https://{FQDN}/wallets/transfer/{externalTransferId}/void

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
`externalTransferId`	string	Sim	Seu identificador externo de transferência usado na criação da transferência

Exemplo de Requisição

curl -X POST https://{FQDN}/wallets/transfer/xfer-001/void \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Resposta (200)

{
  "transferId": "xfer-5e6f7g8h-9i0j-1k2l",
  "externalTransferId": "xfer-001",
  "status": "VOIDED",
  "voidedAt": "2025-03-31T14:10:00Z"
}

O Que Vem a Seguir

Gestão de carteiras — Crie carteiras, consulte saldos e recupere extratos
Saldo — Consulte o saldo do pagador em todos os provedores
Transação Push — Envie payouts para destinatários externos