Ellipse Gradient for Header

Cybersource Integration Guide

Integrate Cybersource payment authorization, capture, refunds, tokenization, fraud screening, reporting, and transaction workflows through REST APIs, selected webhooks, legacy SOAP, and batch capabilities.

Cybersource integration options at a glance

Cybersource’s primary integration model is REST APIs using JSON for payments, captures, refunds, voids, payment instruments, tokenization, risk services, transaction search, and reporting. Selected payment and transaction events can be delivered through webhook-style notifications, while legacy SOAP services remain available for existing implementations. Cybersource also supports selected batch, asynchronous, reporting, and file-oriented workflows. Martini can consume these APIs, expose secured endpoints for internal payment operations and webhook receipt, map payment data between systems, orchestrate lifecycle workflows, and persist checkpoints and reconciliation results. HTTP Signature and applicable JWT authentication patterns can be managed through protected Martini secrets and environment configuration.

Integration pointSupported by Cybersource?Common use casesHow Martini supports it
REST APIsYesCybersource’s primary modern API model for payments, captures, refunds, voids, payment instruments, tokenization, risk services, transaction search, and reporting.Martini can consume Cybersource REST endpoints, map JSON payloads, apply business rules, and expose internal APIs that orchestrate payment operations.
SOAP APIsLegacyThe Simple Order API and related SOAP methods support existing integrations or capabilities that have not been migrated to REST.Martini can consume SOAP services where a legacy Cybersource implementation requires them, with XML mapping and explicit error handling.
Webhooks / outbound callbacksLimitedCybersource provides webhook-style notifications for selected payment and transaction events, but not a universal event stream for every object or state change.Martini can expose an API to receive notifications, validate them, deduplicate events, retrieve authoritative transaction details, and update downstream systems.
Bulk / async / batch APIsLimitedSelected transaction, reporting, and operational scenarios support asynchronous or batch-oriented processing. Eligibility and result correlation depend on the service.Martini can schedule submissions, track batch status, correlate individual results, and route failed or incomplete items for reconciliation.
File import/exportLimitedFile-oriented workflows are available for selected reporting and batch use cases, with format, delivery, retention, and encryption requirements varying by service.Martini can orchestrate approved file workflows and transform report or batch data into finance, warehouse, or operational models.
AuthenticationYesREST integrations commonly use merchant credentials with HTTP Signature authentication or applicable JWT patterns; SOAP uses its relevant legacy authentication model.Martini stores merchant IDs, key IDs, secret keys, JWT material, and verification settings in protected secrets and environment configuration.
Database accessNoCybersource does not provide general-purpose direct merchant database access. Transaction search, reporting APIs, and available reports are the supported alternatives.Martini can persist normalized Cybersource data in an application-owned SQL database when an operational store or reconciliation history is required.

How Cybersource exposes data and business events

Cybersource REST APIs

Cybersource REST APIs are the primary modern integration method and use JSON for payment processing, payment lifecycle operations, tokenization, risk services, transaction search, and reporting.

Martini implementation pattern

Martini implementation pattern: a workflow or Martini API receives an internal request, signs and sends the Cybersource REST request, validates the response, applies payment-state business rules, and writes normalized results to the originating application or an operational store.

Implementation sequence

Receive the payment or payment-lifecycle request
Validate amount, currency, transaction state, and operation key
Build and sign the Cybersource REST request
Submit the request and parse the JSON response
Apply approval, decline, review, or retry rules
Persist the transaction identifier and normalized outcome

Cybersource Webhooks

Cybersource supports webhook-style notifications for selected payment and transaction events. Coverage, event types, signing requirements, and retry behavior vary by product and region.

Martini implementation pattern

Martini implementation pattern: a secured Martini API receives the notification, validates its authenticity, records an idempotency key, and queries Cybersource when the notification is not authoritative or complete before updating downstream systems.

Implementation sequence

Receive the Cybersource notification
Validate the request and webhook verification data
Check the event identifier for duplicate delivery
Retrieve authoritative transaction details when required
Map the payment state to the target application
Acknowledge the request and record processing outcome

Cybersource SOAP APIs

Cybersource legacy SOAP methods, including the Simple Order API and related services, remain relevant for existing implementations or confirmed service requirements but are not generally preferred for new development.

Martini implementation pattern

Martini implementation pattern: a workflow consumes the SOAP service, maps XML request and response structures, applies legacy authentication and error rules, and normalizes the result into the same internal payment model used by REST flows.

Implementation sequence

Receive the legacy payment operation
Construct the SOAP XML request
Authenticate against the applicable Cybersource service
Submit the SOAP request and parse the response
Map the result to the canonical payment model
Record faults and route non-retryable failures

Cybersource Batch and Files

