CyberSource Best Practices

Official Documentation

Authentication

Three auth modes are available: JWT Shared Secret, JWT P12, and HTTP Signature. Both JWT modes are recommended for new integrations; HTTP Signature is deprecated.

JWT (Shared Secret) — Recommended

Symmetric JWT signed with HMAC using a shared secret key. Supports MLE.

SDK config keys: authenticationType=jwt, jwtKeyType=SHARED_SECRET, merchantID, merchantKeyId, merchantsecretKey, runEnvironment=apitest.cybersource.com

Key gotcha: "The shared secret is shown only once when generated. Copy it immediately."

JWT (P12 Certificate) — Recommended

Certificate-based authentication using a PKCS#12 file. Supports MLE.

SDK config keys: authenticationType=jwt, merchantID, keysDirectory, keyFilename, keyPass, keyAlias, runEnvironment=apitest.cybersource.com

Obtaining your P12 certificate:

1. Log into Business Center → Payment Configuration → Key Management
2. Generate new key → select P12
3. Download the .p12 file — store securely, never commit to source control

HTTP Signature — Deprecated

Signs each request with HMAC-SHA256. Being deprecated — migrate to JWT Shared Secret. Does not support MLE.

SDK config keys: authenticationType=http_signature, merchantID, merchantKeyId, merchantsecretKey, runEnvironment=apitest.cybersource.com

Key gotcha: "The shared secret is shown only once when generated. Copy it immediately."

OAuth 2.0

For ISV/partner delegation — allows one merchant to authorize another to act on their behalf. Not a general-purpose auth method. Uses separate endpoints: api-matest.cybersource.com (sandbox), api-ma.cybersource.com (production).

Environments

Never mix environments in the same code example. Sandbox test cards will fail on production and vice versa.

Message Level Encryption (MLE)

Application-level payload encryption (request) and decryption (response). Supported only with JWT authentication — works with both JWT key types (P12 and SHARED_SECRET). HTTP Signature does not support MLE.

Enable globally: set enableRequestMLEForOptionalApisGlobally=true in merchantConfig (replaces the deprecated useMLEGlobally).

Request MLE certificate source by key type:

Key gotchas:

• Check each API's MLE enforcement level (Mandatory / Optional / Not Applicable)
• For SHARED_SECRET, mleForRequestPublicCertPath is required or request MLE cannot run
• Use disableRequestMLEForMandatoryApisGlobally=true to opt mandatory-MLE APIs out
• Default P12 key alias is CyberSource_SJC_US — only change if using a custom cert
• Up to 3 active Key-IDs for rotation

Credential & Key Management

• P12 certificates — generated in Business Center, contain both signing key and MLE cert
• Shared secrets — shown once at generation; copy immediately
• Monitor expiration in Business Center → Key Management
• Maintain 2 active credential sets for seamless rotation
• Validate rotation in sandbox before promoting to production
• Revoke old credentials only after confirming new ones function correctly

Core Payment Flows

Key Endpoints

Auth-only vs Auth+Capture

Gotchas:

• If the auth window expires, capturing is no longer possible — issue a new authorization
• "Void cancels before settlement (no money moves). Refund returns money after settlement (5-10 business days)."
• "Never auto-retry a PROCESSOR_DECLINED (code 05). This is an issuer decision. Retrying can trigger fraud flags."

Tokenization (TMS)

Store payment credentials without handling raw PANs. Never store raw card numbers in your database.

Token Types

Zero-Dollar Authorization (Store Card Without Charge)

POST /pts/v2/payments with actionList: ["TOKEN_CREATE"], capture: false, totalAmount: "0.00". Returns a TMS token for permanent storage.

Unified Checkout (UC v1)

IMPORTANT: Always use UC v1 (/uc/v1/sessions). Do NOT use the legacy Microform/Flex endpoint /pts/v2/microform/capture-contexts — that is a deprecated v0.x API.

Drop-in payment form handling card entry, digital wallets, and 3DS — all PCI-compliant.

Setup Flow

1. Server-side: POST /uc/v1/sessions — creates a UC session and returns a captureContext JWT
2. Client-side: Load the UC JavaScript library with the captureContext
3. On submit: UC returns a transient token representing the entered card
4. Server-side: POST /pts/v2/payments with the transient token to authorize

Session lifetime is 15 minutes. Generate a fresh one per checkout session.

Minimal Session Creation Request

