ARi LogoPortal de Desarrolladores
|
Volver a Documentacion

Transfer

Una Transfer es un movimiento de valor en una sola moneda desde un wallet ARi a un destino — ya sea otro wallet ARi (transferencia interna en libros) o un IBAN destino accesible por un rail de pago. Los dos rails soportados en M2M son SINPE (doméstico de Costa Rica, vía la integración de Prosoft) y stablecoin (rail de stablecoin). La forma en el cable está segregada por audiencia según ADR-0048: los socios envían M2mCreateTransferDto, y los identificadores internos de correlación (por ejemplo, los identificadores minoristas de MFA / SCA usados en flujos de aplicación al cliente final) se retiran antes de que el documento llegue al SDK del socio.

Las transferencias son la contraparte accesible para socios de createOrder: mientras una orden FX combina una conversión de moneda con una liquidación, una transferencia mueve un saldo ya convertido a su destino final.
Endpoint que la crea POST /api/v1/transfers/createTransfer
Esquema en el cable (request) M2mCreateTransferDto — compuesto por M2mTransferOriginDto, M2mTransferDestinationDto, M2mTransferParametersDto
Ciclo de vida PENDING → ACCEPTED → SETTLED (o REJECTED/CANCELED en rutas de falla)
Webhooks Sí — vea eventos SSE para las transiciones de estado

Garantías del objeto

  • origin.iban debe ser un IBAN de wallet ARi (código de banco 0589). El IBAN destino puede ser cualquier IBAN alcanzable por rail.
  • origin_currency y destination_currency son iguales — las transferencias no son FX. Para mover valor entre monedas, primero llame createOrder y luego transfiera el wallet destino.
  • rail determina la semántica de liquidación:
    • sinpe — SINPE costarricense, casi instantáneo en horario hábil, gobernado por la integración de Prosoft.
    • stablecoin — rail de stablecoin, ventana de liquidación más larga, gobernado por confirmaciones en cadena.
  • amount siempre es una cadena con máximo 2 decimales para preservar la precisión en parsers JSON.
  • description es texto libre del socio que aparece en la línea de tiempo del cliente; no incluya material sensible.
  • Los identificadores minoristas de correlación MFA / SCA no están en el cable M2M — las transferencias de socio ejecutan una ceremonia mayorista, no minorista.

Campos del request (`M2mCreateTransferDto`)

`origin` (`M2mTransferOriginDto`)

Campo Tipo Requerido Descripción
iban string (22 caracteres) sí IBAN del wallet ARi origen (código de banco 0589).
iban_holder string no Nombre del titular del origen. Requerido para transferencias DTR.
wallet_id string (uuid) no Selección explícita opcional del wallet. Si se omite, ARi selecciona automáticamente por moneda.

`destination` (`M2mTransferDestinationDto`)

Campo Tipo Requerido Descripción
iban string (22 caracteres) sí IBAN destino.
iban_holder string no Nombre del titular. Recomendado fuertemente para SINPE/stablecoin — aparece en el memo del receptor.

`parameters` (`M2mTransferParametersDto`)

Campo Tipo Requerido Descripción
amount string (decimal-2) sí Importe a transferir. Positivo, máximo 2 decimales.
origin_currency string (ISO 4217) sí Moneda origen.
destination_currency string (ISO 4217) sí Moneda destino. Debe ser igual a origin_currency.
rail "sinpe" | "stablecoin" sí Rail de pago.
description string no Descripción libre en la línea de tiempo de la transferencia.

Ejemplo de request

{
  "origin": {
    "iban": "CR06058901234567890123",
    "iban_holder": "Empresa Ejemplo S.A.",
    "wallet_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "destination": {
    "iban": "CR06152010098765432109",
    "iban_holder": "Juan Pérez García"
  },
  "parameters": {
    "amount": "50000",
    "origin_currency": "CRC",
    "destination_currency": "CRC",
    "rail": "sinpe",
    "description": "Pago de plan móvil"
  }
}

Campos internos que usted nunca verá

El CreateTransferDto interno lleva identificadores minoristas de correlación MFA/SCA usados en flujos de aplicación al cliente final. El filtro de audiencia los retira del cable M2M — los socios no pasan retos de MFA, por lo que los campos no aplican.

Véase también