Selected Cybersource reporting, operational, and transaction workflows support asynchronous, batch, or file-oriented processing. These capabilities are service-specific rather than universal payment interfaces.

Martini implementation pattern

Martini implementation pattern: a scheduled workflow submits or retrieves an approved batch or report, tracks status, parses returned records or files, correlates results to source operations, and writes reconciliation outcomes.

Implementation sequence

Start the workflow for a defined processing window
Submit or retrieve the supported batch or report
Track asynchronous status until completion
Parse the returned records or file
Correlate each result with the originating operation
Persist a checkpoint and reconciliation result

Common Cybersource integration patterns

Pattern 1: Authorize payments for commerce orders

When to use this pattern

Use this pattern when a commerce or order-management application needs a controlled payment authorization flow with centralized validation, response handling, and transaction persistence.

Integration direction
Commerce application
Martini
Cybersource
Example Mapping
Cybersource FieldCanonical FieldTarget Field
orderInformation.amountDetails.totalAmountpayment.amountpaymentInformation.amountDetails.totalAmount
orderInformation.amountDetails.currencypayment.currencyorderInformation.amountDetails.currency
merchantReferenceCodeorder.referenceclientReferenceInformation.code
paymentInstrument.tokenpayment.tokenpaymentInformation.paymentInstrument.token
Martini implementation pattern

Martini receives the order request, validates amount and currency, maps the payment or tokenized instrument, signs the REST request, and applies approval, decline, review, and uncertain-outcome rules. It persists the Cybersource transaction identifier and avoids logging raw payment credentials.

Martini capabilities used
  • APIs
  • workflows
  • API consumption
  • data mapping
  • business rules
  • secrets management
  • error handling

Pattern 2: Orchestrate capture, refund, and void operations

When to use this pattern

Use this pattern when commerce, billing, and finance applications have different payment lifecycles and need controlled operations against an existing Cybersource transaction.

Integration direction
Order or billing application
Martini
Cybersource
Example Mapping
Cybersource FieldCanonical FieldTarget Field
transactionIdpayment.transactionIdoriginalPaymentInformation.token
requestedAmountoperation.amountorderInformation.amountDetails.totalAmount
currencyCodeoperation.currencyorderInformation.amountDetails.currency
operationTypepayment.lifecycleActionCybersource capture, refund, or void operation
Martini implementation pattern

Separate Martini workflows receive capture, refund, or void requests, retrieve or validate the original transaction, check allowable amounts and current state, call the appropriate Cybersource REST operation, and update the source system. Timeouts are reconciled before any retry.

Martini capabilities used
  • APIs
  • workflows
  • data mapping
  • validation
  • business rules
  • idempotency
  • error handling

Pattern 3: Reconcile asynchronous payment notifications

When to use this pattern

Use this pattern when a payment state changes after the initial request or when Cybersource sends a supported webhook notification for a selected event.

Integration direction
Cybersource
Martini
Commerce or billing application
Example Mapping
Cybersource FieldCanonical FieldTarget Field
eventIdnotification.idintegrationEvent.externalId
transactionIdpayment.transactionIdorder.paymentTransactionId
paymentStatuspayment.statusorder.paymentStatus
reasonCodepayment.reasonCodeorder.paymentDecision
Martini implementation pattern

Martini receives and verifies the notification, deduplicates it, queries Cybersource for authoritative details when needed, maps the resulting state, and updates the order or subscription. Long-running reconciliation can be separated from the initial acknowledgment.

Martini capabilities used
  • API exposure
  • webhook consumption
  • workflows
  • data mapping
  • business rules
  • idempotency
  • error handling

Pattern 4: Run scheduled payment reconciliation

When to use this pattern

Use this pattern for finance and operational reconciliation using Cybersource transaction search, reporting APIs, or approved batch and file workflows.

Integration direction
Cybersource
Martini
Oracle NetSuite or operational database
Example Mapping
Cybersource FieldCanonical FieldTarget Field
transactionIdpayment.transactionIdexternalTransactionId
transactionTypepayment.operationTypetransactionType
amountDetails.totalAmountpayment.amountamount
submitTimeUtcpayment.sourceTimestampsourceTimestamp
Martini implementation pattern

A Martini scheduler invokes a workflow for a bounded time window, retrieves pages or report results, transforms amounts and currencies, applies deduplication and checkpoint rules, and writes reconciliation records. Failed items are retained for replay without duplicating financial entries.

Martini capabilities used
  • scheduling
  • workflows
  • API consumption
  • file processing
  • data mapping
  • database access
  • monitoring

Applications commonly integrated with Cybersource

Cybersource can be integrated with commerce, billing, finance, and customer platforms through their APIs, payment extensions, or intermediary services. The exact payment path depends on the product configuration and merchant architecture.

