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.v2.paychtec.com

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

curl -X POST 'https://api.v2.paychtec.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"
}'

curl -X POST 'https://api.v2.paychtec.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.

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