Payments

The complete payment flow — from discovering payment options through paying for an order, managing sources, tipping, and promotions.

🔒 Certified Partners only. Creating orders and processing payments through the API is restricted to certified partners. If you are not certified, use the Checkout Handoff instead — it needs no certification and hands the shopper to Blaze-hosted checkout with the cart intact. To apply for certification, contact your Blaze account manager or ecomsupport@blaze.me. Full list of restricted operations: Access Tiers.

What you'll learn

How the payment flow works end-to-end: payment options → customer token → source → session → pay
How payment providers are abstracted behind the {service} parameter
How to manage payment sources (list, add, update, delete)
How to create payment sessions and pay for an order
How tipping and payment promotions work
v1 vs v2 source listing differences
Common payment error scenarios and their error codes

Prerequisites

A Store UUID (staging: e87437f2-3e35-4738-af5e-6307e368255c)
A valid JWT token — see the Authentication guide
An order created via cart checkout — see the Cart & Checkout guide

All payment endpoints use the jwt_authenticated pipeline — a valid token is required.

Payment Flow Overview

The typical payment flow follows these steps:

Get payment options — discover which payment providers the store supports
Get customer token — obtain a provider-specific token for the customer (provider-dependent)
Create/register a customer — upsert the customer record in the external provider
Add a payment source — register a payment method (card, bank account, etc.)
Create a payment session — initialize a payment session with the provider (provider-dependent)
Pay for an order — charge the order using the payment source

Not all steps are required for every provider. Some providers (e.g. Stronghold) need a customer token step, while others (e.g. Adyen) need a session step. The specific requirements depend on the provider.

Payment Providers

All payment endpoints use a {service} path parameter that identifies the provider. The API abstracts provider-specific logic behind a common interface.

Supported {service} values:

adyen — Adyen (card payments, 3DS)
aeropay — AeroPay (ACH/bank transfers)
stronghold — Stronghold (ACH payments)
moneris — Moneris (card payments, 3DS)
swifter — Swifter (digital payments)
ledgergreen — LedgerGreen (lending)
merrco — Merrco (card payments)
spence — Spence (digital payments)
greenbax — Greenbax (digital payments)
blazepay_widget — BlazePay Widget (embedded payment widget)

The same endpoint paths work across all providers — only the {service} segment changes.

Step 1: Get Payment Options

Discover which payment methods are configured for the store.

`GET /api/v1/store/payment-options`

curl -X GET https://ecom-api.staging.blaze.me/api/v1/store/payment-options \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c"

This endpoint uses the jwt_optional_authenticated pipeline — no token is strictly required. It returns the list of payment options enabled for the store, including which external services are available.

Step 2: Get Payment Customer Token

Some providers require a customer-specific token before adding sources or making payments.

`GET /api/v1/store/payments/{service}/token`

Auth: jwt_authenticated

cURL

curl -X GET https://ecom-api.staging.blaze.me/api/v1/store/payments/stronghold/token \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "data": {
    "id": null,
    "type": "payments_token",
    "attributes": {
      "mfa": false,
      "token": "pay_tok_abc123def456...",
      "expiry": "2026-06-01T00:00:00Z"
    }
  }
}

Error codes

bad_request (400) — Invalid payment option. Returned when {service} is not a recognized provider.
payment_customer_not_found (400) — The user does not have a customer record with this provider yet.

Step 3: Create / Register Payment Customer

Register or update the user's customer record with an external payment provider. This links the cart to the provider so the payment can be processed.

`PUT /api/v1/store/payments/{service}/customers`

Auth: jwt_authenticated

cURL

curl -X PUT https://ecom-api.staging.blaze.me/api/v1/store/payments/adyen/customers \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "payment_customers",
      "id": "",
      "attributes": {},
      "relationships": {
        "cart": {
          "data": {
            "type": "carts",
            "id": "CART_UUID"
          }
        }
      }
    }
  }'

JavaScript (fetch)

