API Reference (1.0.0)

Authentication

Every endpoint uses OAuth 2.0 client credentials. Request an access token, then send it as a bearer token on subsequent calls.

The token request and the calls that follow authenticate differently:

• POST /oauth2/token uses HTTP Basic authentication with your client ID and client secret.
• Every other endpoint uses Authorization: Bearer <access_token>.

X-APP-ID: <your account identifier> is required on every request, including the token request. It is issued with your credentials and sent exactly as provided.

Tokens are valid for one hour. Cache and reuse them rather than requesting one per call, and request a new token when the current one expires.

A 401 is always returned before a request is processed, so it never indicates a payment that partially completed. It is safe to request a new token and retry once. Do not retry other error responses automatically.

Environments

A staging environment is available for integration work. Staging and production are fully isolated: payments made in staging settle against sandbox processors and have no effect on production billing. Staging holds a partial copy of production reference data, so some identifiers valid in production may not resolve there.

Requests and responses

Payment requests are submitted as an array and each item is processed independently. The HTTP status stays 200 even when individual items fail, so inspect the saleStatus of every element in the response rather than relying on the status code. An item with saleStatus of ERROR did not move money.

Errors

Two kinds of error can be returned, and they are handled differently:

• Transport and authorization errors apply to every endpoint and are returned as standard HTTP status codes — 400 for a malformed request, 401 for missing or expired credentials, 403 where access is not permitted, 404 where a record does not exist, and 5xx for a temporary failure. These are described once here and are not repeated on each operation.
• Per-item business errors are specific to payment submission. They are returned inside a 200 response on the individual item, in saleResponse, and describe why that item was not accepted — for example a facility that could not be found, a missing required field, or a payment detected as a duplicate of one already submitted. Where an endpoint returns an error unique to it, that error is documented on the endpoint itself.

Not currently supported

The following are handled outside the API today, and are worth designing around rather than waiting for:

• Refunds, voids and partial payments
• Webhooks or payment status callbacks — the response to a payment request is the source of truth