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

# API Reference

> Complete endpoint documentation for the Orchestra API.

This reference documents all Orchestra API endpoints. Not sure which integration approach is right for you? See [REST API vs Payments Library](/concepts/api-vs-library).

## Base URL

All API requests use the same base URL for both production and sandbox:

```
https://api.orchestrasolutions.com
```

All request and response bodies are JSON format.

## Authentication

Authenticate all API requests with your API key (created through the [Orchestra Portal](https://portal.orchestrasolutions.com/)). Include it in the `X-Api-Key` header:

```bash theme={null}
curl -X GET "https://api.orchestrasolutions.com/PaymentGateway" \
  -H "X-Api-Key: YOUR_API_KEY"
```

***

## Choose Your Path

<CardGroup cols={2}>
  <Card title="REST API" icon="code" href="#rest-api-endpoints">
    Direct HTTP calls for charges, refunds, tokenization. You handle card collection and UI.
  </Card>

  <Card title="Payments Library" icon="browser" href="#payments-library-endpoints">
    Backend endpoints for the JavaScript library. The library handles card entry UI.
  </Card>
</CardGroup>

***

## REST API Endpoints

Use these endpoints when integrating via direct HTTP calls from your backend.

<CardGroup cols={2}>
  <Card title="Payment Operations" icon="credit-card" href="/api-reference/paymentgateway/overview">
    Charge, authorize, capture, refund, and void transactions.
  </Card>

  <Card title="String Tokens" icon="lock" href="/api-reference/stringtokens/overview">
    Tokenize and retrieve sensitive strings (card numbers, etc).
  </Card>

  <Card title="Payment Gateway Accounts" icon="building-columns" href="/api-reference/paymentgatewayaccounts/overview">
    Store and manage your payment provider credentials.
  </Card>

  <Card title="Utilities" icon="wrench" href="/api-reference/utils/validate-apikey">
    Validate API key, list supported gateways.
  </Card>
</CardGroup>

***

## Payments Library Endpoints

Use these endpoints when integrating via the [JavaScript Payments Library](/guides/library/setup). Your server calls these endpoints; the client-side library handles UI.

<CardGroup cols={2}>
  <Card title="Start Session" icon="play" href="/api-reference/ewalletoperations/start-an-ewallet-session">
    Create a payment session for the client-side library.
  </Card>

  <Card title="Validate Results" icon="check" href="/api-reference/ewalletoperations/validate-operation-results">
    Verify payment results returned from the library.
  </Card>

  <Card title="Payment Gateway Accounts" icon="building-columns" href="/api-reference/paymentgatewayaccounts/overview">
    Store and manage your payment provider credentials.
  </Card>

  <Card title="eWallet Accounts" icon="store" href="/guides/library/store-merchant-account">
    Configure accounts for Apple Pay, Google Pay, PayPal, and more.
  </Card>
</CardGroup>

***

## Response Codes

Orchestra API endpoints use two response patterns:

| Pattern   | Status Code    | Used By                                                       | Meaning                                                                       |
| --------- | -------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Async** | `202 Accepted` | Payment operations (charge, authorize, capture, refund, void) | Request forwarded to payment gateway. Check response body for gateway result. |
| **Sync**  | `201 Created`  | StringTokens (create)                                         | Operation completed. Resource created in Orchestra.                           |
| **Sync**  | `200 OK`       | GET operations, status checks                                 | Operation completed successfully.                                             |

### Common Error Codes

| Code  | Description                                                 |
| ----- | ----------------------------------------------------------- |
| `400` | Bad request - invalid parameters                            |
| `401` | Not authenticated - invalid or missing API key              |
| `404` | Resource not found                                          |
| `409` | Conflict - rejected by payment gateway or validation failed |
| `500` | Internal server error                                       |
| `503` | Temporary failure - retry with exponential backoff          |

<Note>
  Payment operations return `202` because they're forwarded to external gateways asynchronously. The response body contains the gateway's result. StringTokens returns `201` because tokens are stored synchronously in Orchestra's vault.
</Note>

***

## OpenAPI Specification

The Orchestra API is fully described in an OpenAPI 3.0 specification file. You can use this to:

* **Import into Postman** or other API clients for quick testing and exploration
* **Generate client libraries** in your preferred language using tools like OpenAPI Generator
* **Enable IDE autocomplete** for API requests in supported editors
* **Build integrations** with API management platforms

<Card title="Download OpenAPI Spec" icon="file-code" color="#FF6C37" href="https://api.orchestrasolutions.com/swagger/1.0/swagger.json">
  OAS 3.0 format. Use with Postman, client generators, or your IDE
</Card>