Onecheckout API Documentation

Overview

This document provides a comprehensive overview of the Onecheckout REST API. It is designed for developers who need to integrate our payment services into their applications. The API is organized around REST principles, uses JSON for requests and responses, and standard HTTP response codes.

Standard Workflow

The typical payment processing flow involves creating an order, redirecting the user to a secure payment page, and then verifying the payment status.

Client Application         Your Server (Backend)      Onecheckout API
------------------         ---------------------      ---------------
      |                            |                          |
1.  User clicks "Pay"  -------->   |                          |
      |                            |                          |
      |                      2. Create Order Request          |
      |                            | ---------------------->  |
      |                            |                          |
      |                            | <----------------------  |
      |                      3. Receive payment_token         |
      | <------------------------  | & redirect link          |
      |                            |                          |
4.  Redirect user to             |                          |
    Onecheckout URL ------------->                          |
      |                                                       |
      |                5. User completes payment              |
      | <---------------------------------------------------  |
      | 6. Redirected to success_url                          |
      |    with order details                                 |
      |                            |                          |
      |                      7. Verify Payment Status         |
      |                            | ---------------------->  |
      |                            | (GET /orders/:id)        |
      |                            |                          |
      |                            | <----------------------  |
      |                      8. Receive PAID status           |
      |                            |                          |
      | <------------------------  |                          |
9.  Display "Thank You" page     |                          |
      |                            |                          |

Authentication

The Onecheckout API uses API keys to authenticate requests. You can manage your API keys from the merchant dashboard. Authentication is performed via HTTP headers. Note that different endpoints may require different headers.

Bearer Token

Used for core order operations. Provide your token as a Bearer token in the Authorization header.

Authorization: Bearer <your-token>

X-API-Key

Used for account management and data retrieval. Provide your key in the X-API-Key header.

X-API-Key: <your_api_key_here>

Important:
Your API keys carry many privileges. Be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

API Endpoints

Base URL for all API endpoints:

Production: https://onecheckout.sandbox.whatee.io/api/v1.0
Staging:    https://api-staging.onecheckout.com/api/v1.0

Read Account

GET /me

Retrieves the details of the authenticated merchant account.

Authentication

Requires X-API-Key or Authorization: Bearer.

Successful Response (200 OK)

{
  "id": "merchant_id_uuid",
  "email": "merchant@example.com",
  "full_name": "John Doe",
  "phone": "+1234567890",
  "address": "123 Business St, City",
  "theme": "default",
  "order_prefix": "ORD-",
  "currencies": ["USD", "EUR"],
  "payment_methods": ["paypal", "stripe_hosted"],
  "success_url": "https://store.example.com/success",
  "cancel_url": "https://store.example.com/cancel",
  "webhook_url": "https://store.example.com/webhook",
  "created": 1698765432000
}

Update Account

POST /me

Updates the details of the authenticated merchant account.

Request Body (JSON)

Field	Type	Description
email	string	Merchant's email address.
full_name	string	Full name of the merchant.
phone	string	Contact phone number.
address	string	Business address.
webhook_url	string	URL for receiving webhooks.
success_url	string	Default redirect URL for successful payments.
cancel_url	string	Default redirect URL for cancelled payments.

Successful Response (200 OK)

Returns the updated fields of the merchant object.

Create Order

POST /orders

Creates a new order and initializes a payment session.

Authentication

Requires Authorization: Bearer <token>.

Request Body (JSON)

Field	Type	Required	Description
currency	string	Yes	ISO 4217 currency code (e.g., 'USD').
order_lines	array	Yes	Array of objects, each representing a line item.
order_lines[].title	string	Yes	Name of the product.
order_lines[].quantity	number	Yes	Quantity of the product.
order_lines[].unit_price	number	Yes	Price per unit.
tax_amount	number	No	Total tax amount for the order.
success_url	string	No	Override the default success URL.
cancel_url	string	No	Override the default cancel URL.
reference_id	string	No	Your internal identifier for the order.

Successful Response (200 OK)

Returns an order object with a payment_token and redirect links.

{
  "id": "0001",
  "payment_token": "abc123...",
  "status": "OPEN",
  "amount": 61.97,
  "links": [
    {
      "href": "https://checkout.onecheckout.com/pay/0001?token=abc123",
      "rel": "pay"
    }
  ]
}

Read Order

GET /orders/:id

Retrieves the details of a specific order by its ID.

Successful Response (200 OK)

Returns a full order object, including status, payment details, and customer information if available.

{
  "id": "0001",
  "status": "PAID",
  "amount": 61.97,
  "currency": "USD",
  "payment_method": "stripe_hosted",
  "payment_id": "pi_abc123",
  "created": 1729712400000,
  "paid": 1729712500000
}

Capture Order

POST /orders/:id/capture

Captures a previously authorized payment. This is typically used to confirm a payment after the user has completed the checkout flow.

Successful Response (200 OK)

Returns the order object with a status of PAID if successful.

List Orders

POST /orders-list

Retrieves a paginated list of orders, with support for filtering.

Request Body (JSON)

Field	Type	Description
anchor	string	Pagination cursor from `next_anchor` of a previous response.
limit	integer	Number of orders to return (default: 20, max: 1024).
status	string	Filter by status: OPEN, PAID, CANCELLED, REFUNDED.
created_hour_from	timestamp	Start of creation time window.
created_hour_to	timestamp	End of creation time window.

Successful Response (200 OK)

{
  "anchor": "",
  "limit": 50,
  "count": 125,
  "next_anchor": "order_id_for_next_page",
  "orders": [
    {
      "id": "0001",
      "status": "PAID",
      "amount": 99.99
    }
  ]
}

List Order Events

GET /orders/:id/events

Retrieves a list of all events associated with a specific order, such as payment creation and status changes.

Successful Response (200 OK)

{
  "events": [
    {
      "id": "event_uuid_1",
      "order_id": "0001",
      "type": "payment_created",
      "created": 1698765432000
    },
    {
      "id": "event_uuid_2",
      "order_id": "0001", 
      "type": "payment_succeeded",
      "created": 1698765432200
    }
  ]
}

Common Information

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of a request. In case of an error, the response body will contain a JSON object with details.

Error Code	HTTP Status	Description
api_key_required	400	The API key was not provided.
api_key_invalid	401	The provided API key is invalid or expired.
validation_error	400	The request body contains invalid data.
id_required	400	A required ID parameter is missing.
id_invalid	404	The requested resource ID does not exist.
order_status_invalid	400	The operation is not permitted for the order's current status.
server_error	500	An unexpected error occurred on the server.

Rate Limiting

To ensure API stability, requests are rate-limited per API key.

Rate limit: 1000 requests per minute.
Concurrent requests: 10 simultaneous requests.

If you exceed the rate limit, the API will respond with an HTTP 429 Too Many Requests status code.