Guia de Transferencias

Guia completa para ejecutar transferencias en la misma moneda a traves de la API de ARi.

Descripcion General

Use la API de Transferencias para mover fondos en la misma moneda entre cuentas. Para operaciones de cambio de divisas, consulte la Guia de Ordenes FX.

Tipo de Operacion	Caso de Uso	Endpoint API
Transferencias	Mover misma moneda entre cuentas	`/api/v1/transfer`

Inicio Rapido

Requisitos Previos

Antes de ejecutar cualquier transferencia, asegurese de tener:

Credenciales API - Obtenga su clave de suscripcion desde el Portal de Desarrolladores
Wallet con Fondos - Asegurese de que su wallet de origen tenga saldo suficiente
IBANs de Cuenta - Numeros de cuenta de origen y destino

Flujos de Transferencia Soportados

ARi soporta los siguientes escenarios de transferencia en la misma moneda:

Flujo	Origen	Destino	Rail
Deposito	IBAN Externo	Wallet ARi	`sinpe`
Retiro	Wallet ARi	IBAN Externo	`sinpe`
Interno	Wallet ARi	Wallet ARi	`internal`

+---------------------------------------------------------------+
|                FLUJOS DE TRANSFERENCIA SOPORTADOS             |
+---------------------------------------------------------------+

        Flujo 1: DEPOSITO (Externo → Wallet ARi)
        ┌──────────────────┐           ┌──────────────────┐
        │   IBAN Externo   │ ───────>  │   Wallet ARi     │
        │ (Cliente fondea) │   sinpe   │    (Recibe)      │
        └──────────────────┘           └──────────────────┘

        Flujo 2: RETIRO (Wallet ARi → Externo)
        ┌──────────────────┐           ┌──────────────────┐
        │   Wallet ARi     │ ───────>  │   IBAN Externo   │
        │  (Prefinanciado) │   sinpe   │    (Recibe)      │
        └──────────────────┘           └──────────────────┘

        Flujo 3: INTERNO (Wallet ARi → Wallet ARi)
        ┌──────────────────┐           ┌──────────────────┐
        │   Wallet ARi     │ ───────>  │   Wallet ARi     │
        │  (Prefinanciado) │  internal │    (Recibe)      │
        └──────────────────┘           └──────────────────┘

        NO SOPORTADO: Externo → Externo (misma moneda)
        ┌──────────────────┐           ┌──────────────────┐
        │   IBAN Externo   │ ────X───  │   IBAN Externo   │
        │                  │           │                  │
        └──────────────────┘           └──────────────────┘

+---------------------------------------------------------------+

Escenario 1: Deposito (Externo a Wallet ARi)

Fondee un wallet ARi desde una cuenta bancaria externa.

Ejecutar Deposito

+----------------------+
| TRANSFERENCIA DEPOS. |
+----------------------+
          |
          v
+------------------------------------------+
| POST /api/v1/transfer/createTransfer     |
| Headers:                                 |
|   Idempotency-Key: unique-request-id     |
|                                          |
| Body: {                                  |
|   "origin": {                            |
|     "iban": "CR27015100019876543210", |
|     "iban_holder": "Mario Herrera"       |
|   },                                     |
|   "destination": {                       |
|     "iban": "CR27409819882707497149"  |
|   },                                     |
|   "parameters": {                        |
|     "amount": "100000",                  |
|     "rail": "sinpe",                     |
|     "origin_currency": "CRC",            |
|     "destination_currency": "CRC",           |
|     "description": "Fondeo de wallet"    |
|   }                                      |
| }                                        |
+------------------------------------------+
          |
          v
+------------------------------------------+
| Respuesta (Aceptado - Asincrono):        |
| {                                        |
|   "reference_code": "TRF-20260203-001",  |
|   "status": "PENDING_APPROVAL"           |
| }                                        |
+------------------------------------------+

Escenario 2: Retiro (Wallet ARi a Externo)

Envie fondos desde un wallet ARi a una cuenta bancaria externa via SINPE.

Ejecutar Retiro

+----------------------+
| TRANSFERENCIA RETIRO |
+----------------------+
          |
          v
