Ellipse Gradient for Header

Checkout.com Integration Guide

Connect Checkout.com payment APIs and selected webhook events with enterprise order, finance, customer, and reconciliation workflows.

Checkout.com integration options at a glance

Checkout.com provides REST APIs as its primary server-side integration mechanism for payments, captures, voids, refunds, payment instruments, customers, disputes, balances, and related account functions. It also supports webhook notifications for selected payment, refund, dispute, and account events. Martini can consume these APIs, receive and verify webhook requests, transform payment data, and orchestrate downstream workflows. Asynchronous outcomes can be coordinated with webhook-driven processing, scheduled retrieval, pagination, checkpoints, controlled concurrency, and idempotency keys. File functionality is available for selected workflows such as dispute evidence, while general-purpose bulk, GraphQL, SOAP, and direct database access were not confirmed.

Integration pointSupported by Checkout.com?Common use casesHow Martini supports it
REST APIsYesCreate and retrieve payments, perform captures and voids, issue refunds, manage payment instruments and customers, and access dispute or balance information.Martini can consume Checkout.com REST APIs from workflows, map request and response models, apply validation and business rules, and expose controlled APIs around payment operations.
Webhooks / outbound callbacksYesReceive selected asynchronous notifications for payment approvals, declines, captures, capture failures, refund changes, and disputes or chargebacks.Martini can expose webhook endpoints, validate Checkout.com signatures, apply event and resource idempotency, and route events to downstream workflows.
AuthenticationYesAuthenticate server-to-server API calls with Checkout.com secret API keys passed as bearer tokens, using separate test and live credentials.Martini stores credentials in secrets or environment configuration and applies them to outbound API calls without embedding them in workflow logic.
Bulk / asynchronous / batch APIsLimitedSupport asynchronous payment outcomes and webhook-driven processing, but a general-purpose bulk API for arbitrary payment operations was not confirmed.Martini can coordinate scheduled workflows, pagination, checkpoints, controlled concurrency, idempotency keys, and webhook-driven state updates.
File / attachment APIsLimitedProvide file functionality for selected workflows such as dispute evidence and related payment or dispute operations rather than general file transfer.Martini can orchestrate resource-specific file operations and transform or route evidence data where the relevant Checkout.com API supports it.
GraphQL APIsNot confirmedA public Checkout.com GraphQL API was not confirmed in the reviewed official documentation.Martini should use the confirmed Checkout.com REST APIs rather than assuming GraphQL availability.
SOAP APIsNot confirmedA public Checkout.com SOAP API was not confirmed; new integrations should use REST APIs and webhooks.Martini can consume SOAP services generally, but the Checkout.com integration should be based on confirmed REST and webhook mechanisms.
Database accessNot confirmedDirect database access to Checkout.com operational data is not provided as a normal integration mechanism.Martini can retrieve data through Checkout.com APIs or supported exports and write normalized results to a supported database.

How Checkout.com exposes data and business events

Checkout.com REST APIs

Checkout.com REST APIs are the principal server-side mechanism for payment processing and related operations. They cover payment creation and retrieval, captures, voids, refunds, payment instruments, customers, disputes, balances, and other account functions, subject to the enabled account products and API version.

Martini implementation pattern

Martini implementation pattern: a Martini API or workflow receives a normalized business request, validates required values such as amount and currency, maps the request to the Checkout.com model, calls the REST endpoint with a secret bearer token, and transforms the response for the originating or downstream system. Correlation identifiers and idempotency data are retained for recovery.

Implementation sequence

Receive a normalized payment, refund, or reconciliation request
Validate amount, currency, merchant reference, and authorization rules
Retrieve the Checkout.com secret from secure environment configuration
Call the relevant Checkout.com REST endpoint
Map the response to the internal payment or finance model
Persist the Checkout.com identifier and correlation data

Checkout.com webhooks

Checkout.com supports webhook notifications for selected payment, refund, dispute, and related account events. Coverage is event-specific rather than a universal event stream, and exact event names, retry behavior, and availability should be confirmed for the relevant account and API product.

Martini implementation pattern

