API Basics
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.
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 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 in the Forter Portal:
Authorization: Basic base64(<siteId>:<siteSecretKey>)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.
- 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.
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.