Dos formas de integrarte con ONE

1. 1

   Creás un Checkout Preference

   Tu backend llama a la API con monto, moneda y título. ONE te devuelve un checkout_url.

2. 2

   Tu cliente paga

   Abre el link, elige un medio local y completa el pago. Ahí se crea un Payment Order.

3. 3

   Te llega un webhook

   ONE hace POST a tu URL cuando cambia el estado de la orden (opened, closed, expired…).

4. 4

   Consultás la orden

   Usá el entity_id del webhook para hacer GET del Payment Order y confirmar el estado final.

1. Probá con estas keys, o creá las tuyas

   Para probar la API ahora, usá el API Key y el API Secret de esta página. Cuando vendas de verdad, en el Dashboard andá a Integrations y generá tu x-api-key y x-api-secret.

2. Empezá en staging

   Integrá contra api.stg.one.lat. Solo podés pedir una cuenta de staging si ya tenés una cuenta de producción aprobada y activa: escribinos a support.

3. Creá tu primer checkout

   POST /v1/checkout_preferences, abrí el checkout_url, completá un pago de prueba y mirá llegar el webhook.

Mandá x-api-key y x-api-secret en cada llamada. Creá y rotá las keys desde el dashboard en Integrations.

Body del request

Ejemplo de request

curl 'https://api.one.lat/v1/checkout_preferences' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-api-secret: YOUR_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 25,
    "currency": "USD",
    "origin": "API",
    "title": "Introductory course to Blockchain",
    "external_id": "order_1234",
    "payer": {
      "email": "luca@test.com",
      "first_name": "Luca",
      "last_name": "Dorain",
      "phone_number": "+521142567689"
    },
    "custom_urls": {
      "status_changes_webhook": "https://api.mycompany.io/webhook",
      "success_payment_redirect": "https://mycompany.io/payment/success",
      "error_payment_redirect": "https://mycompany.io/payment/error"
    }
  }'

Ejemplo de response

Compartí checkout_url con tu cliente. El checkout solo muestra los medios disponibles en su país.

{
  "id": "qwDsh9aMoywPOiUx0O",
  "amount": 25,
  "currency": "USD",
  "created_at": "2025-02-25T14:11:29Z",
  "expiration_date": "2025-02-26T15:02:50Z",
  "origin": "API",
  "external_id": "order_1234",
  "title": "Introductory course to Blockchain",
  "type": "PAYMENT",
  "checkout_url": "https://one.lat/checkout/qwDsh9aMoywPOiUx0O",
  "payer": {
    "email": "luca@test.com",
    "first_name": "Luca",
    "last_name": "Dorain",
    "phone_number": "+521142567689"
  }
}

Configurar la URL del webhook

Pasá custom_urls.status_changes_webhook cuando creás el Checkout Preference.

{
  "custom_urls": {
    "status_changes_webhook": "https://api.mycompany.io/webhook"
  }
}

¿Necesitás una URL para todas las notificaciones de la cuenta? Escribile a support para configurarla a nivel cuenta.

Payload de la notificación

Para eventos de Payment Order, llamá a GET /v1/payment_orders/:id con el entity_id para obtener la versión más reciente.

{
  "id": "uCEarm1kXJsroMQ6dt",
  "event_type": "PAYMENT_ORDER.CLOSED",
  "entity_type": "PAYMENT_ORDER",
  "entity_id": "rcAaNfKdKJRmrnj4l5"
}

Notificaciones de refund

Cuando un refund se completa llega REFUND.SUCCEEDED. Después llamá a GET /v1/refunds/:id con el entity_id.

{
  "id": "nR8kLm2pQxYtVw4HsZ",
  "event_type": "REFUND.SUCCEEDED",
  "entity_type": "REFUND",
  "entity_id": "1dUPlZbsDABq3bIEOG"
}

Tipos de evento

Payment Order

• PAYMENT_ORDER.OPENED
• PAYMENT_ORDER.CLOSED
• PAYMENT_ORDER.REJECTED
• PAYMENT_ORDER.EXPIRED

Refund

• REFUND.SUCCEEDED

Tu handler del webhook tiene que ser idempotente. El campo id es único por notificación.

Estados del Payment Order

Estados del Refund

Monedas