Direct integration

Integrate Nelo Checkout directly through our REST API, without a platform plugin.

Use this integration for custom storefronts or ecommerce platforms where Nelo does not provide a native plugin.

For endpoint and field details, see the API reference.

Integration flow

1. The shopper selects Nelo at checkout.
2. Your backend creates an order.
3. Redirect the shopper to the returned redirectUrl.
4. The shopper completes the Nelo flow.
5. Nelo redirects the shopper to your redirectConfirmUrl or redirectCancelUrl.
6. Your backend verifies the order status.
7. Capture the authorization when you are ready to charge.

Important: Do not use the browser redirect as confirmation of authorization. Always verify the order status through the API or webhook before fulfilling the order.

All amounts are expressed in minor units. For example, 249900 represents $2,499.00 MXN.

Authentication

Send your secret token on every call: Authorization: Bearer <secret token>. Nelo issues it when your store is set up, and it identifies your store, so call the API only from your backend, never from a browser, app or POS terminal. If it leaks, ask us to rotate it; the old token stops working at once. Promotional-message endpoints take the publishable token instead, which is safe to use in the browser.

Order identifiers

Nelo orders use three main identifiers:

If you do not have the orderUuid, for example after a timed-out create request, use Find orders with platformPaymentId or reference.

Redirects

Nelo redirects shoppers to the URLs provided when creating the order:

• redirectConfirmUrl when the Nelo flow completes.
• redirectCancelUrl when the shopper cancels.

Nelo does not append orderUuid or other parameters to these URLs. Add any information your application needs to the URL yourself.

Order status

Use Find orders to verify the current status.

Authorizations expire after 3 days if they are not captured.

Capture, void, and refund

Use Capture when you are ready to charge an authorized order.

If your business fulfills immediately, you can enable shouldAutoCapture when creating the order.

Use Void to release an authorization you do not intend to capture.

Use Refund for full or partial refunds. Refunds aren't allowed after 90 days of order creation.

Always provide an idempotencyKey when creating a refund so the request can be retried safely.

Order amounts

Retrieve a payment returns the financial details of an order, including the amount, Nelo fee, tax, netAmount, and refunds.

Use Find orders when you need the current order status.

Webhooks

Nelo can notify your backend when an order is authorized or canceled.

Current events are:

• order.authorized
• order.canceled

Webhook delivery is at least once and events may arrive out of order. Make your handler idempotent and verify the current order state before taking action.

Deduplicate events using:

orderUuid + event

Return a 2xx response quickly and process slower work asynchronously.

Signature verification

Webhook requests include an X-Nelo-Signature header containing a Base64-encoded SHA256withRSA signature.

Verify it using Nelo's public key and the exact request body bytes received. Do not parse and reserialize the JSON before verification.

Idempotency and retries

Use the Idempotency-Key header when creating, capturing, voiding, or refunding an order.

If a request times out, retry it with the same idempotency key and request body.

Idempotency keys are retained for 24 hours.

For create requests, platformPaymentId also protects against duplicate orders. For refunds, use the refund's idempotencyKey.

Errors

Errors return an HTTP status code and JSON response:

{
  "message": "Order platformPaymentId is required...",
  "status": 400
}

Common status codes:

Promotional messages

Promotional-message endpoints use the publishable token, so they can be called directly from the browser.

See Promotional messages.