Application Scenario Direction Martini Pattern
Salesforce Commerce Cloud Process payment authorization, capture, refund, and order payment-status updates for online commerce. Salesforce Commerce Cloud → Martini → Cybersource Martini receives commerce payment requests, maps them to Cybersource REST operations, applies approval and retry rules, and returns or synchronizes transaction identifiers and statuses.
Adobe Commerce Submit payment transactions and synchronize authorization, refund, and order-payment results. Adobe Commerce → Martini → Cybersource A Martini workflow validates the Adobe Commerce request, calls Cybersource, normalizes response and reason-code data, and updates the commerce order or refund state.
SAP Commerce Cloud Coordinate payment authorization and settlement lifecycle events with commerce orders and fulfillment processes. SAP Commerce Cloud → Martini → Cybersource Martini orchestrates payment calls, maps Cybersource transaction states to SAP Commerce Cloud status values, and routes uncertain or failed operations for reconciliation.
Oracle NetSuite Reconcile Cybersource transactions with invoices, customer payments, refunds, and settlement records. Cybersource → Martini → Oracle NetSuite A scheduled or event-driven workflow retrieves Cybersource transactions or reports, transforms amounts and currencies, applies idempotency rules, and writes normalized payment records to NetSuite.
Salesforce Synchronize payment transactions, customer payment status, invoices, and refunds with Salesforce business processes. Salesforce → Martini → Cybersource Martini exposes or consumes Salesforce APIs, invokes the appropriate Cybersource payment operation, and returns normalized results while masking sensitive payment data.
Zuora Coordinate subscription billing payments, refunds, and payment-status changes with Cybersource. Zuora → Martini → Cybersource Martini translates billing payment actions into Cybersource requests, consumes selected status notifications, and updates Zuora only after validation and transaction-state checks.

How to build a Cybersource integration in Martini

Objective

Configure Cybersource access using separate sandbox and production credentials and protect signing material.

Instructions in Martini

  • Create protected Martini secrets for merchant ID, API key ID, secret key, and applicable JWT or webhook verification material.
  • Configure the Cybersource base URL and environment-specific settings.
  • Use HTTP Signature or the applicable JWT pattern for REST requests.

Objective

Select an API request, selected Cybersource notification, or scheduled reconciliation trigger based on the business process.

Instructions in Martini

  • Use a Martini API for internal payment operations.
  • Use a webhook-consuming API for supported Cybersource notifications.
  • Use a scheduler for transaction search, reports, or batch reconciliation.

Objective

Obtain the payment request, notification, transaction details, report, or batch result needed by the workflow.

Instructions in Martini

  • Validate incoming requests before processing.
  • Query Cybersource after notifications when the event is not authoritative.
  • Use bounded time windows and checkpoints for searches and reports.

Objective

Coordinate Cybersource calls, target-system updates, state checks, and exception paths in a maintainable workflow.

Instructions in Martini

  • Separate authorization, capture, refund, void, and reconciliation operations.
  • Check transaction state before retrying uncertain operations.
  • Route non-retryable declines and validation errors separately from transient failures.

Objective

Normalize Cybersource payment data for commerce, billing, finance, or operational systems.

Instructions in Martini

  • Map transaction identifiers, amounts, currencies, statuses, and reason codes.
  • Preserve decimal precision and source timestamps.
  • Mask or exclude sensitive payment data from payloads and logs.

Objective

Protect payment integrity and enforce business decisions before and after Cybersource operations.

Instructions in Martini

  • Apply idempotency keys to payment lifecycle operations and webhook events.
  • Validate capture and refund limits against the original transaction.
  • Distinguish approval, decline, review, reversal, settlement, and refund states.

Common Cybersource data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
PaymentsAuthorize payment requests and track payment outcomes, transaction identifiers, risk decisions, and processor responses.Commerce platforms, order management, billing, CRM, finance systemsMartini maps payment requests to Cybersource REST models, preserves identifiers and reason codes, masks sensitive data, and applies idempotency and outcome rules.
CapturesCapture funds previously authorized for a payment, including partial or subsequent captures where supported.Commerce platforms, order management, ERP, finance systemsA workflow validates payment state, amount, and currency before submitting the capture and synchronizing the result.
RefundsReturn all or part of captured or settled funds to a customer.Commerce platforms, billing, ERP, finance systemsMartini checks the original transaction and remaining refundable amount, submits the refund, records the response, and updates the target after result handling.
VoidsCancel an authorization or eligible transaction before settlement.Commerce platforms, order management, finance systemsMartini validates the source payment state, invokes the void operation, and maps the resulting status to the originating order or payment record.
Payment instrumentsRepresent card and other payment instrument data, including identifiers and tokenized payment information.Commerce, billing, customer, and payment applicationsMartini should prefer tokenized identifiers and minimize exposure of cardholder data while mapping only fields required by downstream systems.
CustomersSupport customer-related payment, tokenization, and stored-credential scenarios.CRM, commerce, subscription billing, customer serviceMartini maps customer references and payment-related identifiers without copying unnecessary sensitive payment information.

