---
title: API Basics
slug: api-basics
createdAt: 2026-11-02T00:00:00.000Z
---

This page covers the conventions shared by every Orchestration API endpoint: environments, authentication, request and response format, and identifiers. For the full endpoint reference, see the [Orchestration API reference](https://docs.forter.com/reference/create-a-payment).

## Environments

| Environment | Base URL                                     |
| ----------- | -------------------------------------------- |
| Sandbox     | `https://payments-sandbox.checkouttools.com` |
| Production  | `https://payments.checkouttools.com`         |

Sandbox and production use separate site IDs and credentials. Sandbox payments are routed to your processors' test environments, so no real money moves. See [Environments](https://docs.forter.com/reference/environments) for how sandbox and production sites are set up in the Forter Portal.

## Authentication

Authenticate every request with HTTP Basic authentication. Use your Forter **site ID** as the username and your **site secret key** as the password. These are the same credentials you use for other Forter APIs, and you'll find them on the [Credentials page](https://portal.forter.com/app/integration/credentials/) in the Forter Portal:

```http
Authorization: Basic base64(<siteId>:<siteSecretKey>)
```

```bash
curl https://payments-sandbox.checkouttools.com/api/payments/pi_v1r1a3f9c2e4b5d6478a9b0c1d2e3f4a5b6c \
  -u "$FORTER_SITE_ID:$FORTER_SITE_SECRET"
```

- Requests with missing or invalid credentials are rejected with `401 Unauthorized`.
- Call the API from your server only. Never expose your site secret key in front-end code or mobile apps.
- Every request is scoped to the authenticated site. A resource that belongs to another site returns `404 Not Found`, exactly as if it did not exist.

## Requests

- Send request bodies as JSON with `Content-Type: application/json`.
- Every `POST` request must include an `Idempotency-Key` header. See [Idempotency](docId:6evvXmGB4xaQjCtRHZlTW).
- Field names are `camelCase`. Enum values are lowercase `snake_case` (for example `requires_capture`, `requested_by_customer`). Standard codes keep their usual format, for example ISO 4217 currency codes such as `USD`.
- Unknown fields are rejected with `400 Bad Request`. Check field names carefully: a misspelled field is reported as an error, not silently ignored.
- Amounts are integers in the currency's minor unit. See [Amounts and Currencies](docId:4XfZlvFF6uU-cWHsR3eQH).

## Responses

- Fields that don't apply to a payment are **omitted**, not returned as `null`. For example, `authorizationExpiresAt` only appears while an authorization is active, and `nextAction` only appears when the customer must complete 3DS.
- Timestamps are ISO 8601 strings in UTC, and their names end in `At` (for example `createdAt` and `capturedAt`).
- The API evolves additively: new optional fields and new enum values may be added at any time. Ignore fields you don't recognize, and handle unknown enum values gracefully.

## Identifiers

| Prefix    | Resource                                          |
| --------- | ------------------------------------------------- |
| `pi_`     | Payment                                           |
| `charge_` | Capture against a payment (an entry in `charges`) |
| `refund_` | Refund                                            |

Treat IDs as opaque strings. Don't parse them or assume a fixed length. Your own order reference is `orderId`, which you provide when creating the payment. The processor's identifiers are returned separately under `processor`.

## Metadata

`POST /api/payments` accepts an optional `metadata` object of string key-value pairs for your own reference. It is stored with the payment and returned in every payment response.

- Up to 10 keys.
- Keys up to 40 characters, values up to 200 characters.
- Values must be strings.

Don't put sensitive data, such as card or personal data, in metadata.

## Tracing Requests

Every response includes an `X-Correlation-ID` header. You can also send your own `X-Correlation-ID` on the request, and it will be used instead. Include the correlation ID, together with the payment ID, when you contact Forter support about a request.

## Timeouts

Payment requests that contact a processor can take several seconds, and longer when Forter reroutes to another processor. Set your HTTP client timeout to **at least 60 seconds** for `POST` requests.

If a request times out, its outcome is unknown. Retry it with the **same** `Idempotency-Key`. Forter either returns the original result, or processes the request if it never ran. Never retry with a new key, because that can create a second payment.