const STORE_UUID = "e87437f2-3e35-4738-af5e-6307e368255c";
const BASE_URL = "https://ecom-api.staging.blaze.me";

const response = await fetch(
  `${BASE_URL}/api/v1/store/payments/adyen/customers`,
  {
    method: "PUT",
    headers: {
      "Content-Type": "application/vnd.api+json",
      Accept: "application/vnd.api+json",
      "X-Store": STORE_UUID,
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      data: {
        type: "payment_customers",
        id: "",
        attributes: {},
        relationships: {
          cart: {
            data: { type: "carts", id: cartId },
          },
        },
      },
    }),
  },
);

const { data } = await response.json();
console.log(`Customer registered: ${data.id}`);

Response

{
  "data": {
    "id": "customer-uuid",
    "type": "payment_customers",
    "attributes": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone_number": "+15551234567",
      "external_service": "adyen",
      "external_id": "ext_cust_abc123",
      "is_confirmed": true,
      "extra_content": null
    }
  }
}

Error codes

bad_request (400) — Invalid payment option. Returned when {service} is not recognized.
no_match_for_payment_customer (400) — Customer does not match the one from the external payment source data.
cart_data_required_for_customer (400) — Additional shopping cart data is required for this payment processor. Returned when the cart relationship is missing and the provider requires it.

Step 4: Manage Payment Sources

Payment sources represent saved payment methods (credit cards, bank accounts, etc.).

List Sources (v1)

`GET /api/v1/store/payments/{service}/sources`

Returns sources for a specific provider.

Auth: jwt_authenticated

cURL

curl -X GET https://ecom-api.staging.blaze.me/api/v1/store/payments/adyen/sources \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

JavaScript (fetch)

const response = await fetch(
  `${BASE_URL}/api/v1/store/payments/adyen/sources`,
  {
    headers: {
      "Content-Type": "application/vnd.api+json",
      Accept: "application/vnd.api+json",
      "X-Store": STORE_UUID,
      Authorization: `Bearer ${token}`,
    },
  },
);

const { data } = await response.json();
console.log(`Found ${Array.isArray(data) ? data.length : 1} source(s)`);

Response

{
  "data": [
    {
      "id": "source-uuid",
      "type": "payment_sources",
      "attributes": {
        "label": "Visa",
        "label_display": "Visa •••• 4242",
        "active": true,
        "external_service": "adyen",
        "external_id": "ext_src_abc123",
        "type": "credit_card",
        "provider": "visa",
        "provider_display": "Visa",
        "mask": "4242",
        "account_type": null,
        "is_default": true,
        "expiry_date": "12/2027",
        "cardholder_name": "Jane Doe",
        "is_expired": false
      }
    }
  ]
}

List Sources (v2) — All Providers

`GET /api/v2/store/payments/sources`

Returns sources grouped by provider in a single request. No {service} parameter needed.

Auth: jwt_authenticated

curl -X GET https://ecom-api.staging.blaze.me/api/v2/store/payments/sources \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "data": {
    "id": "all_payment_sources",
    "type": "all_payment_sources",
    "attributes": {
      "adyen": [
        {
          "id": "source-uuid",
          "label": "Visa",
          "label_display": "Visa •••• 4242",
          "active": true,
          "external_service": "adyen",
          "type": "credit_card",
          "mask": "4242",
          "is_default": true,
          "is_expired": false
        }
      ],
      "stronghold": []
    }
  }
}

Tip: Use v2 when you need to show all saved payment methods across providers. Use v1 when working with a single provider.

Add a Payment Source

`POST /api/v1/store/payments/{service}/sources`

Auth: jwt_authenticated

The exact attributes required vary by provider. Common fields include token, external_id, type, and is_default.

cURL

curl -X POST https://ecom-api.staging.blaze.me/api/v1/store/payments/adyen/sources \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "payment_sources",
      "attributes": {
        "token": "tok_abc123...",
        "type": "credit_card",
        "is_default": true
      }
    }
  }'

JavaScript (fetch)

