SINPE Móvil

SINPE Móvil permite cobrar un pago cuando el comprador realiza una transferencia al número móvil de ONVO y ONVO la asocia automáticamente con una intención de pago.

Actualmente este flujo solo soporta pagos en CRC.

Referencia API relacionada

Paso	Referencia	Payloads
Crear la intención	POST /v1/payment-intents	Solicitud · Respuesta
Crear el método de pago	POST /v1/payment-methods	Solicitud · Respuesta
Confirmar la intención	POST /v1/payment-intents/{id}/confirm	Solicitud · Respuesta
Conciliar transferencias	GET /v1/mobile-transfers/list	Parámetros · Respuesta
Recibir confirmación	Webhooks	Payloads por evento

Antes de empezar

• Configurá webhooks y escuchá payment-intent.succeeded.
• Usá CRC como moneda de la intención de pago.
• Indicá en el método de pago la identificación real de la persona o entidad que hará la transferencia.
• Pedile al comprador transferir desde una cuenta cuya identificación coincida con la enviada en mobileNumber.identification.

ONVO solo acepta una transferencia entrante si coincide con una intención de pago en processing por identificación y monto. Consultá cómo se asocia la transferencia.

El número destino por defecto para recibir transferencias SINPE Móvil es +506 70196686. Si tu comercio solicitó un número personalizado, usá el número provisto por el equipo de soporte de ONVO.

Flujo

1. Creá una intención de pago por el monto exacto a cobrar.
2. Creá un método de pago con type: "mobile_number".
3. Confirmá la intención con el paymentMethodId.
4. Mostrá al comprador el número SINPE Móvil destino y el monto exacto.
5. Esperá el webhook payment-intent.succeeded antes de marcar el pago como completado.

Cuando confirmás la intención con este método de pago, la intención pasa a processing. Ese estado significa que ONVO está esperando recibir y asociar la transferencia.

Cómo se asocia la transferencia

Antes de que se envíe una transferencia SINPE Móvil, SINPE le consulta a ONVO si la acepta. ONVO la acepta solo si hay una intención de pago en processing con la misma identificación y el mismo monto que la transferencia:

• La identificación tiene que ser exactamente la que reporta el banco del comprador, incluyendo los guiones. Consultá el formato de la identificación.
• El monto tiene que ser exactamente el de la intención. ONVO no acepta pagos parciales ni montos mayores.

Cuando la transferencia coincide, el pago se completa y recibís payment-intent.succeeded.

Si no hay una intención que coincida, ONVO rechaza la transferencia antes de que se envíe: el dinero no sale de la cuenta del comprador y el comprador no puede completar la transferencia desde su banco. ONVO no recibe el dinero para luego devolverlo. Por eso, confirmá la intención antes de que el comprador transfiera.

Crear la intención de pago

curl https://api.onvopay.com/v1/payment-intents \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "CRC",
    "description": "Pago SINPE Móvil #1001"
  }'

Crear el método de pago

mobileNumber.number es el número SINPE Móvil del comprador. El número destino al que el comprador debe transferir es el número de ONVO indicado en las instrucciones de pago.

curl https://api.onvopay.com/v1/payment-methods \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mobile_number",
    "mobileNumber": {
      "identification": "01-1393-1919",
      "identificationType": 0,
      "number": "+50688888888"
    },
    "billing": {
      "name": "María Rodríguez",
      "email": "maria@example.com"
    }
  }'

Formato de la identificación

Enviá mobileNumber.identification con el formato que corresponde a mobileNumber.identificationType, incluyendo los guiones. ONVO compara esta identificación con la que reporta el banco del comprador. Si la enviás en otro formato, por ejemplo 113931919 en lugar de 01-1393-1919, la identificación no coincide y ONVO no acepta la transferencia.

identificationType	Tipo	Formato	Ejemplo
0	Persona física nacional	0#-####-####	01-1393-1919
1	Persona física residente	1###########	129381746112
2	Entidad estatal	2-###-######	2-100-000001
3	Persona jurídica	3-###-######	3-101-212393
4	Institución autónoma	4-000-######	4-000-042141
5	Diplomático	5###########	512345678901
9	Extranjero	9###########	9CA938146112

Usá el tipo de la cuenta desde la que se hace la transferencia. Si el comprador paga desde una cuenta de empresa, enviá identificationType: 3 con la cédula jurídica.

Podés usar librerías como react-number-format para aplicar el formato en los campos de texto de tu checkout.

Confirmar la intención

curl https://api.onvopay.com/v1/payment-intents/$PAYMENT_INTENT_ID/confirm \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethodId": "cl502zv0d0127ebdp3zt27651"
  }'

Después de confirmar, indicá al comprador que transfiera el monto exacto al número SINPE Móvil de ONVO. No marques el pago como exitoso en tu sistema hasta recibir payment-intent.succeeded.

Conciliación

La lista de pagos por SINPE Móvil refleja transferencias entrantes recibidas en un número SINPE Móvil. Es útil para revisar transferencias que no pudieron asociarse automáticamente.

Si paymentIntentId es null, la transferencia todavía no está vinculada a una intención de pago.

Pruebas

En modo de prueba, usando llaves onvo_test_, los números definidos en métodos de pago de prueba para SINPE Móvil simulan distintos escenarios de transferencia. No necesitás hacer una transferencia real ni enviar fondos al número SINPE Móvil de ONVO.

Usá esos números para simular transferencias exitosas, retrasadas, fallidas y parciales.