+------------------------------------------+
| POST /api/v1/transfer/createTransfer     |
| Headers:                                 |
|   Idempotency-Key: unique-request-id     |
|                                          |
| Body: {                                  |
|   "origin": {                            |
|     "iban": "CR27409819882707497149"  |
|   },                                     |
|   "destination": {                       |
|     "iban": "CR27015100019876543210", |
|     "iban_holder": "Mario Herrera"       |
|   },                                     |
|   "parameters": {                        |
|     "amount": "50000",                   |
|     "rail": "sinpe",                     |
|     "origin_currency": "CRC",            |
|     "destination_currency": "CRC",           |
|     "description": "Pago por servicios" |
|   }                                      |
| }                                        |
+------------------------------------------+
          |
          v
+------------------------------------------+
| Respuesta (Aceptado - Asincrono):        |
| {                                        |
|   "reference_code": "TRF-20260203-002",  |
|   "status": "PENDING_APPROVAL"           |
| }                                        |
+------------------------------------------+

Escenario 3: Transferencia Interna (Wallet ARi a Wallet ARi)

Mueva fondos entre wallets ARi en la misma moneda.

Ejecutar Transferencia Interna

+----------------------+
| TRANSFERENCIA INTERNA|
+----------------------+
          |
          v
+------------------------------------------+
| POST /api/v1/transfer/createTransfer     |
| Headers:                                 |
|   Idempotency-Key: unique-request-id     |
|                                          |
| Body: {                                  |
|   "origin": {                            |
|     "iban": "CR27409819882707497149"  |
|   },                                     |
|   "destination": {                       |
|     "iban": "CR11409860774530115159"  |
|   },                                     |
|   "parameters": {                        |
|     "amount": "25000",                   |
|     "rail": "internal",                  |
|     "origin_currency": "CRC",            |
|     "destination_currency": "CRC",           |
|     "description": "Transferencia int."  |
|   }                                      |
| }                                        |
+------------------------------------------+
          |
          v
+------------------------------------------+
| Respuesta (Aceptado - Asincrono):        |
| {                                        |
|   "reference_code": "TRF-20260203-003",  |
|   "status": "PENDING_APPROVAL"           |
| }                                        |
+------------------------------------------+

Consultar Estado de Transferencia

Todas las transferencias se procesan de forma asincrona. Consulte actualizaciones de estado:

+------------------------------------------+
| POST /api/v1/transfer/getStatus          |
| Body: {                                  |
|   "reference_code": "TRF-20260203-001"   |
| }                                        |
+------------------------------------------+
          |
          v
+------------------------------------------+
| Respuesta:                               |
| {                                        |
|   "reference_code": "TRF-20260203-001",  |
|   "status": "COMPLETED"                  |
| }                                        |
+------------------------------------------+

Linea de Tiempo de Estado de Transferencia

+----------------------------------------------------------------+
|                  FLUJO DE ESTADO DE TRANSFERENCIA               |
+----------------------------------------------------------------+

      PENDING_APPROVAL ──────> PROCESSING ──────> COMPLETED
                                    |
                                    └───────────> FAILED

      Flujo tipico:
      1. PENDING_APPROVAL - Orden recibida, esperando procesamiento
      2. PROCESSING       - Transferencia en progreso con red bancaria
      3. COMPLETED        - Entregada exitosamente al destino

      Alternativa:
      3. FAILED           - Transferencia no pudo completarse

+----------------------------------------------------------------+

Headers Requeridos

Header	Requerido	Descripcion
`Ocp-Apim-Subscription-Key`	Si	Su clave de suscripcion API
`Idempotency-Key`	Si	ID unico para prevenir transferencias duplicadas
`Content-Type`	Si	`application/json`

Sobre las Claves de Idempotencia

El header Idempotency-Key previene transferencias duplicadas. Si reintenta una solicitud con la misma clave, recibira la respuesta original en lugar de crear un duplicado.

Mejores practicas:
- Use UUID v4 para cada transferencia unica
- Guarde la clave hasta recibir una respuesta final
- Reintente con la MISMA clave si ocurren problemas de red

Referencia de Rails

