.png)
Affirm Integration Guide
Integrate Affirm financing and payment lifecycle operations through REST APIs, selected webhook notifications, and secure server-side workflows.
Affirm integration options at a glance
Affirm’s primary merchant integration mechanism is its HTTPS REST API, which uses JSON for checkout creation, transaction retrieval, authorization, capture, void, and full or partial refund operations. Affirm also provides client-side checkout resources and webhook-style notifications for selected payment and transaction events. Server-side operations use merchant-issued private credentials with HTTP Basic Authentication, while client-side checkout uses public merchant information. Martini can consume the REST API, receive selected webhook events, orchestrate payment workflows, transform JSON payloads, and expose internal APIs for commerce or order systems. Scheduled workflows can support controlled retrieval and reconciliation where the applicable Affirm API permits it.
| Integration point | Supported by Affirm? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Affirm’s primary merchant interface for creating checkouts, retrieving transactions, capturing authorized transactions, voiding authorizations, and issuing full or partial refunds. | Martini can consume Affirm REST endpoints, map JSON requests and responses, apply business rules, and orchestrate calls across commerce, order, and finance systems. |
| Client-side checkout and SDKs | Yes | Client-side checkout resources and implementation libraries present Affirm as a financing option and initiate the customer authorization flow. | Martini can support the server-side orchestration around client-side checkout, while public checkout information remains client-facing and private operations remain server-side. |
| Webhooks / outbound callbacks | Limited | Affirm provides webhook-style notifications for selected payment and transaction events; coverage depends on the merchant account and enabled API version. | Martini can receive webhook notifications, validate them according to Affirm’s requirements, deduplicate events, and trigger asynchronous workflows. |
| Authentication | Yes | Server-side requests use Affirm-issued merchant credentials, including private API keys and HTTP Basic Authentication, with separate sandbox and production environments. | Martini can keep credentials in secure environment configuration or secrets management and apply them to outbound REST calls without exposing them to client-side code. |
| Scheduled synchronization | Limited | Affirm does not provide a confirmed general-purpose change-data-capture feed, but applicable retrieval endpoints may support controlled polling and reconciliation. | Martini can schedule retrieval workflows with checkpoints, bounded date windows, pagination handling, overlap protection, and duplicate controls. |
| Bulk / async / batch APIs | Not confirmed | No general-purpose bulk or asynchronous batch API was confirmed in the reviewed Affirm documentation; individual REST operations should be assumed. | Martini can coordinate individual API calls and workflow batches where appropriate, but should not assume an Affirm bulk endpoint. |
| File / attachment APIs | Not confirmed | No general-purpose file import, export, or attachment API was confirmed for the core Affirm payment APIs. | Martini can use other supported interfaces for surrounding systems, but an Affirm file exchange should not be assumed. |
| GraphQL APIs | Not confirmed | No official Affirm GraphQL API was confirmed. | Martini can consume REST APIs instead; a GraphQL façade could be exposed for internal consumers if required by the architecture. |
How Affirm exposes data and business events
Affirm REST APIs
Affirm’s REST APIs are the primary mechanism for merchant-side payment integration. They use HTTPS and JSON for checkout, transaction, authorization, capture, void, charge, and refund operations.
Martini implementation pattern
Martini implementation pattern: Martini receives a command from a commerce, order, fulfillment, or finance system, validates the business input, calls the relevant Affirm REST endpoint, transforms the response, and writes the result to downstream systems. Payment operations include identifier persistence and state checks before retries.
Implementation sequence
Affirm Webhooks
Affirm provides webhook-style notifications for selected transaction and payment events. Coverage is event-specific and should be confirmed for the merchant account and enabled API version.
Martini implementation pattern
Martini implementation pattern: Martini exposes an inbound endpoint for selected Affirm notifications, validates the request according to the current Affirm webhook requirements, records the original payload, deduplicates the event, and hands longer business processing to a workflow.
Implementation sequence
Affirm Scheduled Retrieval
Affirm does not provide a confirmed general-purpose change-data-capture feed. Where applicable retrieval endpoints support filtering, scheduled synchronization can support reconciliation and controlled status recovery.
Martini implementation pattern
Martini implementation pattern: A scheduled workflow retrieves data in bounded time windows, follows the relevant pagination model, applies an overlap to account for late updates, and stores a checkpoint after successful processing.
Implementation sequence
Common Affirm integration patterns
Pattern 1: Orchestrate Affirm checkout creation
When to use this pattern
Use this pattern when a commerce platform needs Affirm financing without embedding all vendor-specific payment orchestration logic in the storefront or order service.
Integration direction
Example Mapping
| Affirm Field | Canonical Field | Target Field |
|---|---|---|
| order.total | orderAmount | checkout.amount |
| order.currency | currencyCode | checkout.currency |
| order.id | merchantOrderId | checkout.orderReference |
| customer.email | customerEmail | checkout.customerEmail |
Martini implementation pattern
A Martini API receives the checkout request, validates totals and merchant configuration, maps the request to Affirm’s Checkout API, and returns the relevant checkout information. Martini records the Checkout identifier and routes failures to a retry or operational queue without exposing private credentials.
Martini capabilities used
- APIs
- workflows
- API consumption
- data mapping
- business rules
- error handling
Pattern 2: Capture authorized transactions after fulfillment
When to use this pattern
Use this pattern when payment capture should occur only after an order-management or warehouse process confirms that goods are ready for fulfillment.
Integration direction
Example Mapping
| Affirm Field | Canonical Field | Target Field |
|---|---|---|
| fulfillment.status | fulfillmentState | capture eligibility |
| order.id | merchantOrderId | transaction reference |
| order.captureAmount | approvedCaptureAmount | capture.amount |
| order.currency | currencyCode | capture.currency |
Martini implementation pattern
A Martini workflow receives the fulfillment signal, retrieves or validates the related Affirm Transaction or Authorization, checks the amount and current state, and submits capture. It persists the result and updates the commerce or ERP system, while ambiguous timeouts trigger a status check before any retry.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- idempotency controls
- error handling
Pattern 3: Synchronize refunds to Affirm and finance systems
When to use this pattern
Use this pattern when a commerce, order-management, or customer-service application initiates full or partial refunds that must be reflected in Affirm and accounting systems.
Integration direction
Example Mapping
| Affirm Field | Canonical Field | Target Field |
|---|---|---|
| refund.orderId | merchantOrderId | transaction reference |
| refund.amount | refundAmount | refund.amount |
| refund.currency | currencyCode | refund.currency |
| refund.id | refundOperationId | idempotency key |
Martini implementation pattern
Martini validates that the requested amount does not exceed the captured amount, submits the Affirm refund request, stores the Refund identifier, and maps the outcome to the commerce and financial systems. Repeated commands are matched to the existing operation and ambiguous responses are reconciled before retry.
Martini capabilities used
- workflows
- API consumption
- data mapping
- validation
- business rules
- error handling
Pattern 4: Process selected Affirm payment events
When to use this pattern
Use this pattern when downstream order, support, or reconciliation systems need timely notification of selected Affirm transaction or payment state changes.
Integration direction
Example Mapping
| Affirm Field | Canonical Field | Target Field |
|---|---|---|
| event.type | paymentEventType | case or workflow type |
| transaction.id | transactionId | external transaction ID |
| event.status | paymentStatus | operational status |
| event.timestamp | eventTime | reported time |
Martini implementation pattern
Martini receives the selected webhook event, validates and deduplicates it, enriches it with the authoritative Affirm resource when necessary, and maps it to order, support, or exception workflows. Failed downstream delivery is retried independently from webhook acknowledgment.
Martini capabilities used
- APIs
- webhook consumption
- workflows
- data mapping
- asynchronous execution
- error handling
Applications commonly integrated with Affirm
Affirm payment operations can be coordinated with commerce, order, financial, customer-service, operational, and analytics platforms. The exact implementation depends on the target application’s APIs and the merchant’s Affirm configuration.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Shopify | Synchronize orders, checkout information, payment status, captures, and refunds involving Affirm. | Shopify → Martini → Affirm | Martini exposes an internal payment API or receives commerce events, maps order and amount data to Affirm REST requests, and returns or propagates authorization, capture, and refund results to Shopify. Idempotency and status checks protect payment operations. |
| Salesforce Commerce Cloud | Coordinate Affirm financing with storefront checkout, order creation, payment status, and fulfillment processes. | Salesforce Commerce Cloud → Martini → Affirm | A Martini workflow receives checkout or order commands, creates the Affirm Checkout, and routes lifecycle updates back to the commerce platform. Selected Affirm webhook events can trigger normalized order and payment status updates. |
| Adobe Commerce | Support Affirm transaction processing across order placement, authorization, capture, cancellation, and refund workflows. | Adobe Commerce → Martini → Affirm | Martini maps Adobe Commerce order and refund payloads to Affirm JSON requests, applies amount validation and duplicate protection, and writes operation results back to Adobe Commerce. |
| NetSuite | Post Affirm captures, refunds, payment statuses, and related reconciliation information to financial and order records. | Affirm → Martini → NetSuite | Martini consumes Affirm transaction or webhook data, transforms it into NetSuite record fields, and routes exceptions for review. Commands from order or financial processes can initiate capture or refund workflows in the opposite direction. |
| Salesforce | Give customer-service users consolidated visibility into order, financing, transaction, and refund status. | Affirm → Martini → Salesforce | Martini retrieves or receives Affirm payment data, normalizes Checkout, Transaction, Charge, and Refund information, and synchronizes the relevant fields to Salesforce while preserving source identifiers. |
| ServiceNow | Route payment exceptions, failed operations, and reconciliation issues into operational workflows and case management. | Affirm → Martini → ServiceNow | Martini detects failed or unexpected Affirm states, enriches the exception with order and transaction identifiers, and creates or updates a ServiceNow record for operational resolution. |
| SAP S/4HANA | Connect order, fulfillment, refund, and financial settlement processes with Affirm payment activity. | SAP S/4HANA → Martini → Affirm | Martini orchestrates capture and refund commands from fulfillment or finance processes, maps Affirm responses to SAP business objects, and records reconciliation results with retry and exception handling. |
| Snowflake | Centralize Affirm transaction and payment lifecycle data for reporting, reconciliation, and operational analysis. | Affirm → Martini → Snowflake | Scheduled or webhook-driven Martini workflows retrieve and normalize Affirm payment data, apply a bounded synchronization window, and load curated transaction, charge, authorization, and refund data through the available Snowflake ingestion interface. |
How to build a Affirm integration in Martini
Objective
Establish a server-side connection to Affirm using the merchant’s environment-specific credentials and keep private information outside client-side code and workflow payloads.
Instructions in Martini
- Configure sandbox or production endpoints and credentials
- Store private API keys and Basic Authentication values in secure environment configuration
- Separate credentials by merchant, brand, region, or environment where required
- Confirm the enabled Affirm API version and merchant permissions
Objective
Select the event, API request, or schedule that should start the integration workflow.
Instructions in Martini
- Use an inbound Martini API for checkout, capture, void, or refund commands
- Receive selected Affirm webhook notifications through a Martini endpoint
- Use a scheduler for bounded retrieval and reconciliation workflows
- Use fulfillment or refund events from the surrounding order systems
Objective
Collect the authoritative Affirm resource needed to make a payment decision or synchronize a state change.
Instructions in Martini
- Call the relevant Affirm REST endpoint
- Retrieve the current Transaction, Charge, Authorization, or Refund state when required
- Follow the applicable pagination model for list responses
- Use a checkpoint and overlap for scheduled retrieval
Objective
Coordinate validation, Affirm calls, downstream updates, and exception paths as a maintainable Martini workflow.
Instructions in Martini
- Validate required identifiers, amounts, currency, and lifecycle state
- Sequence checkout, authorization, capture, void, and refund operations appropriately
- Separate webhook acknowledgment from longer downstream processing when appropriate
- Persist operation and source identifiers for reconciliation
Objective
Convert Affirm JSON payloads into the canonical model used by commerce, order, finance, support, or analytics systems.
Instructions in Martini
- Map Checkout, Transaction, Charge, Authorization, and Refund fields
- Preserve currency codes, monetary precision, timestamps, and vendor identifiers
- Normalize payment statuses and event types
- Apply target-specific transformations before writing data
Objective
Protect payment integrity by applying merchant and operational rules before irreversible operations.
Instructions in Martini
- Prevent duplicate captures and refunds with business idempotency keys
- Check current Affirm state before retrying ambiguous requests
- Validate refunds against captured amounts
- Route unexpected states and reconciliation gaps for review
Common Affirm data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Checkout | Financing checkout session created before the customer completes an Affirm purchase. | Shopify, Salesforce Commerce Cloud, Adobe Commerce, order management systems | Martini maps order, customer-facing checkout, amount, and merchant data to Affirm and stores the returned identifiers for later lifecycle operations. |
| Transaction | Payment transaction associated with an approved checkout and used to track payment state. | Commerce platforms, NetSuite, SAP S/4HANA, Salesforce, Snowflake | Martini retrieves or receives transaction information, normalizes statuses, and uses the identifier for capture, void, reconciliation, and downstream updates. |
| Charge | Captured or capturable payment amount associated with a transaction. | NetSuite, SAP S/4HANA, commerce platforms, data warehouses | Martini validates amounts and currency, maps charge status, and prevents duplicate capture or downstream posting during retries. |
| Refund | Full or partial reversal of a captured charge. | Adobe Commerce, Shopify, NetSuite, SAP S/4HANA, customer-service systems | Martini validates the refund against captured amounts, submits the request, records the refund identifier, and synchronizes the result. |
| Authorization | Approved financing authorization created after the customer completes the Affirm flow. | Commerce platforms, fulfillment systems, order management, payment ledgers | Martini correlates authorization data with the Checkout and Transaction, applies fulfillment rules, and initiates capture only when appropriate. |
| Merchant | Business account and configuration under which Affirm transactions are processed. | Merchant configuration, environment management, operational systems | Martini separates merchant, sandbox, production, brand, and regional credentials through secure configuration rather than embedding them in workflows. |
Authentication and security considerations
Server-side credentials
Affirm uses merchant-issued credentials, including private API keys and HTTP Basic Authentication, for backend API calls. Private credentials should remain on the server and must not be exposed in client-side code.
Environment separation
Sandbox and production credentials should be configured separately. Merchant permissions and account configuration determine which payment operations are available.
Secure Martini configuration
- Store Affirm secrets in Martini environment configuration or secrets management.
- Use HTTPS/TLS for API communication.
- Prevent private credentials from appearing in logs, traces, or error payloads.
- Validate selected webhook notifications according to Affirm’s current security requirements.
Operational considerations for Affirm integrations
Payment integrity
Persist Checkout, Transaction, Authorization, Charge, and Refund identifiers. Use business idempotency keys and check the current Affirm state before retrying capture or refund operations.
Synchronization and limits
Respect applicable rate limits, pagination behavior, and response headers. Scheduled retrieval should use bounded windows, checkpoints, and a safety overlap for late-arriving changes.
Amounts and reconciliation
Preserve currency and monetary precision, validate refund amounts against captured amounts, and reconcile commerce totals, Affirm statuses, fulfillment state, and accounting records.
Change management
Pin or track the applicable API version, treat status values and webhook payloads as versioned contracts, and maintain tests for checkout, capture, void, and refund scenarios.
Why use Martini instead of scripts or point-to-point integrations?
Centralized orchestration
Martini separates Affirm payment lifecycle logic from individual commerce, order, finance, and support applications. Workflows can coordinate API calls, events, validation, downstream writes, and exception paths.
Reusable integration assets
Teams can expose controlled Martini APIs, reuse payment orchestration logic, and apply consistent mappings and business rules across multiple applications and merchants.
Operational reliability
Compared with isolated scripts, Martini provides structured workflow execution, secure configuration, error handling, retry design, monitoring, and reconciliation patterns for payment operations.
Frequently asked questions
Affirm can be integrated through its HTTPS REST APIs for checkout, transaction retrieval, authorization, capture, void, and refund operations. Affirm also provides client-side checkout resources and webhook-style notifications for selected payment and transaction events. Server-side requests use merchant-issued credentials and JSON payloads.
Yes. Martini can integrate with Affirm by consuming its REST APIs, receiving selected webhook notifications, securely managing Affirm credentials, orchestrating payment lifecycle workflows, and mapping Affirm JSON data to commerce, order, finance, support, or analytics systems.
No. A dedicated Affirm connector is not required. Martini can use Affirm’s confirmed native integration mechanisms, including REST APIs, selected webhook notifications, JSON payloads, and server-side authentication.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Affirm. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Affirm, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
Affirm REST APIs are the primary method for merchant-side operations such as checkout, capture, void, transaction retrieval, and refunds. Selected webhook notifications can complement REST calls for payment state changes. No official Affirm GraphQL or SOAP API was confirmed, and no general-purpose bulk or file API was confirmed.
Affirm provides webhook-style notifications for selected transaction and payment events, but coverage is not universal. Implementations should confirm the enabled event types, payload, signature-validation requirements, retry behavior, and duplicate-delivery expectations for the merchant account and API version.
Martini can synchronize data in real time through selected webhook notifications or through workflows that call Affirm REST endpoints. Scheduled synchronization should use applicable retrieval and filtering behavior, pagination, bounded date windows, checkpoints, overlap protection, and duplicate handling.
Martini workflows can validate inputs, route errors, apply bounded retries with backoff, and record operation identifiers. Capture and refund operations should be idempotent: after an ambiguous failure, the workflow should check the current Affirm state before retrying to avoid duplicate payment actions.
Related Martini documentation
Affirm APIs
Workflows
Build a reliable Affirm integration with Martini
Use Martini to orchestrate Affirm REST APIs and selected webhook events across commerce, fulfillment, finance, support, and analytics systems with secure credentials, reusable workflows, data mapping, and operational controls.