SINPE Movil

SINPE Movil lets you collect a payment when the buyer sends a transfer to ONVO's mobile number and ONVO automatically associates it with a payment intent.

This flow currently supports CRC payments only.

Related API reference

Step	Reference	Payloads
Create the intent	POST /v1/payment-intents	Request · Response
Create the payment method	POST /v1/payment-methods	Request · Response
Confirm the intent	POST /v1/payment-intents/{id}/confirm	Request · Response
Reconcile transfers	GET /v1/mobile-transfers/list	Parameters · Response
Receive confirmation	Webhooks	Event payloads

Before you start

• Configure webhooks and listen for payment-intent.succeeded.
• Use CRC as the payment intent currency.
• Send the real identification of the person or entity that will make the transfer in the payment method.
• Ask the buyer to transfer from an account whose identification matches mobileNumber.identification.

ONVO accepts an incoming transfer only if it matches a payment intent in processing by identification and amount. See how the transfer is associated.

The default destination number for receiving SINPE Movil transfers is +506 70196686. If your merchant account requested a custom number, use the number provided by the ONVO support team.

Flow

1. Create a payment intent for the exact amount to collect.
2. Create a payment method with type: "mobile_number".
3. Confirm the intent with the paymentMethodId.
4. Show the buyer the destination SINPE Movil number and the exact amount.
5. Wait for the payment-intent.succeeded webhook before marking the payment as complete.

When you confirm the intent with this payment method, the intent moves to processing. That state means ONVO is waiting to receive and associate the transfer.

How the transfer is associated

Before a SINPE Movil transfer is sent, SINPE asks ONVO whether to accept it. ONVO accepts it only if there's a payment intent in processing with the same identification and the same amount as the transfer:

• The identification must be exactly the one the buyer's bank reports, dashes included. See the identification format.
• The amount must be exactly the intent amount. ONVO doesn't accept partial payments or higher amounts.

When the transfer matches, the payment completes and you receive payment-intent.succeeded.

If no intent matches, ONVO rejects the transfer before it's sent: the money never leaves the buyer's account, and the buyer can't complete the transfer from their bank. ONVO doesn't receive the money and then return it. That's why you should confirm the intent before the buyer transfers.

Create the payment intent

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": "SINPE Movil payment #1001"
  }'

Create the payment method

mobileNumber.number is the buyer's SINPE Movil number. The destination number the buyer should transfer to is ONVO's number shown in your payment instructions.

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": "Maria Rodriguez",
      "email": "maria@example.com"
    }
  }'

Identification format

Send mobileNumber.identification in the format that matches mobileNumber.identificationType, dashes included. ONVO compares this identification with the one the buyer's bank reports. If you send it in a different format, for example 113931919 instead of 01-1393-1919, the identification doesn't match and ONVO doesn't accept the transfer.

identificationType	Type	Format	Example
0	National individual	0#-####-####	01-1393-1919
1	Resident individual	1###########	129381746112
2	State entity	2-###-######	2-100-000001
3	Legal entity	3-###-######	3-101-212393
4	Autonomous institution	4-000-######	4-000-042141
5	Diplomat	5###########	512345678901
9	Foreign national	9###########	9CA938146112

Use the type of the account the transfer comes from. If the buyer pays from a company account, send identificationType: 3 with the company's legal ID.

You can use libraries such as react-number-format to apply the format in your checkout's text inputs.

Confirm the intent

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

After confirmation, tell the buyer to transfer the exact amount to ONVO's SINPE Movil number. Do not mark the payment as successful in your system until you receive payment-intent.succeeded.

Reconciliation

The SINPE Movil payments list reflects incoming transfers received on a SINPE Movil number. It is useful for reviewing transfers that could not be associated automatically.

If paymentIntentId is null, the transfer is not yet linked to a payment intent.

Testing

In test mode, using onvo_test_ keys, the numbers defined in SINPE Movil test payment methods simulate different transfer scenarios. You do not need to make a real transfer or send funds to ONVO's SINPE Movil number.

Use those numbers to simulate successful, delayed, failed, and partial transfers.