const response = await fetch(
  `${BASE_URL}/api/v1/store/payments/adyen/sources`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/vnd.api+json",
      Accept: "application/vnd.api+json",
      "X-Store": STORE_UUID,
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      data: {
        type: "payment_sources",
        attributes: {
          token: "tok_abc123...",
          type: "credit_card",
          is_default: true,
        },
      },
    }),
  },
);

const { data } = await response.json();
console.log(`Source added: ${data.id}`);

Response

{
  "data": {
    "id": "source-uuid",
    "type": "payment_sources",
    "attributes": {
      "label": "Visa",
      "label_display": "Visa •••• 4242",
      "active": true,
      "external_service": "adyen",
      "external_id": "ext_src_abc123",
      "type": "credit_card",
      "provider": "visa",
      "provider_display": "Visa",
      "mask": "4242",
      "account_type": null,
      "is_default": true,
      "expiry_date": "12/2027",
      "cardholder_name": "Jane Doe",
      "is_expired": false
    }
  }
}

Error codes

bad_request (400) — Invalid payment option. The {service} value is not recognized.
invalid_payment_source (400) — Some required fields are missing for adding the payment source. Check the provider-specific requirements.
guest_cannot_add_source (400) — Cannot add sources in guest checkout. The user must be authenticated.
expired_payment_token (400) — The payment card has expired. The token provided refers to an expired card.
invalid_payment_token (400) — The payment card is invalid. The token could not be validated by the provider.

Update a Payment Source

`PATCH /api/v1/store/payments/{service}/sources/{id}`

Used to update source properties, such as marking a source as the default.

Auth: jwt_authenticated

curl -X PATCH https://ecom-api.staging.blaze.me/api/v1/store/payments/adyen/sources/SOURCE_ID \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "id": "SOURCE_ID",
      "type": "payment_sources",
      "attributes": {
        "is_default": true
      }
    }
  }'

Error codes

payment_source_not_found (400) — The source ID does not match any source for this user and service.

Delete a Payment Source

`DELETE /api/v1/store/payments/{service}/sources/{id}`

Auth: jwt_authenticated

curl -X DELETE https://ecom-api.staging.blaze.me/api/v1/store/payments/adyen/sources/SOURCE_ID \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

Error codes

bad_request (400) — Invalid payment option.
payment_source_not_found (400) — The source does not exist for this user and provider.

Step 5: Create a Payment Session

Some providers (e.g. blazepay_widget, adyen) require creating a payment session before charging. The session ties together the store, cart, and user in the external provider.

`POST /api/v1/store/payments/{service}/sessions`

Auth: jwt_optional_authenticated — for guest checkout, pass user details in the attributes instead.

curl -X POST https://ecom-api.staging.blaze.me/api/v1/store/payments/blazepay_widget/sessions \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "payment_sessions",
      "attributes": {},
      "relationships": {
        "cart": {
          "data": {
            "type": "carts",
            "id": "CART_UUID"
          }
        }
      }
    }
  }'

For guest checkout (no JWT), include user details in attributes:

{
  "data": {
    "type": "payment_sessions",
    "attributes": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone_number": "+15551234567"
    },
    "relationships": {
      "cart": {
        "data": { "type": "carts", "id": "CART_UUID" }
      }
    }
  }
}

Response (201 Created)

{
  "data": {
    "id": "session-uuid",
    "type": "payment_session",
    "attributes": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

Error codes

bad_request (400) — Invalid payment option or invalid request parameters.
not_found_payment_config (404) — Payment configuration was not found for the store. The provider is not configured.
not_found (404) — The cart UUID does not match any existing cart.

Step 6: Pay for an Order

After the order is created (via the Cart & Checkout flow), charge it using the payment source.

`POST /api/v1/store/payments/{service}/orders/{uuid}/pay`

Auth: jwt_authenticated

cURL

curl -X POST https://ecom-api.staging.blaze.me/api/v1/store/payments/adyen/orders/ORDER_UUID/pay \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "payments_charge",
      "attributes": {
        "source_id": "SOURCE_UUID",
        "postal_code": "90210"
      }
    }
  }'