Martini implementation pattern: expose a webhook endpoint, verify the Checkout.com signature before trusting the payload, validate the event type and identifiers, record the event for duplicate protection, and invoke a separate workflow for downstream updates. When ordering cannot be assumed, the workflow retrieves current resource state before applying a state-aware update.

Implementation sequence

Receive the Checkout.com webhook request
Verify the documented webhook signature
Validate the event type and required identifiers
Check the event or payment idempotency record
Retrieve current resource state when ordering or completeness is uncertain
Map the event to internal payment, refund, or dispute status and update targets

Scheduled reconciliation and retrieval

Checkout.com supports API-based retrieval for payment, refund, dispute, balance, and customer-related synchronization. A general-purpose bulk payment API was not confirmed, so high-volume processes should use pagination, checkpoints, controlled concurrency, and webhook recovery patterns.

Martini implementation pattern

Martini implementation pattern: schedule a workflow that retrieves paginated resources using documented filters where available, processes each page into a canonical reconciliation model, and advances a checkpoint only after successful writes. The workflow can compare payments, refunds, disputes, and balances and route mismatches for investigation.

Implementation sequence

Start the scheduled reconciliation workflow
Load the last successful checkpoint and processing window
Retrieve the next paginated Checkout.com result set
Map payments, refunds, disputes, or balances to the reconciliation model
Write normalized data to the finance system or database
Advance the checkpoint only after successful processing and record exceptions

Common Checkout.com integration patterns

Pattern 1: Orchestrate order payments

When to use this pattern

Use this pattern when an ecommerce or order-management application needs a controlled payment API rather than calling Checkout.com directly. Martini validates the request, performs the payment operation, returns a normalized result, and correlates later asynchronous status changes.

Integration direction
Shopify
Martini
Checkout.com
Example Mapping
Checkout.com FieldCanonical FieldTarget Field
amountpayment.amountMinoramount
currencypayment.currencycurrency
merchant_referencepayment.merchantReferencereference
payment_idpayment.providerPaymentIdCheckout.com payment identifier
Martini implementation pattern

A Martini API receives the order payment request and starts a workflow. The workflow validates amount and currency, retrieves the appropriate test or live secret, maps the request to Checkout.com, applies an idempotency key for the operation, stores the payment identifier and initial status, and returns a normalized response. Timeouts and transient failures are retried only when the operation is safely idempotent.

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

Pattern 2: Synchronize payment status from webhooks

When to use this pattern

Use this pattern when downstream orders, subscriptions, customer-service cases, or finance processes must reflect asynchronous approvals, declines, captures, refund changes, or disputes.

Integration direction
Checkout.com
Martini
Salesforce
Example Mapping
Checkout.com FieldCanonical FieldTarget Field
payment_idpayment.providerPaymentIdCheckout.com Payment ID
event_typepayment.lifecycleStatusPayment Status
amountpayment.amountMinorAmount in minor units
merchant_referencepayment.merchantReferenceOrder or opportunity reference
Martini implementation pattern

A Martini webhook endpoint verifies the Checkout.com signature and validates the event. A workflow checks the event identifier and payment identifier for duplicates, retrieves the current payment when required, maps the provider state to the target lifecycle, and updates the downstream application. Failed updates are recorded for controlled retry or replay.

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

Pattern 3: Process refunds and cancellations

When to use this pattern

Use this pattern when customer-service, order-management, or subscription applications need to request full or partial refunds through a governed integration layer.

Integration direction
ServiceNow
Martini
Checkout.com
Example Mapping
Checkout.com FieldCanonical FieldTarget Field
payment_idrefund.originalPaymentIdPayment ID
amountrefund.amountMinorRefund amount
currencyrefund.currencyCurrency
refund_idrefund.providerRefundIdCheckout.com Refund ID
Martini implementation pattern

Martini receives a refund request, confirms the original payment and remaining refundable amount, validates currency and authorization rules, and calls the Checkout.com refund endpoint with an idempotency key. The workflow returns a normalized result and later consumes refund status notifications, updating the originating system while preventing duplicate refunds.

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

Pattern 4: Reconcile payments, refunds, and balances

When to use this pattern

Use this pattern for scheduled finance operations that compare Checkout.com payment activity with refunds, disputes, balances, and accounting or reporting data.