Rail	Descripcion	Caso de Uso
`sinpe`	Deposito SINPE	IBAN Externo → Wallet ARi
`sinpe`	Red SINPE	Wallet ARi → IBAN Externo
`internal`	Transferencia interna	Wallet ARi → Wallet ARi

Flujo de Decision: Cual API Usar?

+---------------------------------------------------------------+
|                   CUAL API DEBO USAR?                         |
+---------------------------------------------------------------+

                               Inicio
                                 |
                                 v
                  +-----------------------------+
                  | Son las monedas de origen   |
                  |    y destino iguales?       |
                  +-----------------------------+
                         |             |
                        SI            NO
                         |             |
                         v             v
                  +------------+  +------------+
                  |    Usar    |  |    Usar    |
                  |  /transfer |  |  /fxorder  |
                  +------------+  +------------+
                         |
                         v
                  +-----------------------------+
                  |   Que tipo de transferencia?|
                  +-----------------------------+
                     |         |         |
                     v         v         v
              +-----------+-----------+-----------+
              |  Externo  |   Wallet  |   Wallet  |
              |     a     |    ARi    |    ARi    |
              |   Wallet  |     a     |     a     |
              |    ARi    |  Externo  |   Wallet  |
              +-----------+-----------+-----------+
                     |         |         |
                     v         v         v
              +-----------+-----------+-----------+
              |   rail:   |   rail:   |   rail:   |
              |   sinpe   |   sinpe   |  internal |
              +-----------+-----------+-----------+

+---------------------------------------------------------------+
| IMPORTANTE: Externo → Externo misma moneda NO esta soportado  |
+---------------------------------------------------------------+

Restricciones

Escenario	Soportado	Alternativa
Externo → Wallet ARi	Si	Use `rail: sinpe`
Wallet ARi → Externo	Si	Use `rail: sinpe`
Wallet ARi → Wallet ARi	Si	Use `rail: internal`
Externo → Externo	No	Deposite primero, luego retire

Manejo de Errores

Errores Comunes

Error	Causa	Solucion
`Insufficient balance`	Wallet origen sin fondos suficientes	Financiar el wallet primero
`Different currencies`	Transferencia con monedas diferentes	Use `/fxorder` en su lugar
`Invalid rail`	Rail incorrecto para tipos de cuenta	Consulte Referencia de Rails
`External to external not allowed`	Transferencia externa misma moneda	Deposite a wallet ARi primero

Formato de Respuesta de Error

Todos los errores siguen RFC 7807 Problem Details:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Transferencias externas a externas en misma moneda no estan soportadas",
  "trace_id": "0HN4G6LJN5FT0:00000001"
}

Consejo: Guarde el trace_id al contactar soporte.

Ejemplos de Codigo

cURL: Retiro SINPE

curl -X POST "https://api.ariari.xyz/api/v1/transfer/createTransfer" \
  -H "Ocp-Apim-Subscription-Key: YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "iban": "CR27409819882707497149" },
    "destination": {
      "iban": "CR27015100019876543210",
      "iban_holder": "Mario Herrera"
    },
    "parameters": {
      "amount": "50000",
      "rail": "sinpe",
      "origin_currency": "CRC",
      "destination_currency": "CRC",
      "description": "Pago"
    }
  }'

cURL: Consultar Estado de Transferencia

curl -X POST "https://api.ariari.xyz/api/v1/transfer/getStatus" \
  -H "Ocp-Apim-Subscription-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_code": "TRF-20260203-001"
  }'

Mejores Practicas

Siempre use claves de idempotencia para prevenir transferencias duplicadas
Consulte el estado en transferencias asincronas (o use webhooks)
Valide formatos de cuenta antes de enviar
Verifique requisitos de rail segun tipos de cuenta origen/destino
Maneje externo-a-externo usando proceso de dos pasos (depositar y luego retirar)

Limites de Tasa

Nivel	Solicitudes por Minuto
Estandar	60
Premium	120
Empresarial	Personalizado

Siguientes Pasos

Obtener Claves API - Comience a construir hoy
Ordenes FX - Operaciones de cambio de divisas
Webhooks - Reciba notificaciones en tiempo real
Referencia API - Documentacion completa de endpoints