DOCSEARCHbyAlgolia
Submit Docs

ONVO Pay Documentation

website·Indexed 33 days ago

https://docs.onvopay.com

Payment processing platform documentation covering Checkout sessions, payment intents, recurring charges, and marketplace functionality. Includes guides for SINPE Móvil, 3DS authentication, fraud monitoring, and integrations for WordPress and Magento, alongside a full OpenAPI reference for managing customers, products, and connected accounts.

Tokens
17.1K
Snippets
134
Records
162
Agent score
57%

What's inside ONVO Pay

  1. Handle the mobile-transfer.received webhook event

    The mobile-transfer.received event provides information about an incoming mobile transfer. Note that this event by itself does not confirm a payment intent.
    {
  "type": "mobile-transfer.received",
  "data": {
    "amount": 1450000,
    "currency": "CRC",
    "description": "PAGO DE SERVICIOS",
    "SINPERefNumber": "2025110312774577852010",
    "authorizationDate": "2026-04-29T16:30:00.000Z",
    "originId": "01-1393-1919",
    "originName": "JUAN PEREZ CASTRO",
    "originPhone": "72940567"
  }
}

  2. Configure and integrate ONVO Webhooks

    ONVO uses webhooks to notify applications about payment intents, recurring charges, checkout sessions, and incoming transfers. Webhooks are sent as POST requests with Content-Type: application/json.

    Integration Workflow:

    1. Expose a public HTTPS endpoint.
    2. Register the endpoint in the ONVO Dashboard (Developer section).
    3. Verify the event origin using the webhook secret.
    4. Process events idempotently.
    5. Respond with a 2xx status code upon successful processing.

    Payload Structure:

    • type: String identifying the event (used to determine business logic).
    • data: Object containing a snapshot of the related entity.

    Data Formats:

    • Amounts: Integers in the smallest currency unit (e.g., 500000 = ₡5,000.00 CRC; 5000 = $50.00 USD).
    • Dates: ISO 8601 format in UTC.
    {
  "type": "payment-intent.succeeded",
  "data": {
    "id": "clpiment0001"
  }
}

  3. Handle 3D Secure (3DS) authentication using the ONVO Web Library

    You can manage 3DS authentication using a modal via the ONVO web library. Initialize the library with your public key and call handleNextAction when a payment intent requires action. Even if the 3DS authentication is successful, you must still validate the final status of the payment intent as the transaction could still be declined for other reasons.
    <script src="https://js.onvopay.com/v1/"></script>
<script>
  const onvo = ONVO("onvo_live_publishable_key_H4PG...");

  onvo.handleNextAction({
    paymentIntentId: "clrr934wl001mdpkhw2g82rlt",
  }).then(function (result) {
    if (result.error) {
      console.error(result.error);
    } else {
      console.log(result.paymentIntent);
    }
  });
</script>

  4. Use Credix with ONVO Checkout or SDK

    If using the ONVO Checkout or SDK, the manual API flow for Credix is not required. When Credix is enabled and the amount meets the minimum requirements, it appears automatically as a payment option. The customer selects the installment plan within the UI, and the credixInstallmentMonths value is handled automatically by the system.

  5. Allow customers to choose the payment amount in Checkout

    To enable a flow where the buyer defines the payment amount (e.g., donations, tips, or flexible reservations), use the customUnitAmount object when creating a price. This configuration allows you to suggest a default amount and set minimum and maximum boundaries for the customer to choose from within the Checkout experience.

    Key Rules:

    • Use type: "one_time" for the price.
    • Do NOT send unitAmount if you are using customUnitAmount.
    • The preset value is required and must fall between the minimum and maximum values.
    • Use a single line item with quantity: 1 when creating the Checkout session.
    • Amounts must be sent in the smallest currency unit (e.g., cents for USD, céntimos for CRC).

  6. Implement fraud monitoring for API integrations

    For 100% API-based integrations, it is highly recommended to include the ONVO web library to collect browser signals from the buyer, which improves fraud prevention accuracy. This is optional and not required for those using plugins, payment links, or the embedded SDK, as these already include signal collection.
    <!-- Add to the head of the page -->
<script src="https://js.onvopay.com/v1/"></script>

<script>
  // Initialize with your public key
  const onvo = ONVO("onvo_live_publishable_key_H4PG...");

  // Call startSignalSession once you have the paymentIntentId, before confirming payment
  onvo.startSignalSession({
    paymentIntentId: "clrr934wl001mdpkhw2g82rlt",
  });
