Commerce Payment Integration

Commerce Payment Integration

This skill activates when a practitioner needs to write or debug Apex code that connects a Salesforce B2B or D2C Commerce store to a payment gateway using the CommercePayments Apex namespace. It covers the full adapter lifecycle from tokenization through capture and refund, PCI isolation patterns, and the decision between the three supported integration paths.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the org API version is v55.0 or higher — the CommercePayments namespace was introduced in that release.
• Identify which integration path applies: Salesforce Payments (native Stripe, no custom Apex required), a vetted AppExchange payment package, or a fully custom CommercePayments Apex adapter. Custom Apex is only necessary when neither of the first two paths supports the target gateway.
• Verify the store is a B2B Commerce or D2C Commerce store — not a legacy B2B store (Aura-based) which uses a different checkout model.
• Confirm whether digital wallets (Apple Pay, Google Pay) are required. Only Salesforce Payments (Stripe path) natively supports Apple Pay; custom adapters must handle wallet tokenization explicitly.
• Check whether the existing checkout configuration uses sfdc_checkout.CartPaymentAuthorize — if so, that is the legacy admin-configured path covered by admin/commerce-checkout-configuration, not this skill.

Core Concepts

The CommercePayments Namespace and Gateway Adapter Contract

The CommercePayments Apex namespace provides the interfaces, request/response types, and enums that form the contract between Salesforce Commerce checkout and a payment gateway. Every custom gateway adapter must implement CommercePayments.PaymentGatewayAdapter and its single entry point: processRequest(CommercePayments.PaymentGatewayContext context). The platform calls this method at every payment lifecycle stage; the adapter inspects context.getPaymentRequestType() to determine which operation to perform and returns a concrete subtype of CommercePayments.GatewayResponse.

The six RequestType values the platform can pass are:

An adapter that does not handle all six will throw an unhandled branch at runtime for any request type the store triggers. At minimum, Tokenize, Authorization, and Capture must be implemented for a functional checkout.

PCI Compliance Through Cross-Domain Tokenization

The most critical architectural constraint is that raw card data — card numbers (PAN), CVV, and expiry — must never pass through Salesforce servers. The Commerce payment framework enforces this by delegating card capture entirely to a cross-domain client-side component (an iframe or redirect) owned and hosted by the payment provider. The provider's JavaScript captures the card details directly and returns a gateway-specific payment method token or nonce. The Apex adapter receives only this opaque token reference — it never sees card data. This is the platform-enforced PCI DSS scope reduction mechanism.

Any design that routes raw card data through Apex — even transiently — violates PCI DSS and breaks the tokenization contract. Named Credentials must be used for gateway API credentials; they must never be stored in Custom Settings or hardcoded.

Three Integration Paths

Path 1 — Salesforce Payments (Stripe): Enabled through Store Setup with no custom Apex. Supports Stripe payment methods including cards and Apple Pay. Requires a Salesforce Payments account. Lowest engineering effort; least flexibility.

Path 2 — AppExchange Payment Package: A vetted third-party package that ships a pre-built CommercePayments adapter for a specific gateway (e.g., Adyen, Braintree, CyberSource). The adapter code is managed and upgraded by the ISV. Appropriate when the target gateway has a published package.

Path 3 — Custom CommercePayments Apex Adapter: Required only when no AppExchange package covers the target gateway, or when bespoke authorization logic is needed. The developer authors and maintains the full adapter class. This is the path this skill covers in detail.

Common Patterns

Pattern: Full Lifecycle Adapter with Named Credential Callout

When to use: A custom gateway requires supporting Tokenize, Authorization, Capture, ReferencedRefund, and AuthorizationReversal.

How it works:

global class AcmeGatewayAdapter implements CommercePayments.PaymentGatewayAdapter {

    global CommercePayments.GatewayResponse processRequest(
            CommercePayments.PaymentGatewayContext context) {

        CommercePayments.RequestType reqType = context.getPaymentRequestType();

        if (reqType == CommercePayments.RequestType.Tokenize) {
            return handleTokenize(
                (CommercePayments.PaymentMethodTokenizationRequest) context.getPaymentRequest());
        } else if (reqType == CommercePayments.RequestType.Authorization) {
            return handleAuthorization(
                (CommercePayments.AuthorizationRequest) context.getPaymentRequest());
        } else if (reqType == CommercePayments.RequestType.Capture) {
            return handleCapture(
                (CommercePayments.CaptureRequest) context.getPaymentRequest());
        } else if (reqType == CommercePayments.RequestType.ReferencedRefund) {
            return handleRefund(
                (CommercePayments.ReferencedRefundRequest) context.getPaymentRequest());
        } else if (reqType == CommercePayments.RequestType.AuthorizationReversal) {
            return handleReversal(
                (CommercePayments.AuthorizationReversalRequest) context.getPaymentRequest());
        } else if (reqType == CommercePayments.RequestType.PostAuthorization) {
            return handlePostAuth(
                (CommercePayments.PostAuthorizationRequest) context.getPaymentRequest());
        }
        // Explicit fallback — should never be reached if all types are handled
        CommercePayments.GatewayErrorResponse errResp =
            new CommercePayments.GatewayErrorResponse();
        errResp.setGatewayMessage('Unsupported request type: ' + reqType);
        return errResp;
    }

    private CommercePayments.GatewayResponse handleAuthorization(
            CommercePayments.AuthorizationRequest req) {
        // Callout uses Named Credential — no hardcoded secrets
        HttpRequest httpReq = new HttpRequest();
        httpReq.setEndpoint('callout:Acme_Gateway/authorize');
        httpReq.setMethod('POST');
        // ... build request body, call gateway, parse response ...
        CommercePayments.AuthorizationResponse resp =
            new CommercePayments.AuthorizationResponse();
        resp.setGatewayReferenceNumber('acme-txn-12345');
        resp.setAmount(req.getAmount());
        resp.setGatewayResultCode('00');
        resp.setSalesforceResultCodeInfo(
            CommercePayments.SalesforceResultCodes.Success);
        return resp;
    }
    // ... remaining handler methods
}

