Checkout.com | Primer

Checkout.com is a global payment processor offering acquiring, alternative payment methods and payment optimization tools across every major market. Through Primer you can process cards, digital wallets and a broad set of alternative payment methods on a single Checkout.com connection.

At a glance

Supported payment methods

Payment method	Payment method type	Integration guide
Card	`PAYMENT_CARD`	Card
Apple Pay	`APPLE_PAY`	Apple Pay
Google Pay	`GOOGLE_PAY`	Google Pay
Bancontact	`CHECKOUT_BANCONTACT`	Bancontact via Checkout.com
iDEAL	`CHECKOUT_IDEAL`	iDEAL via Checkout.com
MB Way	`CHECKOUT_MBWAY`	MB Way
MobilePay	`CHECKOUT_MOBILEPAY`	MobilePay via Checkout.com
Multibanco	`CHECKOUT_MULTIBANCO`	Multibanco
Pinless Debit	`CHECKOUT_PINLESS_DEBIT`	Pinless Debit via Checkout.com
TWINT	`CHECKOUT_TWINT`	TWINT via Checkout.com
Vipps	`CHECKOUT_VIPPS`	Vipps via Checkout.com

Supported capabilities

Capability	Card	Apple Pay and Google Pay	Alternative payment methods
Authorization and capture	Yes	Yes	Yes
Partial capture	Yes	Yes	No
Authorization adjustment	Yes	Yes	No
Refund	Yes	Yes	Yes
Partial refund	Yes	Yes	Yes
Multiple refunds	Yes	Yes	Yes
Recurring and merchant-initiated payments	Yes	Yes	No
Network tokens	Yes	Yes	Not applicable

Some capabilities must be enabled on your Checkout.com account. Contact Checkout.com to confirm which features are available to you.

3D Secure

Primer performs 3D Secure authentication using the Perform 3DS action and passes the authentication result to Checkout.com. Primer only forwards the 3D Secure data when the authentication returns a successful or attempted status together with an ECI and a cryptogram, so a challenge that the customer abandons is not sent on as authenticated.

Get started with Checkout.com

Before you begin

If this is your first connection, make sure to follow the Get started guide to begin processing payments with Primer. You need both a Checkout.com sandbox account and a production account. Sandbox accounts are self-served and can be created here Before you connect, you must ask Checkout.com to enable the full card details API on your account. For sandbox Checkout.com only enable Visa and Mastercard automatically, other schemes must be manually enabled.

Enable the full card details API

Email support@checkout.com and ask them to enable all features of the API in both sandbox and production, explaining that you are using Primer as a PCI compliant orchestration platform. If Checkout.com asks for an attestation of compliance, forward Primer’s PCI certification.This step is required. Without it, Primer cannot pass card credentials to Checkout.com.

Find your environment prefix

Log in to the Checkout.com Dashboard and go to Developers > Overview. Your unique base URL is shown there, for example https://vkuhvk4v.api.checkout.com. You can also find it under Settings > Account details > Connection settings.You need only the prefix portion of that URL, which in the example above is vkuhvk4v. The prefix differs between sandbox and production, so make sure the value matches the environment you are configuring.

Credentials

Field	Where to find it
Account	The account name in the top left corner of your Checkout.com payments dashboard.
Secret Key	Checkout.com Dashboard, under Developers > Keys. Select Create a new key, choose Secret API key, then Create key and copy the value.
Processing channel ID	Shown on the Developers > Keys page as a value beginning `pc_`. Optional.
Prefix	Checkout.com Dashboard, under Developers > Overview. Enter only the prefix portion of your base URL. Different per environment.

Configure in the Dashboard

Add Checkout.com to your Dashboard

Go to Integrations, select New integration, search for Checkout.com and enter your credentials.

Configure webhooks in Checkout.com

Log in to the Checkout.com Dashboard and select Developers in the top right. In the Webhooks section, select New webhook and:

Enter a name for the webhook.
Paste your Primer callback URL into the Endpoint URL field.
Leave the Webhook Key field as it is and generate a random Signature Key.
Under Events, select all available events.
Under Entities and processing channels, select All entities.

Select Create webhook to save.

Activate the payment methods on the Checkout

Go to Checkout and activate the Checkout.com payment methods you want to offer.

Route payments with Workflows

In Workflows, select Checkout.com in the Authorize payment action.

Saved cards and merchant-initiated payments

Checkout.com supports recurring and merchant-initiated payments on cards, Apple Pay and Google Pay. See recurring payments for the general Primer flow. Primer sends the network transaction reference from the initial customer-initiated payment on each subsequent merchant-initiated payment, so no processor-side configuration is needed beyond the account setup above.

Considerations

The full card details API is mandatory. Checkout.com must enable it on both your sandbox and production accounts before Primer can process cards. Request it early, because it is handled by Checkout.com support rather than self-serve.
The prefix is environment specific. The prefix from your sandbox account does not work in production. Entering the wrong one produces connection errors that look like credential failures.
Network tokens are supported. Primer can send network tokens to Checkout.com, including tokenized Google Pay credentials, which can improve authorization rates on repeat payments.
Authorization adjustment is available on cards. You can adjust an authorized amount before capture, which suits use cases such as tipping or order amendments.
Alternative payment methods are asynchronous. Most Checkout.com APMs reach a final status through a webhook after the customer completes a redirect. Fulfil orders only on a final status.

Test in sandbox

Connect your Checkout.com sandbox account to your Primer Sandbox environment. Your prefix differs between environments, so use the sandbox prefix here.

Card
Apple Pay
Google Pay
Merchant-initiated

Test a 3DS challenge. Primer performs the authentication, so use Primer’s 3D Secure test cards and enter the one time passcode when the challenge appears.

Network	Card number	OTP
Visa	`4916 9940 6425 2017`	`1234`
Mastercard	`5306 8899 4283 3340`	`1234`

Enter 1234 to pass the challenge or 1111 to fail it. See testing 3D Secure for the full list, including the cards to use on iOS and Android.Test without a 3DS challenge. Use the Perform 3DS action without a mandated challenge indicator. In Primer Sandbox a mandated challenge always produces a challenge, whatever card you use.Test a full end to end flow. Checkout.com accepts a restricted list of card numbers. Use a Checkout.com specific card when you want the card you entered to reach Checkout.com unchanged. 5137 2100 0000 0158 works for Cartes Bancaires and Mastercard, with any future expiry date and any 3 digit CVV.Test a decline. Use a decline card from Checkout.com’s test cards and confirm the decline reason Primer surfaces.Test a saved card. Make a payment that saves the card, then pay again with the saved payment method.

How sandbox differs from production

Internal configuration aspects (such as Hosted Payment Page enablement and full card API) are different across environments. This is also true for Alternative Payment Methods or Reports scheduled generation (such as the Settlement Breakdown Report supported by Primer).

Troubleshooting

Primer maps Checkout.com’s response codes to its own decline reasons. See decline codes for the full list.

Go live

Before switching to production, confirm that:

Your Checkout.com production account is active for the payment methods you want to offer.
Checkout.com has enabled the full card details API on your production account.
You have added Checkout.com in your Primer production environment using your production credentials, including the production prefix.
Your production webhook is configured in the Checkout.com Dashboard and points at your Primer callback URL.
You handle the PAYMENT.STATUS webhook and fulfil orders only on a final status.