Pruebas en Sandbox

El sandbox le permite llevar una transacción a través de todo su ciclo de vida sin movimiento real de dinero. Dos herramientas lo hacen posible: datos de prueba que activan comportamientos de cumplimiento específicos, y un endpoint de forzado de eventos que simula los callbacks externos (webhooks del gateway, notificaciones de la red de payout) que normalmente hacen avanzar una transacción.

Forzar transiciones de estado

Endpoint: POST /organizations/{tenant}/fx/transactions/{transactionId}/events
Autenticación: Nivel de agente
Disponibilidad: Solo sandbox/staging — este endpoint no existe en producción.

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/fx/transactions/$TRANSACTION_ID/events \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "event": "payment_authorized",
  "message": "Optional description"
}'

Eventos disponibles

Si la transacción no está en un estado válido para el evento, el endpoint devuelve un error explicando el estado actual.

Flujo de prueba típico (Tarjeta + 3DS)

1. Cree la transacción → estado WaitingChallenge3ds, paymentStatus: ActionRequired
2. Fuerce el 3DS: { "event": "payment_authorized" }
3. La transacción progresa automáticamente → PayoutAccepted → ManualReview → ReviewApproved → PaymentCaptured → WaitingPayout
4. Fuerce la entrega: { "event": "payout_paid" }
5. La transacción llega a Completed

Flujo de prueba típico (ACH)

1. Cree la transacción → progresa a WaitingSettlement
2. Fuerce la liquidación: { "event": "ach_settled" }
3. La transacción progresa automáticamente → PaymentSettled → PaymentCaptured → WaitingPayout
4. Fuerce la entrega: { "event": "payout_paid" }
5. La transacción llega a Completed

Escenarios de prueba de cumplimiento

Ciertos valores en los datos del remitente activan comportamientos de cumplimiento específicos en el sandbox:

Retención en la red de payout

Use el nombre de remitente JULIO SOLANO para activar una retención de cumplimiento en la red de payout:

{ "firstName": "JULIO", "lastName": "SOLANO", "...": "..." }

La transacción llega a PayoutHold después de la integración del payout. Libérela con el evento forzado hold_released (o la libera la red/backoffice).

Flujo esperado:

... → ProcessingPayout → PayoutHold → [hold released] → PayoutReleased → ...

Rechazo en la red de payout (datos del receptor faltantes)

Use el código postal 96738 en la dirección de facturación del remitente para activar una falla de validación de datos del receptor en la red de payout:

{ "address": { "zipcode": "96738", "...": "..." } }

El rechazo depende de que falten datos del beneficiario (país, ciudad, estado). Si el destinatario tiene datos de dirección completos, la transacción se acepta sin importar el código postal.

Rechazo del pago

Use un token de tarjeta que el sandbox del gateway rechace, o un token vencido. La transacción llega a PaymentDeclined → Cancelled.

Rechazo de 3DS

Cuando sea redirigido a la página de desafío 3DS, elija "Decline" (donde el sandbox lo ofrezca). El gateway reporta la falla y la transacción pasa a PaymentDeclined → Cancelled.

Tarjetas de prueba

Use tarjetas de prueba del sandbox para simular escenarios de 3DS. La lista completa está en tarjetas de prueba del Payments Gateway. Las más comunes:

Tokenícelas mediante el SDK del gateway, luego pase el token como paymentMethod.token al crear una cuenta de fondeo.

Consulta de estado por polling

Después de crear una transacción, consulte GET /organizations/{tenant}/fx/transactions/{transactionId} y observe:

Para el rastro de auditoría completo de transiciones, use GET /fx/transactions/{transactionId}/status — vea Transacción. En producción, prefiera los webhooks en lugar del polling.