Uprails API Reference

Base URL

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

Base URLtext

https://api.uprails.com

Sandbox Environment

For testing, use https://sandbox.api.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:

Required Headerstext

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)

Pagination Examplebash

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

The API supports idempotent requests to safely retry operations without risk of performing them twice. Include an X-Idempotency-Key header with a unique value for each distinct operation.

Idempotent Requestbash

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

Idempotency Key Best Practices

Use UUIDs or other unique identifiers
Store keys to retry failed requests safely
Keys are valid for 24 hours

Response Format

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

Response Examplesjson

// 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

Rate Limit Exceeded

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