POST /uc/v1/sessions
{
  "targetOrigins": ["https://yoursite.com"],
  "allowedCardNetworks": ["VISA", "MASTERCARD", "AMEX"],
  "allowedPaymentTypes": ["PANENTRY", "SRC", "GOOGLEPAY", "APPLEPAY"]
}

Response includes captureContext — a JWT passed directly to the UC JS library.

Passing a TMS Token into UC (Pre-fill Stored Card)

High-impact feature. Include paymentInformation in the session creation request to pre-populate UC with a stored card from TMS. The customer sees their saved card without re-entering details.

Option A — Pass a specific Payment Instrument ID:

POST /uc/v1/sessions
{
  "targetOrigins": ["https://yoursite.com"],
  "allowedCardNetworks": ["VISA", "MASTERCARD"],
  "allowedPaymentTypes": ["PANENTRY"],
  "paymentInformation": {
    "paymentInstrument": {
      "id": "<TMS_PAYMENT_INSTRUMENT_ID>"
    }
  }
}

Option B — Pass a TMS Customer ID (loads all saved cards for that customer):

POST /uc/v1/sessions
{
  "targetOrigins": ["https://yoursite.com"],
  "allowedCardNetworks": ["VISA", "MASTERCARD"],
  "allowedPaymentTypes": ["PANENTRY"],
  "paymentInformation": {
    "customerId": "<TMS_CUSTOMER_ID>"
  }
}

Key gotchas for TMS passthrough:

• The TMS Payment Instrument ID must belong to the same merchantID making the session request
• The captureContext returned will contain masked card details; the full PAN is never exposed
• On form submit, UC returns a new transient token — do NOT pass the TMS ID directly to the payment API; always use the fresh transient token returned by UC
• If paymentInstrument.id is invalid or expired, UC falls back to blank card entry (no error thrown to the merchant)

Key Gotchas (General UC v1)

• "targetOrigins must exactly match your domain (including port if non-standard)"
• The captureContext is a JWT — do not decode or modify it client-side
• 406 errors on session creation usually indicate a malformed request body
• Enable wallet types via allowedPaymentTypes: PANENTRY, SRC, GOOGLEPAY, APPLEPAY

3D Secure / Payer Authentication

Implements SCA (Strong Customer Authentication) for PSD2 compliance.

When to Use

• Required: EU/EEA transactions (PSD2), high-risk transactions
• Recommended: Any card-not-present transaction (reduces chargebacks)
• Not needed: Recurring billing after initial enrollment, merchant-initiated transactions

Frictionless vs Step-Up

The issuer decides — frictionless cannot be forced.

Digital Wallets

Apple Pay

• Client-side: Apple Pay JS API → payment token
• Server-side: POST /pts/v2/payments with paymentSolution: "001"
• Requires an Apple Developer account and merchant ID registration

Google Pay

Two paths:

• With Unified Checkout: Enable GOOGLEPAY in allowedPaymentTypes in the /uc/v1/sessions request — UC handles everything
• Standalone: Google Pay API → encrypted payment data → POST /pts/v2/payments with paymentSolution: "012"

Click to Pay (SRC)

Enable SRC in allowedPaymentTypes in the /uc/v1/sessions request. No separate integration required.

Webhooks

Subscribe to payment events via POST /notification-subscriptions/v1/webhooks with mutual trust security.

Event types: payments.payments.authorized, payments.payments.captured, payments.payments.refunded

Gotchas:

• Visa Acceptance webhook IPs must be whitelisted — check developer docs for current ranges
• "Respond with 200 OK within 10 seconds or the webhook will retry"
• Use webhookId for deduplication (idempotency)
• TLS 1.2+ required on your endpoint

Recurring Billing

Stored Credential Framework

Testing

Sandbox Test Cards

Always use https://apitest.cybersource.com. Production credentials will not work in sandbox.

Going Live Checklist

1. Get production credentials in Business Center (Production)
2. Change runEnvironment to api.cybersource.com
3. Replace sandbox credentials with production credentials
4. Same code — no logic changes needed between sandbox and production
5. Verify first production transaction with a real card (small amount, then void)
6. Enable webhook subscriptions on production
7. Set up monitoring and alerting on decline rates

Error Handling

Common Status Codes

Processor Response Codes

Supported SDKs

All SDKs handle JWT/HTTP Signature generation automatically. Set authenticationType and credentials — the SDK handles the rest.