Getting Started

The Shift4 API is REST-based, providing a complete payment processing platform for developers. It has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

All API requests are made to the following base URL:

https://api.shift4.com

Key characteristics of the API:

• All requests must use HTTPS. Any HTTP requests will be rejected.
• Request bodies use form-encoded parameters.
• All responses are returned as JSON.
• The API operates in two modes: test and live, each with separate API keys. Test mode transactions are completely isolated from production.

The Shift4 API uses HTTP Basic Authentication. To authenticate, provide your API secret key as the username and leave the password field empty.

• Test keys start with sk_test_
• Live keys start with sk_live_

Example request:

curl https://api.shift4.com/charges -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:

The key above belongs to a shared demo account, so the examples throughout these docs are runnable as written. Substitute your own key to work against your data. The demo account predates the current prefixes, so its keys read pr_test_ and pu_test_ where yours will read sk_test_ and pk_test_.

Note the trailing colon (:) after the key -- this tells cURL to send an empty password.

Important security considerations:

• Never expose your secret key in client-side code, public repositories, or anywhere accessible to end users.
• For client-side integrations with Shift4.js, use your public keys instead (pk_test_ for test mode, pk_live_ for live mode).

The Shift4 API uses standard HTTP status codes to indicate the outcome of a request:

Error object structure:

When an error occurs, the response body contains an error object with the following fields:

{
  "error": {
    "type": "card_error",
    "code": "invalid_number",
    "message": "The card number is not a valid credit card number."
  }
}

Error types:

Card error codes:

The Shift4 API supports idempotent requests, allowing you to safely retry requests without the risk of performing the same operation twice. This is especially important for payment operations.

To make an idempotent request, include the Idempotency-Key header with a unique value (UUIDs are recommended):

curl https://api.shift4.com/charges \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -H "Idempotency-Key: unique_key_123" \
  -d "amount=1000" \
  -d "currency=USD" \
  -d "card=tok_example"

Key details:

• Idempotency keys are valid for 24 hours.
• If a duplicate request is detected, the server responds with the original response and includes an Idempotent-Replayed: true header.
• Only POST requests support idempotency keys. GET and DELETE requests are inherently idempotent.

Most Shift4 objects support a metadata parameter, allowing you to attach custom key-value pairs to resources.

• Up to 20 key-value pairs per object.
• Keys can be up to 40 characters long.
• Values can be up to 500 characters long.
• Useful for storing reference IDs from your own system (e.g., order IDs, user IDs).

Example:

curl https://api.shift4.com/charges \
  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
  -d "amount=1000" \
  -d "currency=USD" \
  -d "card=tok_example" \
  -d "metadata[order_id]=12345" \
  -d "metadata[customer_email]=user@example.com"

Metadata is not used by Shift4 for any processing -- it is purely for your own record-keeping.

All list endpoints return paginated results using cursor-based pagination.

Query parameters:

Example response:

{
  "list": [
    { "id": "char_7Hd8sK2mNpQ4rLbVx0TfYcWs", "amount": 1000, "currency": "USD" },
    { "id": "char_9x2Kd8bViQ0rLmNpQ4TsHfYc", "amount": 2500, "currency": "USD" }
  ],
  "hasMore": true
}

When hasMore is true, pass the id of the last item in the list array as the startingAfterId parameter to retrieve the next page.