Transacciones y Transferencias

Esta página cubre las operaciones de transacciones de billetera: crear transacciones (con retenciones opcionales), confirmar transacciones retenidas, transferir entre billeteras y anular (void) transferencias.

Crear una Transacción

Cree una transacción de débito o crédito contra una billetera. Opcionalmente, coloque una retención (hold) para reservar fondos sin finalizar.

Endpoint

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

Headers:

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

Solicitud

Campo	Tipo	Requerido	Descripción
`walletId`	string	Sí	Identificador de la billetera destino
`externalId`	string	Sí	Su identificador único de transacción (clave de idempotencia)
`amount`	number	Sí	Monto de la transacción
`paymentType`	string	Sí	Tipo de transacción (p. ej., `"DEBIT"`, `"CREDIT"`)
`description`	string	No	Descripción legible para humanos
`hold`	boolean	No	Establezca `true` para reservar fondos sin finalizar (predeterminado `false`). La transacción debe confirmarse por separado mediante `POST /wallets/transaction/{transactionId}/confirm`

Ejemplo — Transacción Inmediata

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

Ejemplo — Transacción con Retención (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
  }'

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

Estado	Descripción
`COMPLETED`	Transacción finalizada de inmediato (`hold: false`)
`HELD`	Fondos reservados, en espera de confirmación (`hold: true`)

Confirmar una Transacción Retenida

Finalice una transacción retenida previamente. Una vez confirmada, los fondos retenidos se debitan o acreditan.

Endpoint

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

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
`transactionId`	string	Sí	El ID de transacción devuelto en la solicitud de retención

Ejemplo de Solicitud

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

Respuesta (200)

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

Transferir Entre Billeteras

Transfiera fondos de forma atómica de una billetera a otra. Ambas billeteras deben usar la misma moneda.

Endpoint

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

Headers:

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

Solicitud

Campo	Tipo	Requerido	Descripción
`fromWallet`	string	Sí	Identificador de la billetera origen
`toWallet`	string	Sí	Identificador de la billetera destino
`amount`	number	Sí	Monto a transferir
`description`	string	No	Descripción legible para humanos
`externalId`	string	Sí	Su identificador único de transferencia (también usado como parámetro de ruta al anular la transferencia)

Ejemplo de Solicitud

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

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

Anular (Void) una Transferencia

Revierta una transferencia completada entre billeteras. El monto completo se devuelve a la billetera origen.

Endpoint

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

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
`externalTransferId`	string	Sí	Su identificador externo de transferencia usado al crear la transferencia

Ejemplo de Solicitud

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

Respuesta (200)

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

Qué Sigue

Gestión de billeteras — Cree billeteras, consulte saldos y obtenga estados de cuenta
Saldo — Consulte el saldo del pagador en todos los proveedores
Transacción Push — Envíe payouts a destinatarios externos