API Basics

Learn the fundamentals of working with the Uprails API.

Base URL

All API requests should be made to the following base URL:

https://api.uprails.com

Sandbox Environment: For testing, use https://api.sandbox.uprails.com with your test API keys.

Request Format

The Uprails API accepts JSON-encoded request bodies and returns JSON-encoded responses. All requests must include the following headers:

Content-Type: application/json
api-key: snd_YOUR_API_KEY

HTTP Methods

The API uses standard HTTP methods to indicate the action being performed:

Method	Description
`GET`	Retrieve a resource or list of resources
`POST`	Create a new resource or perform an action
`PUT`	Replace an existing resource
`DELETE`	Delete a resource

Pagination

List endpoints support pagination through the following parameters:

Parameter	Type	Description
`limit`	integer	Number of items to return (default: 10, max: 100)
`offset`	integer	Number of items to skip (default: 0)
`created_gte`	string	Filter items created after this timestamp (ISO 8601)
`created_lte`	string	Filter items created before this timestamp (ISO 8601)

curl 'https://api.uprails.com/payments/list' \
  -H "api-key: snd_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "limit": 25,
  "offset": 0,
  "created_gte": "2024-01-01T00:00:00Z"
}'

curl 'https://api.uprails.com/payments/list' \  -H "api-key: snd_YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "limit": 25,  "offset": 0,  "created_gte": "2024-01-01T00:00:00Z"}'

Filtering

Most list endpoints support filtering by various fields. Common filters include:

Filter	Description
`status`	Filter by status (e.g., succeeded, failed, pending)
`customer_id`	Filter by customer ID
`currency`	Filter by currency code
`payment_method`	Filter by payment method type

Idempotency

Supply your own payment_id when creating a payment. It is unique per merchant, so retrying with the same value cannot create a second payment.

payment_id is a string of 1–64 characters using letters, digits, _ and -. If you omit it, one is generated for you — but then retries are not safe, because each attempt creates a new payment.

curl -X POST 'https://api.uprails.com/payments' \
  -H "api-key: snd_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "payment_id": "order_12345",
  "amount": 1000,
  "currency": "USD",
  "profile_id": "YOUR_PROFILE_ID"
}'

curl -X POST 'https://api.uprails.com/payments' \  -H "api-key: snd_YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "payment_id": "order_12345",  "amount": 1000,  "currency": "USD",  "profile_id": "YOUR_PROFILE_ID"}'

If a retry returns HE_01 — "The payment with the specified payment_id already exists in our records" — the original request was received and is being processed or has completed. Retrieve the payment to read its true status rather than treating the error as a failure.

Safe retry checklist:

Generate one payment_id per order and reuse it on every retry
Treat HE_01 as "already submitted", not as a failure
Call GET /payments/{payment_id} to get the authoritative status

Response Format

All responses are returned in JSON format. Successful responses return the requested data, while error responses include an error object with details.

Successful response:

{
  "payment_id": "pay_1234567890abcdef",
  "status": "succeeded",
  "amount": 1000,
  "currency": "USD"
}

List response:

{
  "data": [],
  "total_count": 100,
  "has_more": true
}

Error response:

{
  "error": {
    "type": "invalid_request",
    "code": "IR_04",
    "message": "Invalid value for field: amount"
  }
}

Rate Limiting

The API implements rate limiting to ensure fair usage. Rate limit information is included in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait until the reset time before retrying.

On this page