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:
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:
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:
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:
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.
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):
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.
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:
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_actionprocessingsucceededdeclinedfailedcanceledexpired
Events are matched to a payment session via data.session_token. If the referenced transaction does not already exist, it is created automatically.
Last updated