Checkout.com

What you need

In the Checkout.com Dashboard:

• secret_key: Developers → API keys: the secret key (sk_sbox_… for sandbox, sk_… for live).
• client_id: the cli_… value in the top right corner of the Settings → Account structure tab. Checkout.com gives every account its own API host (https://<prefix>.api.checkout.com); the prefix is the first eight characters after cli_, and the panel derives it itself. You can also enter the prefix directly (the subdomain of the base URL shown under Developers → Overview). Left empty, the panel tries the un-prefixed api.checkout.com.
• webhook_secret: the signature key you generate in the webhook configuration (see below).

In your panel choose Settings → Payments → Add method → Checkout.com and enter the three values.

Sandbox: enter the sandbox account's sk_sbox_… key and its client_id, and tick sandbox (test) mode; the panel then talks to <prefix>.api.sandbox.checkout.com. Live and sandbox have different client_id values.

Hosted Payments Page has to be enabled on your account; Checkout.com asks you to contact your solution engineer or support for that.

Webhook (required)

Balance is credited only by the webhook Checkout.com sends server to server; the customer's browser return credits nothing. The webhook therefore must be configured on the Checkout.com side:

1. Dashboard → Developers → Webhooks → Create configuration.
2. Endpoint URL:

https://<your-panel-domain>/payments/checkout_com/callback

1. Under Signature key press Generate key and enter the value in the panel as webhook_secret. (The authorization header key is not checked by the panel; you do not need to generate one.)
2. Tick these event types: payment_captured, payment_approved, payment_declined, payment_capture_declined, payment_pending, payment_expired, payment_canceled.
3. Do this separately for sandbox and live; keys are per environment.

The panel compares each webhook's Cko-Signature header with the HMAC-SHA256 (hex) of the raw body under webhook_secret; a mismatch is rejected with 400. Every verified webhook is acknowledged with 200 within 10 seconds.

Flow

1. The customer enters an amount and picks Checkout.com. No phone number is asked for.
2. The panel opens a session with POST /hosted-payments: the amount in minor units (250.00 TRY → 25000), reference = our payment reference, capture: true (an approved amount is captured at once), customer_retry.max_attempts: 0 (a declined attempt ends the session). The customer is redirected to the page on pay.checkout.com; card entry and 3D Secure happen there.
3. When the payment finishes, the customer returns through success_url / failure_url / cancel_url to the panel's /payments/checkout_com/return, which only forwards to "Add funds".
4. Checkout.com sends the webhook. On payment_captured the payment completes and the balance is credited (data.amount converted back from minor units is stored). A second delivery of the same evt_… id is ignored; balance is never credited twice.
5. Webhooks may arrive out of order; a payment_approved after payment_captured does not touch the already completed payment.

Statuses

Event	Result in the panel
payment_captured	completed, balance credited
payment_approved, payment_pending	pending (awaiting capture / redirect)
payment_declined, payment_capture_declined	failed; response_summary goes into the payment memo
payment_canceled	failed (customer cancelled)
payment_expired	expired
other events (payment_refunded, payment_voided…)	leave an open payment pending, never touch a completed one

Currencies

Your panel currency must be one your Checkout.com account can process (TRY included). Amount conversion follows Checkout.com's rule: JPY, KRW, ISK, VND and the like are whole numbers; BHD, KWD, OMR, JOD, TND, IQD, LYD are divided by 1000; every other currency by 100.

Billing country

Checkout.com requires billing.address.country and a panel does not know its customer's country. The panel first looks at the method's extra.billing_country (two-letter country code); otherwise it sends the country of the panel currency (TRY → TR, USD → US, EUR → DE…). The field can affect risk rules; set it if your market differs.

Common problems

• "Payment could not start: HTTP 401": the key is for the other environment (sk_sbox_… in live or vice versa) or the client_id prefix belongs to another account.
• Payment succeeded but no balance: the webhook configuration is missing or webhook_secret is another configuration's key. Check the delivery log under Dashboard → Developers → Webhooks; a 400 from the panel means the signature did not match. Checkout.com retries a failed webhook eight times.
• Payment stuck in "pending": only payment_approved arrived and payment_captured is not ticked. Check the event types; the payment completes by itself once the capture event arrives.
• billing_address_country_required / currency_invalid: your processing channel does not support that currency; ask Checkout.com.
• Card declined in sandbox: use Checkout.com's test cards; real cards do not work in the sandbox.