Gestión de Billeteras

Esta página cubre las operaciones del ciclo de vida de las billeteras: crear billeteras, obtener detalles de billeteras, consultar saldos y obtener el historial de transacciones.

Crear una Billetera

Endpoint

POST https://{FQDN}/wallets

Headers:

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

Solicitud

Campo	Tipo	Requerido	Descripción
`accountAsset`	string	Sí	Código de moneda o activo de la billetera (p. ej., `"USD"`, `"BRL"`)
`ownerId`	string	Sí	Identificador del propietario de la billetera
`beneficiaryId`	string	Sí	Identificador del beneficiario
`type`	string	Sí	Tipo de billetera (p. ej., `"PERSONAL"`, `"BUSINESS"`)
`additionalInfo`	object	No	Metadatos arbitrarios para adjuntar a la billetera

Ejemplo de Solicitud

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"
  }'

Respuesta (200)

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

Obtener Detalles de la Billetera

Endpoint

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

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
`walletId`	string	Sí	El identificador de la billetera

Ejemplo de Solicitud

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

Respuesta (200)

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

Obtener el Saldo de la Billetera

Endpoint

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

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
`walletId`	string	Sí	El identificador de la billetera

Ejemplo de Solicitud

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

Respuesta (200)

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

Campo	Tipo	Descripción
`availableBalance`	number	Fondos disponibles para transacciones
`heldBalance`	number	Fondos reservados por retenciones (holds) pendientes
`totalBalance`	number	Suma de los saldos disponible y retenido

Obtener el Estado de Cuenta de la Billetera

Obtenga un historial de transacciones paginado de una billetera, con filtrado opcional por rango de fechas.

Endpoint

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

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
`walletId`	string	Sí	El identificador de la billetera

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
`from`	string	No	Fecha de inicio (ISO 8601, p. ej., `"2025-03-01"`)
`until`	string	No	Fecha de fin (ISO 8601, p. ej., `"2025-03-31"`)
`page`	integer	No	Número de página (basado en cero)
`size`	integer	No	Resultados por página

Ejemplo de Solicitud

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...'

Respuesta (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
}

Qué Sigue

Transacciones y transferencias — Ejecute transacciones de billetera, retenciones (holds) y transferencias entre billeteras
Saldo — Consulte el saldo del pagador en todos los proveedores