Authentication and security considerations

Authentication and credential protection

Cybersource REST integrations commonly use merchant credentials with HTTP Signature authentication or applicable JWT patterns. Legacy SOAP services use their relevant authentication model.

  • Store merchant IDs, API key IDs, secret keys, JWT material, and webhook verification settings in Martini secrets or protected environment configuration.
  • Keep sandbox and production credentials separate.
  • Validate webhook authenticity and integrity before processing notifications.
  • Do not log secret keys, authorization headers, raw card data, or unnecessary sensitive response fields.

Payment-data security

Minimize cardholder-data exposure by preferring tokenized payment instruments or hosted payment experiences where appropriate. Review PCI DSS responsibilities for the selected Cybersource integration model and mask sensitive fields in workflow logs.

Operational considerations for Cybersource integrations

Payment integrity

Use idempotency controls for authorization, capture, refund, void, and webhook processing. Do not blindly retry a timed-out payment operation; first query Cybersource to determine whether the original request succeeded.

Reconciliation and pagination

Use bounded time windows, pagination, stable checkpoints, and replay-safe writes for transaction search, reports, and batch processing. Preserve transaction identifiers, source timestamps, amounts, currencies, and reason codes.

Errors and state

  • Separate transport errors, authentication failures, validation errors, processor declines, fraud decisions, and retryable service failures.
  • Distinguish authorization, capture, settlement, decline, review, reversal, and refund states.
  • Validate partial captures and refunds against the applicable authorized or captured amount.
  • Review API and payment-product changes before updating mappings, and test against sandbox scenarios.

Why use Martini instead of scripts or point-to-point integrations?

Controlled orchestration

Martini centralizes Cybersource API calls, webhook receipt, payment lifecycle rules, reconciliation, and downstream updates in maintainable workflows rather than scattering logic across scripts or point-to-point links.

Reusable integration assets

Teams can expose consistent internal APIs, reuse authentication and transformation logic, and maintain separate flows for authorization, capture, refunds, voids, notifications, and reporting.

Operational resilience

  • Apply validation, idempotency, retries, checkpoints, and error routing consistently.
  • Map Cybersource JSON, XML, batch, and file results into canonical business models.
  • Protect secrets and payment data while retaining the identifiers and outcomes needed for audit and reconciliation.

Frequently asked questions

How can Cybersource be integrated with enterprise systems?

Cybersource can be integrated primarily through REST APIs using JSON for payments, captures, refunds, voids, tokenization, risk services, transaction search, and reporting. Selected webhook-style notifications, legacy SOAP services, and service-specific batch or file workflows are also available.

Can Martini integrate with Cybersource?

Yes. Martini can consume Cybersource REST APIs, use legacy SOAP APIs where required, receive supported webhook notifications, orchestrate payment lifecycle workflows, and map results into commerce, billing, finance, or operational systems.

Do I need a connector to integrate Cybersource with Martini?

No. A dedicated Cybersource connector is not required. Martini can use Cybersource’s confirmed native REST APIs, selected webhooks, legacy SOAP services, batch or file workflows, and authentication mechanisms.

Is there any extra Lonti cost to integrate Cybersource with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate Cybersource. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Cybersource, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.

Which Cybersource integration method should new implementations use?

REST APIs are the recommended starting point for new integrations. SOAP should generally be reserved for existing legacy implementations or capabilities confirmed to require that interface. Webhooks, batch, and file workflows should be selected according to the specific product and region.

Can Martini receive Cybersource webhooks?

Yes, Martini can expose an API and consume Cybersource webhook-style notifications for selected events. The implementation must confirm event coverage and verification requirements, validate and deduplicate notifications, and query Cybersource when authoritative transaction details are needed.

How should Cybersource payment synchronization handle timeouts and duplicates?

Payment workflows should use operation keys and idempotency controls. A timeout should not automatically create a second payment request; the workflow should first search for or retrieve the original transaction, determine its outcome, and retry only when safe.

Can Martini expose an API façade for Cybersource payment operations?

Yes. Martini can expose controlled APIs for authorization, capture, refund, void, and payment-status operations while keeping Cybersource credentials and signing logic behind the integration boundary. The façade can apply validation, business rules, mapping, logging controls, and consistent error responses.

Related Martini documentation

API Integration

Workflows

Security

Operations

Integrate Cybersource with Martini

Use Martini to connect Cybersource payment operations with commerce, billing, finance, and operational systems through secure APIs, workflows, webhook processing, and reconciliation automation.

EXPLORE MARTINI
BOOK A DEMO