Cobra desde tu código

1. 1

   Creas 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

   Consultas la orden

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

1. 01

   Crea tus API keys

   En el Dashboard de ONE ve a Integrations y genera tu x-api-key y x-api-secret.

2. 02

   Empieza en staging

   Integra contra api.stg.one.lat. Solo puedes pedir una cuenta de staging si ya tienes una cuenta de producción aprobada y activa: escríbenos a support.

3. 03

   Crea tu primer checkout

   POST /v1/checkout_preferences, abre el checkout_url, completa un pago de prueba y mira llegar el webhook.

Envía x-api-key y x-api-secret en cada llamada. Crea y rota 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"
    }
  }'

Ejemplo de response

Comparte 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

Pasa custom_urls.status_changes_webhook cuando creas el Checkout Preference.

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

¿Necesitas una URL para todas las notificaciones de la cuenta? Escribe a support para configurarla a nivel cuenta.

Payload de la notificación

Para eventos de Payment Order, llama 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 llama 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 debe ser idempotente. El campo id es único por notificación.

Estados del Payment Order

Estados del Refund

Monedas