Integration direction
Checkout.com
Martini
NetSuite
Example Mapping
Checkout.com FieldCanonical FieldTarget Field
payment_idtransaction.providerIdExternal Transaction ID
amounttransaction.amountMinorTransaction Amount
currencytransaction.currencyCurrency Code
statustransaction.lifecycleStatusTransaction Status
Martini implementation pattern

A scheduled Martini workflow retrieves paginated Checkout.com resources, applies date or status filters where supported, maps records into a canonical reconciliation model, and writes them to NetSuite or a finance database. It preserves checkpoints, handles late updates, identifies mismatches, and routes permanent failures or disputed transactions for review.

Martini capabilities used
  • scheduled workflows
  • API consumption
  • pagination handling
  • checkpointing
  • data mapping
  • business rules
  • database integration
  • error handling

Applications commonly integrated with Checkout.com

Checkout.com can be integrated with adjacent commerce, customer, subscription, finance, and service applications through their APIs and Checkout.com’s REST and webhook interfaces. The exact implementation depends on the merchant configuration, enabled Checkout.com products, and the target application’s supported APIs.

Application Scenario Direction Martini Pattern
Shopify Coordinate checkout payment requests with Checkout.com and synchronize payment, refund, and status outcomes back to orders. Shopify → Martini → Checkout.com Martini exposes or consumes the relevant Shopify API, validates order and payment data, calls Checkout.com through a workflow, stores the payment identifier, and processes Checkout.com webhook updates back into Shopify.
Salesforce Associate payment, refund, and dispute status with Accounts, Contacts, Opportunities, or Orders used by sales and service teams. Salesforce → Martini → Checkout.com Martini orchestrates Salesforce API calls with Checkout.com payment and webhook operations, maps payment identifiers and statuses to Salesforce objects, and applies idempotent updates.
NetSuite Post payment and refund results into customer, sales-order, cash-application, and reconciliation processes. Checkout.com → Martini → NetSuite Scheduled and event-driven workflows retrieve Checkout.com payment and refund data, normalize amounts and currencies, and write results to NetSuite while routing rejected or unmatched transactions for review.
Zuora Coordinate subscription payment actions, payment status, refunds, and recurring billing outcomes. Zuora → Martini → Checkout.com Martini receives billing actions from Zuora, validates the operation against the original payment, invokes Checkout.com REST APIs, and sends asynchronous status changes back to Zuora through correlated workflows.
SAP S/4HANA Transfer payment settlements, refunds, disputes, and reconciliation data into enterprise finance processes. Checkout.com → Martini → SAP S/4HANA Martini retrieves relevant Checkout.com resources, maps them to SAP finance structures, validates accounting dates and currencies, and records processing checkpoints and exceptions.
ServiceNow Expose payment or refund status to customer-service and case-management workflows. Checkout.com → Martini → ServiceNow Checkout.com webhooks trigger Martini workflows that verify events, normalize payment state, and update ServiceNow cases or customer-service data through its APIs with duplicate protection.
HubSpot Synchronize customer or transaction status for customer-service, lifecycle, and revenue-reporting processes. Checkout.com → Martini → HubSpot Martini consumes Checkout.com payment and customer data, applies privacy and field-mapping rules, and updates HubSpot through its APIs while preserving payment identifiers and status history.

How to build a Checkout.com integration in Martini

Objective

Establish separate Checkout.com test and live configurations and protect server-side credentials.

Instructions in Martini

  • Store the Checkout.com secret API key in Martini secrets or environment configuration.
  • Configure bearer authentication for outbound REST requests.
  • Keep test and live credentials separate.
  • Configure webhook verification settings without exposing secrets in logs.

Objective

Select an API, webhook, or scheduled trigger based on whether the process starts with a business request, an asynchronous provider event, or a reconciliation run.

Instructions in Martini

  • Use a Martini API for payment or refund requests from applications.
  • Use a webhook endpoint for supported Checkout.com event notifications.
  • Use a scheduler for reconciliation and recovery retrieval.
  • Use a separate workflow for lengthy downstream processing when appropriate.

Objective

