Saltar al contenido principal

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​

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 intenta asociar la transferencia entrante primero por número de identificación. Si el banco reporta una identificación distinta a la esperada, la asociación automática puede fallar.

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.

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

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.