> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orsunpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Endpoints

> Complete reference for Orsunpay API base URLs, versioning, and compatibility policies

# 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)

<Note>
  We're currently on version 1 (`v1`) and maintain strict backward compatibility within major versions.
</Note>

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

<CodeGroup>
  ```bash cURL theme={null}
  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": "customer@example.com"
      },
      "returnUrl": "https://yoursite.com/return",
      "cancelUrl": "https://yoursite.com/cancel"
    }'
  ```

  ```javascript JavaScript theme={null}
  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: 'customer@example.com'
      },
      returnUrl: 'https://yoursite.com/return',
      cancelUrl: 'https://yoursite.com/cancel'
    })
  });

  const sessionData = await session.json();
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.post(
    'https://api.orsunpay.com/v1/checkout/sessions',
    {
      amount: 5000,
      currency: 'USD',
      country: 'US',
      customer: {
        email: 'customer@example.com'
      },
      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);
  ```
</CodeGroup>

## Request Format Standards

### Content Type

All requests with body content must use:

```http theme={null}
Content-Type: application/json
```

### Authentication

Include your API key in all requests:

```http theme={null}
Authorization: Bearer your_api_key_here
```

### Idempotency

For state-changing operations, include idempotency key:

```http theme={null}
Idempotency-Key: your-unique-key-here
```

## Response Format Standards

### Success Response

All successful API responses follow this structure:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```json theme={null}
{
  "data": [...],
  "hasMore": true,
  "nextCursor": "eyJpZCI6InRyXzEyMyJ9"
}
```

#### Example Usage

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```javascript JavaScript theme={null}
  // 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();
  }
  ```
</CodeGroup>

## 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:

```bash theme={null}
# 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:

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200
```

### Rate Limit Exceeded Response

```json theme={null}
{
  "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

<Warning>
  We provide at least 12 months notice before deprecating any API version.
</Warning>

## 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:

```bash theme={null}
# 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](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](https://sandbox-api.orsunpay.com/docs)
* **Production**: [https://api.orsunpay.com/docs](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:

```bash theme={null}
# 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**: [dev-support@orsunpay.com](mailto:dev-support@orsunpay.com)
* **Community Forum**: [https://forum.orsunpay.com](https://forum.orsunpay.com)
* **GitHub Issues**: [https://github.com/orsunpay/api-issues](https://github.com/orsunpay/api-issues)

<Note>
  All endpoints support both sandbox and production environments. Always test thoroughly in sandbox before using production endpoints.
</Note>