Acquire Checkout.com data through the confirmed REST and webhook mechanisms while accounting for event coverage and pagination.

Instructions in Martini

  • Receive and validate selected Checkout.com webhook events.
  • Retrieve the current resource when webhook ordering or completeness is uncertain.
  • Paginate list responses rather than assuming one response contains all results.
  • Use documented filters and checkpoints for scheduled retrieval.

Objective

Coordinate provider calls, correlation, state management, and downstream operations in a maintainable Martini workflow.

Instructions in Martini

  • Correlate requests and events using merchant references and Checkout.com identifiers.
  • Separate synchronous API responses from asynchronous status processing.
  • Apply bounded retries and backoff for transient failures.
  • Use idempotency keys for supported mutating operations.

Objective

Convert Checkout.com payment-domain objects into canonical models and target-specific structures.

Instructions in Martini

  • Map amounts in the required minor currency units.
  • Validate currency codes, required identifiers, and payment lifecycle states.
  • Preserve payment, action, refund, and dispute relationships where available.
  • Redact card data, credentials, and unnecessary personal information from logs.

Objective

Enforce authorization, refund, reconciliation, privacy, and state-transition rules before writing results.

Instructions in Martini

  • Confirm refund amounts against the original payment and remaining refundable value.
  • Do not treat authorization, capture, refund, void, and dispute states as one lifecycle.
  • Apply account-specific event and target-system rules.
  • Route mismatches and unsupported operations for review.

Common Checkout.com data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
PaymentsCreate, authorize, retrieve, capture, void, and track customer payment operations.Shopify, Salesforce, Zuora, NetSuite, SAP S/4HANAMartini validates amount, currency, merchant reference, and payment state; maps requests and responses; stores Checkout.com identifiers; and correlates webhook updates.
Payment instrumentsRepresent cards, tokens, and other payment credentials used to fund a payment.Shopify, Zuora, SalesforceMartini should minimize sensitive-data movement, prefer supported tokens or instruments, and redact payment credentials from logs and error responses.
CustomersAssociate customer profiles and stored instruments with payment activity where supported by the account configuration.Salesforce, HubSpot, Shopify, ZuoraMartini maps customer identifiers and permitted profile data while applying privacy rules and avoiding unnecessary cardholder data.
RefundsPerform and track full or partial reversals of captured payments.NetSuite, Salesforce, Shopify, Zuora, SAP S/4HANAMartini validates the original payment, amount, currency, and authorization before issuing a refund, then processes refund status notifications idempotently.
Disputes / chargebacksTrack payment disputes, chargebacks, status changes, and related evidence workflows.ServiceNow, Salesforce, NetSuite, SAP S/4HANAMartini retrieves or receives dispute information, coordinates supported evidence operations, maps statuses, and routes exceptions for review.
BalancesSupport account and entity balance monitoring, financial operations, and reconciliation.NetSuite, SAP S/4HANA, finance databases, reporting platformsScheduled Martini workflows retrieve balance data, normalize currencies and accounting dates, compare it with payment and refund activity, and persist reconciliation results.

Authentication and security considerations

API authentication

Checkout.com server-to-server API calls use secret API keys as bearer tokens in the Authorization header. Store these keys in Martini secrets or environment configuration and maintain separate credentials for test and live environments.

Webhook protection

Webhook requests should be authenticated using Checkout.com’s documented signature or verification mechanism before Martini processes event data. Restrict the receiving endpoint and reject invalid or unrecognized events.

Payment data protection

  • Do not expose secret keys in client-side applications, mappings, logs, or error responses.
  • Prefer supported tokens, payment instruments, hosted payment pages, or client-side collection patterns to reduce PCI scope.
  • Redact card details, credentials, and unnecessary personal information from workflow logs.

Operational considerations for Checkout.com integrations

Reliability and throughput

Design for HTTP 429 responses, transient 5xx failures, bounded retries, exponential backoff, and controlled concurrency. Use idempotency keys for supported payment and refund mutations.

Webhooks and state

Verify signatures, track processed event identifiers, and do not assume webhook ordering. Retrieve current resource state when required before applying a downstream update.

Synchronization

