Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Beta

Payment setting externals

The payment setting external object and the allowed CRUD operations on the related resource endpoint

External payment settings are the custom gateway subtype of payment settings. They allow you to integrate any payment provider that is not supported out-of-the-box by implementing a simple webhook-based contract that Commerce Layer calls for each payment operation.

URLs

Setting up an external payment setting requires the following endpoint URLs:

Attribute
Description
Required

authorization_url

Endpoint Commerce Layer calls to authorize a payment.

capture_url

Endpoint called to capture an authorized payment.

void_url

Endpoint called to void an authorization.

refund_url

Endpoint called to issue a refund.

session_url

Endpoint called when a payment session is created — allows the external provider to register the session and return a reference token used to correlate future async events back to the correct session.

token_url

Endpoint called to vault a payment instrument (enables wallet support).

Capabilities

External payment settings support the following Commerce Layer features:

Feature
Supported
Notes

Payment sessions

Payment wallets

Requires token_url to be configured.

Payment links

3DS / SCA

Depends on the external provider's implementation.

Request signing

Commerce Layer signs all outbound requests with HMAC-SHA256 using the shared_secret. The signature is included in the X-CommerceLayer-Signature header so your endpoint can verify the request authenticity.

Idempotency

Requests to authorization_url, capture_url, void_url, and refund_url carry an X-CommerceLayer-Idempotency-Key header. When a new transaction matches an open one, Commerce Layer sends the same value again, so your endpoint should treat a key it has seen before as the operation it already performed and return the original outcome instead of charging or refunding again. Requests to session_url and token_url don't carry it.

Circuit breaker

External payment settings include built-in circuit breaker protection. The circuit opens once the number of accumulated failures reaches a threshold of 50 — not an error rate — and any further request is skipped while the circuit remains open. Before that threshold is reached, a successful request resets the failure count back to zero.

The circuit can also be reset manually via the _reset_circuit trigger attribute — this is the only way to close it once it has opened.

Payload enrichment

By default, the request payload sent to your external endpoint includes the order with its market, line items, shipping address, billing address, and customer. You can configure custom includes via the options attribute.

Payment instrument

To populate the payment instrument of the session, return a payment_instrument object in the successful authorization response data, next to the usual transaction fields:

Only the following keys are kept — any other key is ignored:

Key
Description

issuer

The instrument issuer (e.g. the issuing bank).

issuer_type

The kind of instrument. Defaults to external when not provided.

card_type

The card brand.

card_last_digits

The last digits of the card number.

card_expiry_month, card_expiry_year

The card expiration date.

card_holder_name

The cardholder name.

card_fingerprint

Your fingerprint identifying the card.

account_id, account_email, account_status

The account details, for non-card instruments.

With the example above, the payment session gets:

The object is read from the authorization response only, the first time the authorization succeeds — returning it on capture, void, or refund has no effect, and it never overwrites an instrument already set. For asynchronous authorizations, include it in the 202 response: webhook events don't carry it.

Wallet vaulting

If a token_url is configured, the payment setting is considered vaultable and supports payment wallets. Commerce Layer calls the token URL endpoint to vault a payment instrument on behalf of the customer. The external endpoint must return a payment_source_token and optionally a customer_token in its response data to be stored on the wallet — if you already supply it yourself when creating the wallet, that value is kept instead.

You can find more information about how this compares to the other payment providers here.

Storing the instrument during a payment

When a payment session has vaulting enabled, the authorization request sent to your authorization_url endpoint tells your integration to store the payment instrument. The request body is the payment authorization in JSON:API format, and the session it belongs to is part of its included resources, carrying the vaulting flag among its attributes:

To have Commerce Layer create the wallet, return the stored instrument in the successful authorization response data, next to the usual transaction fields, using the same keys as the token URL endpoint (payment_source_token and, optionally, customer_token):

If payment_source_token is missing, the session is paid all the same but no wallet is created. These keys are only read from the authorization response — returning them on capture, void, or refund has no effect.

Duplicate wallets

Commerce Layer deduplicates wallets by the payment_source_token your integration returns. When a payment session with vaulting enabled returns a token the customer already holds in an active wallet, the session is linked to that wallet instead of creating a new one.

To avoid duplicate wallets for the same instrument, have your integration return the same payment_source_token every time that instrument is stored for the same customer.

Webhook events

Your external endpoint can push asynchronous events to Commerce Layer — send them via POST request to the webhook_endpoint_url attribute exposed on this resource — to update payment transaction states. Each event must include an event_type, a status, and a data object with the required fields:

Event type
Required fields

AUTHORIZATION

session_token, transaction_token, amount_cents

CAPTURE

session_token, transaction_token, amount_cents, reference_transaction_token

VOID

session_token, transaction_token, reference_transaction_token

REFUND

session_token, transaction_token, amount_cents, reference_transaction_token, authorization_token

The status field must be one of:

  • requires_action

  • processing

  • succeeded

  • declined

  • failed

  • canceled

  • expired

Events are matched to a payment session via data.session_token. If the referenced transaction does not already exist, it is created automatically.

As for the outbound requests, all incoming events must be signed with HMAC-SHA256 using the shared_secret — the signature is expected in the X-CommerceLayer-Signature header.

Last updated