JavaScript (fetch)

const response = await fetch(
  `${BASE_URL}/api/v1/store/payments/adyen/orders/${orderUuid}/pay`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/vnd.api+json",
      Accept: "application/vnd.api+json",
      "X-Store": STORE_UUID,
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      data: {
        type: "payments_charge",
        attributes: {
          source_id: sourceId,
          postal_code: "90210",
        },
      },
    }),
  },
);

const result = await response.json();
if (response.ok) {
  console.log(`Payment status: ${result.data.attributes.status}`);
} else {
  console.error("Payment failed:", result.errors);
}

The attributes vary by provider, but common fields include:

source_id — UUID of the payment source to charge
postal_code — billing postal code (required by some providers)
payment_session_id — session ID from the session creation step (for providers that use sessions)
payment_session_payment_id — external payment ID from the provider widget

Response

{
  "data": {
    "id": "charge-uuid",
    "type": "payment_charges",
    "attributes": {
      "status": "authorized",
      "type": "charge",
      "fee": { "amount": 0, "currency": "USD" },
      "convenience_fee": { "amount": 0, "currency": "USD" },
      "amount_without_convenience_fee": { "amount": 4928, "currency": "USD" },
      "description": null,
      "external_id": "ext_charge_abc123",
      "external_service": "adyen",
      "amount": { "amount": 4928, "currency": "USD" },
      "external_url": null,
      "created_at": "2026-05-30T20:00:00Z",
      "authorized_at": "2026-05-30T20:00:01Z",
      "captured_at": null,
      "updated_at": "2026-05-30T20:00:01Z",
      "guest_payment_source": null,
      "is_3ds_authenticated": false,
      "service_external_id": null,
      "service_external_url": null,
      "credit": null
    },
    "relationships": {
      "payment_customer": {
        "data": { "id": "customer-uuid", "type": "payment_customers" }
      },
      "payment_source": {
        "data": { "id": "source-uuid", "type": "payment_sources" }
      },
      "payment_tip": { "data": null }
    }
  },
  "included": [
    {
      "id": "customer-uuid",
      "type": "payment_customers",
      "attributes": {
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "external_service": "adyen",
        "external_id": "ext_cust_abc123"
      }
    },
    {
      "id": "source-uuid",
      "type": "payment_sources",
      "attributes": {
        "label": "Visa",
        "mask": "4242",
        "is_default": true,
        "is_expired": false
      }
    }
  ]
}

Charge statuses:

authorized — payment authorized, pending capture
captured — payment captured (funds collected)
failed — payment failed

Error codes

order_already_paid (400) — This order has already been paid.
order_user_mismatch (400) — The order belongs to another user. The JWT user must match the order owner.
payment_failed (400) — Payment authorization failed. The provider declined the charge. The error detail may include a provider-specific message.
charge_not_authorized (400) — Payment not yet authorized. Occurs when trying to capture a payment that hasn't been authorized.
charge_canceled (400) — Payment canceled by the provider.
missing_payment_source (400) — Online payment requires a payment source. The source_id is missing or invalid.
missing_payment_source_identifier (400) — Online payment requires a payment source ID or token.
expired_payment_token (400) — Online payment card has expired.
invalid_payment_token (400) — Online payment card is invalid.
payment_source_not_found (400) — Online payment source not found.
missing_payment_postal_code (400) — Online payment requires a postal code (provider-dependent).
missing_payment_cres (400) — Invalid challenge result (cres). Occurs during 3DS authentication flow.
missing_payment_cavv (400) — Can't authenticate cardholder. 3DS verification failed.
missing_cardholder_name (400) — Missing cardholder name.
missing_billing_address (400) — Billing address is required (provider-dependent).
not_found (404) — Order not found for the given UUID.

Step 7: External Auth (3DS)

Some providers (e.g. Adyen, Moneris) require 3D Secure authentication. This endpoint handles the challenge/response flow.

