Gestão de Carteiras

Esta página cobre as operações do ciclo de vida da carteira: criação de carteiras, recuperação de detalhes, consulta de saldos e busca do histórico de transações.

Criar uma Carteira

Endpoint

POST https://{FQDN}/wallets

Headers:

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

Requisição

Campo	Tipo	Obrigatório	Descrição
`accountAsset`	string	Sim	Código de moeda ou ativo da carteira (ex.: `"USD"`, `"BRL"`)
`ownerId`	string	Sim	Identificador do titular da carteira
`beneficiaryId`	string	Sim	Identificador do beneficiário
`type`	string	Sim	Tipo de carteira (ex.: `"PERSONAL"`, `"BUSINESS"`)
`additionalInfo`	object	Não	Metadados arbitrários a anexar à carteira

Exemplo de Requisição

curl -X POST https://{FQDN}/wallets \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountAsset": "USD",
    "ownerId": "user-12345",
    "beneficiaryId": "user-12345",
    "type": "PERSONAL"
  }'

Resposta (200)

{
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "accountAsset": "USD",
  "ownerId": "user-12345",
  "beneficiaryId": "user-12345",
  "type": "PERSONAL",
  "status": "ACTIVE",
  "createdAt": "2025-03-31T10:00:00Z"
}

Obter Detalhes da Carteira

Endpoint

GET https://{FQDN}/wallets/{walletId}

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
`walletId`	string	Sim	O identificador da carteira

Exemplo de Requisição

curl -X GET https://{FQDN}/wallets/w-a1b2c3d4-e5f6-7890 \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Resposta (200)

{
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "accountAsset": "USD",
  "ownerId": "user-12345",
  "beneficiaryId": "user-12345",
  "type": "PERSONAL",
  "status": "ACTIVE",
  "createdAt": "2025-03-31T10:00:00Z"
}

Obter o Saldo da Carteira

Endpoint

GET https://{FQDN}/wallets/{walletId}/balance

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
`walletId`	string	Sim	O identificador da carteira

Exemplo de Requisição

curl -X GET https://{FQDN}/wallets/w-a1b2c3d4-e5f6-7890/balance \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Resposta (200)

{
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "accountAsset": "USD",
  "availableBalance": 1250.75,
  "heldBalance": 200.00,
  "totalBalance": 1450.75
}

Campo	Tipo	Descrição
`availableBalance`	number	Fundos disponíveis para transações
`heldBalance`	number	Fundos reservados por retenções (holds) pendentes
`totalBalance`	number	Soma dos saldos disponível e retido

Obter o Extrato da Carteira

Recupere um histórico de transações paginado de uma carteira, com filtro opcional por intervalo de datas.

Endpoint

GET https://{FQDN}/wallets/{walletId}/statement

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
`walletId`	string	Sim	O identificador da carteira

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
`from`	string	Não	Data inicial (ISO 8601, ex.: `"2025-03-01"`)
`until`	string	Não	Data final (ISO 8601, ex.: `"2025-03-31"`)
`page`	integer	Não	Número da página (a partir de zero)
`size`	integer	Não	Resultados por página

Exemplo de Requisição

curl -X GET 'https://{FQDN}/wallets/w-a1b2c3d4-e5f6-7890/statement?from=2025-03-01&until=2025-03-31&page=0&size=20' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Resposta (200)

{
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "entries": [
    {
      "transactionId": "txn-001",
      "externalId": "order-5001",
      "type": "CREDIT",
      "amount": 500.00,
      "description": "Wallet top-up",
      "balanceAfter": 1450.75,
      "createdAt": "2025-03-15T14:30:00Z"
    },
    {
      "transactionId": "txn-002",
      "externalId": "order-5002",
      "type": "DEBIT",
      "amount": 49.25,
      "description": "Payment to merchant",
      "balanceAfter": 1401.50,
      "createdAt": "2025-03-16T09:15:00Z"
    }
  ],
  "page": 0,
  "size": 20,
  "totalEntries": 2
}

O Que Vem a Seguir

Transações e transferências — Execute transações de carteira, retenções (holds) e transferências entre carteiras
Saldo — Consulte o saldo do pagador em todos os provedores