Duas formas de se integrar com a ONE

1. 1

   Você cria um Checkout Preference

   Seu backend chama a API com valor, moeda e título. A ONE devolve um checkout_url.

2. 2

   Seu cliente paga

   Ele abre o link, escolhe um meio local e conclui o pagamento. Isso cria um Payment Order.

3. 3

   Você recebe um webhook

   A ONE faz POST na sua URL quando o status da ordem muda (opened, closed, expired…).

4. 4

   Você busca a ordem

   Use o entity_id do webhook para fazer GET do Payment Order e confirmar o estado final.

1. Teste com estas keys, ou crie as suas

   Para testar a API agora, use a API Key e o API Secret desta página. Quando vender de verdade, no Dashboard vá em Integrations e gere seu x-api-key e x-api-secret.

2. Comece no staging

   Integre contra api.stg.one.lat. Só é possível pedir uma conta de staging se você já tiver uma conta de produção aprovada e ativa: fale com o support.

3. Crie seu primeiro checkout

   POST /v1/checkout_preferences, abra o checkout_url, complete um pagamento de teste e veja o webhook chegar.

Envie x-api-key e x-api-secret em cada chamada. Crie e rotacione as keys no dashboard em Integrations.

Body da request

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

Exemplo de response

Compartilhe checkout_url com seu cliente. O checkout mostra só os meios disponíveis no país dele.

{
  "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 a URL do webhook

Passe custom_urls.status_changes_webhook ao criar o Checkout Preference.

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

Precisa de uma URL para todas as notificações da conta? Fale com o support para configurar no nível da conta.

Payload da notificação

Para eventos de Payment Order, chame GET /v1/payment_orders/:id com o entity_id para obter a versão mais recente.

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

Notificações de refund

Quando um refund é concluído chega REFUND.SUCCEEDED. Depois chame GET /v1/refunds/:id com o 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

Seu handler de webhook precisa ser idempotente. O campo id é único por notificação.

Status do Payment Order

Status do Refund

Moedas