Charge from your code

1. 1

   You create a Checkout Preference

   Your backend calls the API with amount, currency, and title. ONE returns a checkout_url.

2. 2

   Your customer pays

   They open the link, pick a local method, and complete the payment. That creates a Payment Order.

3. 3

   You get a webhook

   ONE POSTs a small event to your URL when the order status changes (opened, closed, expired…).

4. 4

   You fetch the order

   Use the entity_id from the webhook to GET the Payment Order and confirm the final state.

1. 01

   Create API keys

   In the ONE Dashboard go to Integrations and generate your x-api-key and x-api-secret.

2. 02

   Use staging first

   Build against api.stg.one.lat. You can only request a staging account if you already have an approved, active production account — contact support.

3. 03

   Create your first checkout

   POST /v1/checkout_preferences, open the checkout_url, complete a test payment, and watch the webhook arrive.

Send x-api-key and x-api-secret on every call. Create and rotate keys from the dashboard under Integrations.

Request body

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

Example response

Share checkout_url with your customer. Checkout shows only the payment methods available in their country.

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

Configure a webhook URL

Pass custom_urls.status_changes_webhook when you create the Checkout Preference.

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

Need one URL for every notification on the account? Contact support to set it at account level.

Notification payload

For Payment Order events, call GET /v1/payment_orders/:id with entity_id to get the latest version.

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

Refund notifications

When a refund completes you get REFUND.SUCCEEDED. Then call GET /v1/refunds/:id with entity_id.

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

Event types

Payment Order

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

Refund

• REFUND.SUCCEEDED

Your webhook handler should be idempotent. The id field is unique per notification.

Payment Order statuses

Refund statuses

Currencies