API Endpoints

This page provides a comprehensive reference for all Orsunpay API endpoints, versioning strategy, and compatibility policies.

Base URLs

API Endpoints

Environment	Base URL	Description
Sandbox	`https://sandbox-api.orsunpay.com/v1`	Development and testing
Production	`https://api.orsunpay.com/v1`	Live transactions

Service Endpoints

Service	Sandbox	Production
Checkout	`https://sandbox-checkout.orsunpay.com`	`https://checkout.orsunpay.com`
BackOffice	`https://office.orsunpay.com`	`https://office.orsunpay.com`
Webhooks	Delivered to your configured URLs	Delivered to your configured URLs

API Versioning

Current Version: v1

All API endpoints are versioned using URL path versioning:

https://api.orsunpay.com/v1/{resource}

Version Format

Major Version: Breaking changes (e.g., v1, v2)
Minor Updates: Backward-compatible improvements (released without version increment)
Patch Updates: Bug fixes and security updates (transparent to users)

We’re currently on version 1 (v1) and maintain strict backward compatibility within major versions.

Core API Endpoints

Transactions

Method	Endpoint	Description
`POST`	`/v1/transactions`	Create a new transaction
`GET`	`/v1/transactions/{id}`	Retrieve transaction by ID
`GET`	`/v1/transactions`	List transactions with filtering
`POST`	`/v1/transactions/{id}/capture`	Capture authorized transaction
`POST`	`/v1/transactions/{id}/void`	Void authorized transaction
`POST`	`/v1/transactions/{id}/refund`	Refund completed transaction

Customers

Method	Endpoint	Description
`POST`	`/v1/customers`	Create a new customer
`GET`	`/v1/customers/{id}`	Retrieve customer by ID
`GET`	`/v1/customers`	List customers with filtering
`PUT`	`/v1/customers/{id}`	Update customer information
`DELETE`	`/v1/customers/{id}`	Delete customer

Merchants

Method	Endpoint	Description
`GET`	`/v1/merchants/me`	Retrieve current merchant
`GET`	`/v1/merchants`	List merchants (admin only)
`GET`	`/v1/merchants/{id}`	Retrieve specific merchant

Credential Configs

Method	Endpoint	Description
`POST`	`/v1/credential-configs`	Create credential config
`GET`	`/v1/credential-configs/{id}`	Retrieve config by ID
`GET`	`/v1/credential-configs`	List configs with filtering
`PUT`	`/v1/credential-configs/{id}`	Update config
`DELETE`	`/v1/credential-configs/{id}`	Delete config

Payment Methods

Method	Endpoint	Description
`GET`	`/v1/payment-methods`	List available payment methods
`GET`	`/v1/payment-methods/{method}`	Get specific payment method details

Webhooks

Method	Endpoint	Description
`GET`	`/v1/webhooks/events`	List webhook event types
`POST`	`/v1/webhooks/test`	Send test webhook

Checkout API Endpoints

Session Management

Method	Endpoint	Description
`POST`	`/v1/checkout/sessions`	Create checkout session
`GET`	`/v1/checkout/sessions/{id}`	Retrieve session details
`PUT`	`/v1/checkout/sessions/{id}`	Update session

Example Checkout Session Creation

curl "https://api.orsunpay.com/v1/checkout/sessions" \
  -X POST \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "USD",
    "country": "US",
    "customer": {
      "email": "[email protected]"
    },
    "returnUrl": "https://yoursite.com/return",
    "cancelUrl": "https://yoursite.com/cancel"
  }'

const session = await fetch('https://api.orsunpay.com/v1/checkout/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,
    currency: 'USD',
    country: 'US',
    customer: {
      email: '[email protected]'
    },
    returnUrl: 'https://yoursite.com/return',
    cancelUrl: 'https://yoursite.com/cancel'
  })
});

const sessionData = await session.json();

const axios = require('axios');

const response = await axios.post(
  'https://api.orsunpay.com/v1/checkout/sessions',
  {
    amount: 5000,
    currency: 'USD',
    country: 'US',
    customer: {
      email: '[email protected]'
    },
    returnUrl: 'https://yoursite.com/return',
    cancelUrl: 'https://yoursite.com/cancel'
  },
  {
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Request Format Standards

Content Type

All requests with body content must use:

Content-Type: application/json

Authentication

Include your API key in all requests:

Authorization: Bearer your_api_key_here

Idempotency

For state-changing operations, include idempotency key:

Idempotency-Key: your-unique-key-here

Response Format Standards

Success Response

All successful API responses follow this structure:

{
  "id": "resource_id",
  "object": "transaction|customer|merchant",
  "created": "2023-11-15T10:30:00.000Z",
  "updated": "2023-11-15T10:30:00.000Z",
  // ... resource-specific fields
}

Error Response

All error responses follow this structure:

{
  "error": {
    "code": "error_code",
    "message": "Human readable error message",
    "details": {
      "field": "Additional error details"
    }
  }
}

Pagination

List Endpoints

All list endpoints support pagination using cursor-based pagination:

Request Parameters

Parameter	Type	Default	Description
`limit`	integer	10	Number of items per page (max 100)
`cursor`	string	-	Cursor for next page

Response Format

{
  "data": [...],
  "hasMore": true,
  "nextCursor": "eyJpZCI6InRyXzEyMyJ9"
}

Example Usage

# First page
curl "https://api.orsunpay.com/v1/transactions?limit=10" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Next page using cursor
curl "https://api.orsunpay.com/v1/transactions?limit=10&cursor=eyJpZCI6InRyXzEyMyJ9" \
  -H "Authorization: Bearer sk_live_your_api_key"

// First page
const firstPage = await fetch(
  'https://api.orsunpay.com/v1/transactions?limit=10',
  {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  }
);

const firstPageData = await firstPage.json();

// Next page
if (firstPageData.hasMore) {
  const nextPage = await fetch(
    `https://api.orsunpay.com/v1/transactions?limit=10&cursor=${firstPageData.nextCursor}`,
    {
      headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
    }
  );
  
  const nextPageData = await nextPage.json();
}

Filtering and Sorting

Common Filter Parameters

Parameter	Type	Example	Description
`status`	string	`SUCCESS`	Filter by status
`merchantId`	string	`mr_123`	Filter by merchant
`customerId`	string	`cu_456`	Filter by customer
`dateFrom`	ISO date	`2023-11-01T00:00:00.000Z`	Start date filter
`dateTo`	ISO date	`2023-11-30T23:59:59.999Z`	End date filter

Sorting

Use the sort parameter with field names:

# Sort by creation date (newest first)
curl "https://api.orsunpay.com/v1/transactions?sort=-createdAt"

# Sort by amount (ascending) 
curl "https://api.orsunpay.com/v1/transactions?sort=amount"

Rate Limits

Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Rate Limit Exceeded Response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after some time.",
    "details": {
      "retryAfter": 60
    }
  }
}