`POST /api/v1/store/payments/{service}/sources/external-auth`

Auth: jwt_optional_authenticated

curl -X POST https://ecom-api.staging.blaze.me/api/v1/store/payments/adyen/sources/external-auth \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "payment_external_auth",
      "id": "",
      "attributes": {
        "challenge_screen_width": 600,
        "challenge_screen_height": 400
      },
      "relationships": {
        "cart": {
          "data": {
            "type": "carts",
            "id": "CART_UUID"
          }
        }
      }
    }
  }'

For existing sources, use the path with source ID:

`POST /api/v1/store/payments/{service}/sources/{source_id}/external-auth`

This variant attaches the auth verification to a specific existing payment source.

Tipping

Add a tip to a paid order. Tips are processed through the same payment provider.

`POST /api/v1/store/payments/{service}/tip`

Auth: jwt_authenticated

curl -X POST https://ecom-api.staging.blaze.me/api/v1/store/payments/adyen/tip \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "payment_sources",
      "attributes": {
        "external_id": "charge-external-id",
        "percentage": 15
      }
    }
  }'

Response

{
  "data": {
    "id": "tip-uuid",
    "type": "payment_tips",
    "attributes": {
      "status": "captured",
      "beneficiary_name": "Store Name",
      "fee": { "amount": 0, "currency": "USD" },
      "amount": { "amount": 740, "currency": "USD" },
      "external_id": "ext_tip_abc123",
      "external_service": "adyen",
      "created_at": "2026-05-30T20:05:00Z",
      "authorized_at": "2026-05-30T20:05:00Z",
      "captured_at": "2026-05-30T20:05:01Z",
      "percentage": 15
    },
    "relationships": {
      "payment_source": {
        "data": { "id": "source-uuid", "type": "payment_sources" }
      }
    }
  }
}

Error codes

tips_not_allowed (400) — Tips are not allowed for the selected payment option.
already_tipped (400) — Tip already processed. Each order can only be tipped once.
bad_request (400) — Invalid payment option.

Payment Promotions

Some payment providers offer their own promotional discounts (e.g., "Save $5 when you pay with Aeropay").

List Promotions

`GET /api/v1/store/payments/{service}/promotions`

Auth: jwt_authenticated

Supports pagination with limit and offset query parameters.

curl -X GET "https://ecom-api.staging.blaze.me/api/v1/store/payments/aeropay/promotions?limit=10&offset=0" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "data": [
    {
      "id": "promo-external-id",
      "type": "payment_promotions",
      "attributes": {
        "name": "Save $5 with AeroPay",
        "title": "Save $5 with AeroPay",
        "description": "You'll save $5 in this payment. Valid until Jun 30, 2026, 11:59 PM",
        "start_date": "2026-01-01T00:00:00Z",
        "end_date": "2026-06-30T23:59:59Z",
        "promotion_type": "discount",
        "benefit_type": "fixed",
        "immediate_use": true,
        "fixed_amount": { "amount": 500, "currency": "USD" },
        "first_purchase_only": false,
        "single_use": false,
        "min_charge_amount": null,
        "disabled_on": null,
        "savings": { "amount": 500, "currency": "USD" },
        "savings_display": "You're saving $5 OFF with Aeropay"
      }
    }
  ]
}

Error codes

promotions_not_allowed (400) — Promotions are not allowed for the selected payment option. The store's payment option has allows_promotions disabled.
bad_request (400) — Invalid payment option.
payment_option_not_found (400) — The payment option for this service was not found in the store configuration.

Check Redeemable Promotions

Check which promotions can be redeemed for a given charge amount.

`POST /api/v1/store/payments/{service}/promotions/redeemable`

Auth: jwt_authenticated

curl -X POST https://ecom-api.staging.blaze.me/api/v1/store/payments/aeropay/promotions/redeemable \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "payment_redeemable_promotions",
      "id": "",
      "attributes": {
        "charge_amount": 4928
      }
    }
  }'

Returns the same promotion format as the list endpoint, filtered to promotions that are redeemable for the specified amount.