Paginate list responses and use checkpoints for scheduled retrieval. Advance a checkpoint only after successful processing, account for late-arriving updates, and make overlapping runs idempotent.

Amounts and schemas

Represent amounts in Checkout.com’s expected minor currency units and validate currency codes. Pin or explicitly select API versions where supported, tolerate additive fields, and regression-test payment, refund, and webhook mappings when schemas change.

Reconciliation

Authorization, capture, refund, dispute, settlement, and balance activity can have different lifecycles. Reconcile using stable identifiers, operation relationships, and accounting dates appropriate to the business process.

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

Centralized integration logic

Martini provides a governed workflow layer for Checkout.com API calls, webhook processing, validation, mapping, business rules, retries, and downstream updates instead of duplicating payment logic across applications.

Reusable APIs and workflows

A Martini API façade can normalize payment and refund requests while reusable workflows handle provider-specific authentication, idempotency, correlation, and error handling.

Maintainable synchronization

Scheduled workflows and webhook-triggered processing can work together for near-real-time updates, recovery, reconciliation, pagination, and checkpoint management.

Secure operations

Martini centralizes environment configuration and secrets while supporting controlled logging and workflow-based handling of sensitive payment information.

Frequently asked questions

How can Checkout.com be integrated with enterprise systems?

Checkout.com integrates primarily through REST APIs for payments, captures, voids, refunds, payment instruments, customers, disputes, balances, and related operations. Selected asynchronous payment, refund, and dispute events can be delivered through webhooks. Enterprise workflows can combine these interfaces with scheduled retrieval, pagination, checkpoints, idempotency, and downstream API or database writes.

Can Martini integrate with Checkout.com?

Yes. Martini can integrate with Checkout.com by consuming its REST APIs, receiving selected webhook events, securely storing API keys, mapping payment-domain objects, and orchestrating workflows for payments, refunds, status synchronization, reconciliation, and disputes. A native Martini Checkout.com connector is not documented in the supplied sources.

Do I need a connector to integrate Checkout.com with Martini?

No dedicated Checkout.com connector is required. Martini can use Checkout.com’s confirmed native integration mechanisms, including REST APIs, API-key bearer authentication, selected webhook events, and resource-specific file operations where supported.

Is there any extra Lonti cost to integrate Checkout.com with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate Checkout.com with Martini. Integrations are subject to the provisioned capacity of the Martini environment. Separate costs may apply from Checkout.com, infrastructure providers, or other third-party systems based on subscription, usage, and deployment model.

Which Checkout.com integration methods should be used?

Use Checkout.com REST APIs for server-side payment, capture, void, refund, instrument, customer, dispute, balance, and retrieval operations. Use webhooks for supported asynchronous status changes, with REST retrieval as a recovery and reconciliation mechanism. GraphQL and SOAP APIs were not confirmed for Checkout.com.

Can Martini receive Checkout.com payment events?

Yes. Checkout.com supports webhook notifications for selected payment, refund, dispute, and related events. Martini can expose the receiving endpoint, verify the webhook signature, validate the event, apply idempotency, map the status, and invoke downstream workflows. Event coverage and behavior should be confirmed for the relevant Checkout.com account and product.

How should Checkout.com synchronization, errors, and duplicates be handled?

Use webhooks for asynchronous changes and scheduled REST retrieval for reconciliation or missed events. Workflows should handle pagination, checkpoints, late updates, HTTP 429 responses, transient 5xx failures, and bounded retries. Payment and refund mutations should use supported idempotency mechanisms, while webhook event or resource identifiers should protect against duplicate delivery.

Can Martini expose an API façade for Checkout.com?

Yes. Martini can expose a controlled API that accepts normalized payment or refund requests, applies validation and authorization rules, calls Checkout.com REST APIs, and returns a consistent response to internal applications. This façade can hide provider-specific details, centralize secrets and idempotency, and standardize error handling without implying that Checkout.com provides GraphQL or SOAP access.

Related Martini documentation

API Integration

Workflows

Data Handling

Security Operations

Build reliable Checkout.com integrations with Martini

Use Martini to connect Checkout.com payment APIs and webhook events with your enterprise systems through secure, maintainable workflows.

EXPLORE MARTINI
BOOK A DEMO