Checkout.com Integration

Checkout.com is a cloud-based payment platform built for high-growth and enterprise businesses. LostChurn connects to Checkout.com via API key and processes webhook notifications to detect failed payments and automate recovery.

Prerequisites

• An active Checkout.com account
• Access to The Hub (Checkout.com's management dashboard) with admin permissions
• A Checkout.com Secret Key (starts with sk_ for live or sk_test_ for sandbox)
• A LostChurn account with at least one workspace created

Connection Steps

1. Log in to The Hub.
2. Navigate to Settings > Channels and select your processing channel.
3. Under API Keys, locate your Secret Key and Public Key. If you need a new key pair, click Generate New Keys.
4. Copy the Secret Key (you will need to confirm generation, as the key is shown only once).
5. In your LostChurn dashboard, go to Settings > Integrations and click Connect Checkout.com.
6. Select your environment: Sandbox or Production.
7. Paste the Secret Key and click Save and Verify. LostChurn makes a test API call to confirm the key is valid.

Webhook Configuration

1. In The Hub, navigate to Settings > Channels and select your processing channel.
2. Click Webhooks in the left sidebar.
3. Click Add Webhook.
4. Set the URL to:

   https://webhooks.lostchurn.com/v1/checkoutcom

5. Under Events, select the following:
   • payment_declined
   • payment_captured
   • payment_approved
   • payment_voided
   • payment_refunded
   • payment_expired
   • payment_capture_declined
   • payment_refund_declined
   • card_verified
   • card_verification_declined
   • dispute_evidence_required
   • dispute_won
   • dispute_lost
   • dispute_expired
   • source_updated
6. Under Authorization, set the Signing Key. This key is auto-generated by Checkout.com. Copy it.
7. Click Save.
8. In your LostChurn dashboard, paste the Signing Key into the Webhook Signing Key field on the Checkout.com integration page.

Webhook Signature Verification

Checkout.com signs webhook payloads with an HMAC-SHA256 signature using the Signing Key. The hex-encoded signature is sent in the Cko-Signature HTTP header. LostChurn computes HMAC-SHA256 of the raw request body using your Signing Key and compares the hex digest against the Cko-Signature value using a timing-safe comparison. Requests with missing or invalid signatures are rejected with a 401 response.

Verify Connection

1. In The Hub, go to Settings > Channels > Webhooks and select the LostChurn webhook.
2. Click Test to send a test event.
3. Verify the endpoint responds successfully (HTTP 200).
4. In your LostChurn dashboard, navigate to Events and confirm the test event appears.
5. For a more thorough test, process a test payment in the Checkout.com Sandbox using one of their test cards:
   • Use card number 4242424242424242 with amount 100.00 and 3DS simulation to trigger a decline.

A successful connection shows a green Connected badge on the Checkout.com card in Settings > Integrations.

Supported Events

Provider-Specific Notes

Sandbox vs. Production

Checkout.com provides separate sandbox and production environments:

• Sandbox (api.sandbox.checkout.com): Test transactions with test card numbers. Keys start with sk_test_ and pk_test_.
• Production (api.checkout.com): Real transactions. Keys start with sk_ and pk_.

Both environments can be connected to LostChurn simultaneously. Sandbox events are labeled with a sandbox badge.

Response Codes

Checkout.com provides detailed response codes for declined payments. LostChurn maps these to its internal decline taxonomy:

• 20005 — Do Not Honor: Generic decline, retry eligible.
• 20051 — Insufficient Funds: Retry on a different day (e.g., after payday).
• 20054 — Expired Card: Triggers dunning email for payment method update.
• 20014 — Invalid Card Number: Requires customer to re-enter payment details.
• 20065 — Withdrawal Limit Exceeded: Retry with a lower amount or after a delay.
• 30004 — Suspected Fraud: No automatic retry, flagged for review.

The full mapping is available in Settings > Integrations > Checkout.com > Decline Code Mapping.

Network Tokens

Checkout.com supports network tokenization, which replaces card PANs with network-provisioned tokens. LostChurn supports retries using network tokens and Account Updater data, which can improve authorization rates on retries by up to 3-5%.

Intelligent Acceptance

Checkout.com offers an Intelligent Acceptance product that optimizes routing and retry logic. When using LostChurn alongside Intelligent Acceptance:

• LostChurn respects Checkout.com's routing decisions and does not override them.
• LostChurn adds dunning email, SMS, and in-app messaging capabilities that complement Checkout.com's server-side retry optimization.
• Recovery attribution is tracked separately for each system.

Processing Channels

Checkout.com organizes processing through channels (entities). If you have multiple processing channels (e.g., different geographies or business lines), connect each channel to LostChurn separately using channel-specific API keys.

Rate Limits

Checkout.com rate limits vary by account and are not publicly documented. LostChurn uses a conservative default of 10 requests per second and automatically adjusts based on 429 (Too Many Requests) responses. If you have a high-volume account with custom rate limits, contact LostChurn support to optimize throughput.

3D Secure

Checkout.com supports 3D Secure 2 (3DS2) for Strong Customer Authentication. When a retry requires 3DS, LostChurn sends the customer a secure link to complete the authentication challenge. The result flows back through Checkout.com's webhook notifications.