Order Payment Charges

View the payment charges associated with an order.

`GET /api/v1/store/orders/{uuid}/payment/charges`

Auth: jwt_authenticated

curl -X GET https://ecom-api.staging.blaze.me/api/v1/store/orders/ORDER_UUID/payment/charges \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns a list of payment_charges for the order, including the related customer, source, and tip.

Payment Configuration

Get the provider configuration for the store. This returns settings like supported card types, fee structures, etc.

`GET /api/v1/store/payments/{service}/configuration`

Auth: jwt_optional_authenticated

curl -X GET https://ecom-api.staging.blaze.me/api/v1/store/payments/adyen/configuration \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c"

`GET /api/v1/store/integrations/payments/{service}/configuration`

Alternative path — returns the same data. This is the integrations-namespaced version.

Common Error Scenarios

All payment errors follow the standard JSON error format:

{
  "errors": [
    {
      "code": "error_code",
      "status": "400",
      "detail": "Human-readable error message",
      "source": { "pointer": "/data/attributes/field_name" }
    }
  ]
}

Payment Processing Errors

payment_failed (400) — Payment authorization or capture failed. The detail field may include a provider-specific reason.
charge_not_authorized (400) — Payment not yet authorized. Attempting an operation that requires prior authorization.
charge_canceled (400) — Payment canceled by the provider.
order_already_paid (400) — The order has already been paid. Cannot charge the same order twice.
order_already_completed (400) — The order has already been completed.

Source & Token Errors

missing_payment_source (400) — No payment source provided for an online payment.
missing_payment_source_identifier (400) — Neither a source ID nor a token was provided.
payment_source_not_found (400) — The referenced payment source does not exist.
invalid_payment_source (400) — Required fields are missing for adding a payment source.
expired_payment_token (400) — The payment card has expired.
invalid_payment_token (400) — The payment card is invalid.
guest_cannot_add_source (400) — Cannot add payment sources during guest checkout.
multiple_bank_accounts (400) — Only a single active bank account is supported.

Authentication & Authorization Errors

missing_payment_postal_code (400) — Online payment requires a postal code.
missing_payment_cres (400) — Invalid 3DS challenge result.
missing_payment_cavv (400) — Cannot authenticate cardholder (3DS failure).
missing_cardholder_name (400) — Missing cardholder name.
missing_billing_address (400) — Billing address is required.
missing_customer_signature (400) — Missing customer signature (provider-specific).
missing_customer_auth_key (400) — Missing customer auth key (provider-specific).

Configuration Errors

not_found_payment_config (404) — Payment configuration not found for the store.
invalid_payment_config (400) — External payment configuration is invalid.
inactive_service_config (400) — The provider configuration is inactive.
missing_service_config (400) — The provider configuration is missing.
no_payment_method_available (400) — No payment method available for this store.

Order Errors

order_user_mismatch (400) — The order belongs to a different user than the authenticated one.

Complete Payment Flow Example

Here's the typical end-to-end sequence:

Get payment options → GET /api/v1/store/payment-options
Register customer → PUT /api/v1/store/payments/{service}/customers (with cart relationship)
Get customer token → GET /api/v1/store/payments/{service}/token (if provider requires it)
Add payment source → POST /api/v1/store/payments/{service}/sources
Create payment session → POST /api/v1/store/payments/{service}/sessions (if provider requires it)
Handle 3DS → POST /api/v1/store/payments/{service}/sources/external-auth (if required)
Pay for order → POST /api/v1/store/payments/{service}/orders/{uuid}/pay
Add tip → POST /api/v1/store/payments/{service}/tip (optional)
View charges → GET /api/v1/store/orders/{uuid}/payment/charges

What's Next?

Cart & Checkout: Build the cart before paying — see the Cart & Checkout guide
Authentication: Set up JWT tokens — see the Authentication guide
Store & Delivery: Configure delivery options — see the Store & Delivery guide

For request/response format details, see the General Concepts guide.

User Accounts

Webhooks