</script>

  7. Implement cursor-based pagination for list endpoints

    ONVO API list endpoints (e.g., /v1/customers, /v1/payment-intents/account, /v1/products) use cursor-based pagination. To navigate through collections, use the startingAfter and endingBefore query parameters.

    Constraints:

    • Send only one cursor per request. Sending both startingAfter and endingBefore simultaneously will result in an API error.
    • The limit parameter accepts values between 1 and 100 (defaults to 10).

    Navigation Logic:

    • To move forward: Use the id of the last object in the current page as the startingAfter parameter. In API responses, this is provided in meta.cursorNext.
    • To move backward: Use the id of the first object in the current page as the endingBefore parameter. In API responses, this is provided in meta.cursorBefore.
    # First page
curl "https://api.onvopay.com/v1/customers?limit=10" \
  -H "Authorization: Bearer onvo_test_secret_key_..."

# Next page (using startingAfter)
curl "https://api.onvopay.com/v1/customers?limit=10&startingAfter=cl40muorw00493ndp0okzk2g3" \
  -H "Authorization: Bearer onvo_test_secret_key_..."

# Previous page (using endingBefore)
curl "https://api.onvopay.com/v1/customers?limit=10&endingBefore=cl40muorw00493ndp0okzk2g3" \
  -H "Authorization: Bearer onvo_test_secret_key_..."

  8. Capture authorized funds for a payment intent

    Once a payment intent is in the requires_capture state, you can capture the funds. By default, ONVO captures the full authorized amount. To perform a partial capture, specify the amountToCapture parameter; any remaining authorized funds will be automatically released. A successful capture moves the intent to succeeded, while a failure reverts it to requires_payment_method.
    {
  "amountToCapture": 750
}

  9. Implement webhook endpoint responses and error handling

    Your webhook endpoint must adhere to the following requirements:

    1. Response Codes: Respond with a 2xx status code only if the event was successfully received and processed. Any other status code will cause OnvoPay to record the delivery as failed.
    2. Event Ordering: Your system must be designed to tolerate events arriving out of order.
    3. Error Payloads: When an event represents an error, the payload includes an error object containing:
      • message: A human-readable description of the error.
      • code: The error code (if applicable).
      • type: The error type (if applicable).

  10. Implement payments using SINPE PIN

    SINPE PIN allows merchants to collect payments via bank transfers to an IBAN provided by ONVO. This method is available only upon request and supports CRC currency.

    Critical Constraint: Transfers must be sent in real-time. Scheduled, deferred, or non-immediate transfers cannot be automatically associated by ONVO and will not complete the flow.

    Key Requirements:

    • Request enablement of SINPE PIN from ONVO support.
    • Use the specific destination IBAN provided by ONVO.
    • The identification in bankDeposit.identification must match the identification reported by the bank in the transfer.
    • Configure webhooks to listen for payment-intent.succeeded.

    Payment Flow:

    1. Create a payment intent for the exact amount.
    2. Create a payment method with type: "bank_deposit".
    3. Confirm the intent using the paymentMethodId (the intent will move to processing state).
    4. Instruct the buyer to transfer the exact amount to the ONVO IBAN in real-time.
    5. Wait for the payment-intent.succeeded webhook.
    # 1. Create 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": "Pago SINPE PIN #1001"
  }'

# 2. Create Payment Method
curl https://api.onvopay.com/v1/payment-methods \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bank_deposit",
    "bankDeposit": {
      "identification": "01-1393-1919",
      "identificationType": 1
    },
    "billing": {
      "name": "María Rodríguez",
      "email": "maria@example.com"
    }
  }'

# 3. Confirm 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"
  }'

  11. Integrate ONVO payments: General workflow

    The base flow for integrating ONVO payments consists of five main steps: 1. Obtain secret and publishable keys from the ONVO Dashboard. 2. Create a Payment Intent to represent the order's collection cycle. 3. Confirm the payment using the buyer's payment method or ONVO Checkout. 4. Register a webhook endpoint to listen for events like payment-intent.succeeded for internal order reconciliation. 5. Switch to live mode by replacing test keys with onvo_live_ keys after end-to-end testing.
    # Example: Creating a 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": 250000,
    "currency": "CRC",
    "description": "Orden #1001"
  }'

  12. Implement the Credix API payment flow

    To process a Credix payment via API, follow these steps:

    1. Create a payment intent for the exact amount.
    2. Create a payment method of type credix with card details.
    3. Confirm the intent using the paymentMethodId and the required credixInstallmentMonths.
    4. The intent moves to succeeded if approved or failed if rejected.
    5. Wait for the payment-intent.succeeded webhook before marking the payment as complete in your system.
    # 1. Create 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": "Pago Credix #1001"
  }'

# 2. Create Payment Method
curl https://api.onvopay.com/v1/payment-methods \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "credix",
    "credix": {
      "number": "4111111111111111",
      "expMonth": 12,
      "expYear": 2026,
      "cvv": "123",
      "holderName": "María Rodríguez"
    },
    "billing": {
      "name": "María Rodríguez",
      "email": "maria@example.com"
    }
  }'

# 3. Confirm 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",
    "credixInstallmentMonths": 3
  }'