Why not the alternative: Using a single method without dispatching on RequestType means the adapter returns an incorrect response type for lifecycle steps other than the one it was built for, causing silent checkout failures.

Pattern: Payment Gateway Provider Registration via Custom Metadata

When to use: Wiring a custom adapter class to a specific Commerce store so the platform knows which Apex class to invoke.

How it works: Create a Payment Gateway Provider record (via Setup > Payment Gateway Providers) that points to the Apex adapter class. Then in the store's Payment Settings, select the registered provider. The platform reads this metadata at checkout time to determine which class to instantiate. This registration is done in Setup UI or deployed as a PaymentGatewayProvider metadata type in a SFDX/source-format project — it is not configured in Apex code itself.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Confirm integration path — Determine whether Salesforce Payments, an AppExchange package, or a custom adapter is required. Only proceed with Apex authoring if neither of the first two paths is viable. Document the chosen path and rationale.
2. Scaffold the adapter class — Create an Apex class with global access that implements CommercePayments.PaymentGatewayAdapter. Add a processRequest method with dispatch logic covering all six RequestType values. Stub each handler method to return a typed error response before adding real callout logic.
3. Configure the Named Credential — Create a Named Credential for the gateway API endpoint and credentials. Ensure the adapter's callout endpoint references callout:<NamedCredentialName>/... — never hardcode URLs or secrets.
4. Implement each handler method — For each RequestType, implement the callout, parse the gateway response, and populate the corresponding CommercePayments response object. Map gateway result codes to SalesforceResultCodes enum values (Success, Decline, SystemError, etc.).
5. Register the adapter — Create a Payment Gateway Provider record in Setup that references the Apex class name. In the store's Payment Settings, select the registered provider.
6. Write test coverage — Create a test class that uses Test.setMock(HttpCalloutMock.class, ...) to mock the gateway API. Test each RequestType branch. Minimum 75% coverage required; aim for 90%+. Verify that no test directly passes raw card data through Apex.
7. Validate PCI posture and run a full checkout — Confirm the cross-domain client component (provider-hosted iframe or redirect) handles card capture. Walk through a test order end-to-end: tokenize, authorize, capture, refund. Verify all lifecycle transitions succeed and that error paths return GatewayErrorResponse rather than throwing exceptions.

Review Checklist

Run through these before marking work in this area complete:

• Adapter implements all six RequestType branches (Tokenize, Authorization, PostAuthorization, Capture, ReferencedRefund, AuthorizationReversal)
• No raw card data (PAN, CVV, expiry) appears anywhere in Apex code, debug logs, or Custom Settings
• All gateway credentials are stored in Named Credentials — no hardcoded endpoints or API keys
• Every handler returns the correct typed CommercePayments response subclass (not a generic object or exception throw)
• Test class achieves 90%+ coverage and mocks all HTTP callouts via HttpCalloutMock
• Payment Gateway Provider metadata record is created and linked to the store
• End-to-end test order completes successfully through tokenize → authorize → capture

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. CommercePayments vs sfdc_checkout.CartPaymentAuthorize are separate interfaces — The CommercePayments.PaymentGatewayAdapter interface (used in LWR-based B2B/D2C stores, introduced ~v55.0) and sfdc_checkout.CartPaymentAuthorize (older Aura-based B2B checkout) are completely different extension points. Implementing CartPaymentAuthorize in a modern LWR store will not be invoked by the platform. Consult admin/commerce-checkout-configuration if you are on the older interface.
2. Missing RequestType branches cause silent checkout failures — The platform does not throw an obvious error if processRequest returns null or an incorrectly typed response for a given RequestType. Instead, checkout silently stalls or shows a generic error. Every branch must return a correctly typed response object even if the handler is not yet implemented.
3. Apple Pay requires Salesforce Payments — custom adapters cannot support it natively — Apple Pay domain verification and session handling are managed entirely by Stripe/Salesforce Payments infrastructure. A custom CommercePayments adapter cannot implement Apple Pay without significant complexity outside the adapter interface. Communicate this limitation early.

Output Artifacts

Related Skills

• admin/commerce-checkout-configuration — for legacy sfdc_checkout.CartPaymentAuthorize pattern and store checkout setup; also covers the admin steps for registering a gateway provider
• apex/billing-integration-apex — for Salesforce Billing (blng namespace) invoicing and payment scenarios, which are entirely separate from Commerce payment adapters
• apex/callouts-and-http-integrations — for Named Credential setup, callout patterns, and HTTP mock testing in Apex
• apex/apex-security-patterns — for securing callout credentials and avoiding injection vulnerabilities in payment-related Apex