Compatibility Policy

Backward Compatibility

We maintain backward compatibility within major versions by:

Never removing existing fields from responses
Never changing field data types
Never requiring new mandatory fields in requests
Never changing existing endpoint behavior

Additive Changes (Non-Breaking)

We may add these without notice:

New optional fields in requests
New fields in responses
New endpoints
New optional query parameters
New webhook event types

Breaking Changes

Breaking changes require a new major version:

Removing fields from responses
Changing field data types
Adding required fields to requests
Changing endpoint URLs
Removing endpoints

We provide at least 12 months notice before deprecating any API version.

Regional Endpoints

Currently, all traffic is routed through our primary data centers:

Primary Regions

Region	Location	Status
US East	Virginia	Primary
EU West	Ireland	Secondary

Planned Expansion

Region	Location	Timeline
Asia Pacific	Singapore	Q2 2024
EU Central	Germany	Q3 2024

Service Status

Health Check Endpoints

Monitor API health using these endpoints:

# API Health
curl https://api.orsunpay.com/health

# Specific service health
curl https://api.orsunpay.com/health/transactions
curl https://api.orsunpay.com/health/webhooks

Status Page

Monitor real-time system status at:

Public Status: https://status.orsunpay.com
Incident History: Historical uptime and incidents
Maintenance Windows: Scheduled maintenance notifications

Development Tools

API Explorer

Interactive API testing available at:

Sandbox: https://sandbox-api.orsunpay.com/docs
Production: https://api.orsunpay.com/docs (read-only)

SDKs and Libraries

Official SDKs available for:

Language	Package	Installation
JavaScript	`@orsunpay/sdk-js`	`npm install @orsunpay/sdk-js`
Node.js	`@orsunpay/sdk-node`	`npm install @orsunpay/sdk-node`
Python	`orsunpay`	`pip install orsunpay`
PHP	`orsunpay/orsunpay-php`	`composer require orsunpay/orsunpay-php`

Postman Collection

Import our Postman collection for easy testing:

# Download collection
curl -o orsunpay-api.json \
  https://api.orsunpay.com/postman/collection.json

Support and Resources

For endpoint-specific questions:

API Documentation: Detailed endpoint documentation
Developer Support: [email protected]
Community Forum: https://forum.orsunpay.com
GitHub Issues: https://github.com/orsunpay/api-issues

All endpoints support both sandbox and production environments. Always test thoroughly in sandbox before using production endpoints.

​API Endpoints

​Base URLs

​API Endpoints

​Service Endpoints

​API Versioning

​Current Version: v1

​Version Format

​Core API Endpoints

​Transactions

​Customers

​Merchants

​Credential Configs

​Payment Methods

​Webhooks

​Checkout API Endpoints

​Session Management

​Example Checkout Session Creation

​Request Format Standards

​Content Type

​Authentication

​Idempotency

​Response Format Standards

​Success Response

​Error Response

​Pagination

​List Endpoints

​Request Parameters

​Response Format

​Example Usage

​Filtering and Sorting

​Common Filter Parameters

​Sorting

​Rate Limits

​Headers

​Rate Limit Exceeded Response

​Compatibility Policy

​Backward Compatibility

​Additive Changes (Non-Breaking)

​Breaking Changes

​Regional Endpoints

​Primary Regions

​Planned Expansion

​Service Status

​Health Check Endpoints

​Status Page

​Development Tools

​API Explorer

​SDKs and Libraries

​Postman Collection

​Support and Resources

API Endpoints

Base URLs

API Endpoints

Service Endpoints

API Versioning

Current Version: v1

Version Format

Core API Endpoints

Transactions

Customers

Merchants

Credential Configs

Payment Methods

Webhooks

Checkout API Endpoints

Session Management

Example Checkout Session Creation

Request Format Standards

Content Type

Authentication

Idempotency

Response Format Standards

Success Response

Error Response

Pagination

List Endpoints

Request Parameters

Response Format

Example Usage

Filtering and Sorting

Common Filter Parameters

Sorting

Rate Limits

Headers

Rate Limit Exceeded Response

Compatibility Policy

Backward Compatibility

Additive Changes (Non-Breaking)

Breaking Changes

Regional Endpoints

Primary Regions

Planned Expansion

Service Status

Health Check Endpoints

Status Page

Development Tools

API Explorer

SDKs and Libraries

Postman Collection

Support and Resources