> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/payments/integrations/providers/checkout-com.md).

# Checkout.com

Connect Checkout.com to Payments — keys, webhook URL and signing secret.

Checkout.com takes card and local payments worldwide. Norbix gets its payment webhooks (approved, captured, declined, refunded, canceled, disputes).

## Get your credentials

1. Sign in to the [Checkout.com Dashboard](https://dashboard.checkout.com/) (the sandbox for tests).
2. Note your entity id (`ent_…`) — Cloud calls it **Merchant Account**.
3. Open **Developers → Keys** and create a secret key (see [Manage API keys](https://www.checkout.com/docs/developer-resources/api/manage-api-keys)).
4. Save the integration in Cloud once (below) to get its **Webhook URL**.
5. Create a webhook (in the Dashboard under **Workflows**) that sends the payment events to the webhook URL (see [Webhooks](https://www.checkout.com/docs/developer-resources/webhooks)), copy its authorization / signature secret into **Webhook Secret**, type the secret key again, and **Save**.

## Connect it in Cloud

**Where:** Payments → Integrations → **Add New Integration** → Checkout.com → **Connect** · `/projects/<project>/payments/integrations/new/checkout-com`

| Field            | Required | What it does                                                                                                                                              | Example                |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| Merchant Account | yes      | Your Checkout.com entity.                                                                                                                                 | `ent_…`                |
| Environment      | yes      | `sandbox` or `production` — type the word.                                                                                                                | `sandbox`              |
| Secret Key       | yes      | Lets Norbix call Checkout.com. Secret; encrypted on save and never shown again — type it again whenever you press **Save**.                               | `sk_sbox_…`            |
| Webhook Secret   | no       | Checks the `CKO-Signature` header of each call — needed for payment triggers. It is shown as plain text while you type and is not shown again after save. | `your-webhook-secret`  |
| Integration Name | yes      | The name in your integrations list.                                                                                                                       | `Checkout.com sandbox` |

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-bc653a736c5907cbd832d402d1fb1b13a764531d%2Fcheckout-com-form-1.png?alt=media" alt="New Checkout.com Integration form filled with example values"><figcaption><p>The filled form (placeholder values).</p></figcaption></figure>

Press **Save**. The page turns into **Editing Checkout.com integration** with the badges **ENABLED**, **NOT TESTED**, **NOT CONFIRMED**, the integration id (`int_1r750GVsGp3GKYOlbPRWo7`) and the **Webhook URL** — `<Hub address>/v3/payments/webhooks/<account id>/<project id>/checkoutcom/<integration id>`; outside PROD it ends with `?env=<ENV>`. Copy it with its copy button and paste it at Checkout.com (see **Get your credentials**). **Received webhooks** at the bottom lists every call Checkout.com makes to it.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-66d18ee289ceb026d6fa5f208e57b9b018d4cc42%2Fcheckout-com-saved-2.png?alt=media" alt="Editing Checkout.com integration after Save: ENABLED, NOT TESTED, NOT CONFIRMED, the integration id and the Webhook URL"><figcaption><p>After save: the webhook URL to paste at Checkout.com.</p></figcaption></figure>

Events Norbix accepts from Checkout.com (pick them at Checkout.com and in your [trigger](/codemash/cloud/payments/triggers/new.md)): `payment_approved`, `payment_captured`, `payment_declined`, `payment_refunded`, `payment_canceled`, `dispute_received`.

## Test and set as default

**Test integration** only checks that the saved fields and secret are filled in and well-formed; it does not call Checkout.com, so it can pass with a wrong key — it passed with the made-up values of this example. Send a test payment and check **Received webhooks**. See [Test an integration](/codemash/cloud/payments/integrations/test.md). Payments has no default integration — every enabled integration gets its own calls ([Default integration](/codemash/cloud/payments/integrations/set-default.md)).

## Common errors

| Message                             | Cause                                                        | Fix                                                                        |
| ----------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------- |
| **Received webhooks** shows **400** | The webhook secret is empty or wrong.                        | Copy the secret of the webhook again into **Webhook Secret** and **Save**. |
| Required                            | An empty required field.                                     | Fill every field marked required.                                          |
| Required                            | A required field is empty — secrets count too on every save. | Fill the field; type every secret again before **Save**.                   |

## Do it from code

```ts
const { id } = await norbix.hub.payments.savePaymentsIntegration({
  integration: {
    provider: 'CheckOutCom',
    integrationName: 'Checkout.com live',
    isEnabled: true,
    merchantAccount: 'ent_your_entity_id',
    environment: 'production',
    secretKey: 'sk_your_secret_key',
    webhookSecret: 'your-webhook-secret',
  } as any, // the TS type knows only the shared fields
});
console.log(id); // int_…
```

```sh
norbix hub payments integration save --integration '{"provider":"CheckOutCom","integrationName":"Checkout.com live","isEnabled":true,"merchantAccount":"ent_your_entity_id","environment":"production","secretKey":"sk_your_secret_key","webhookSecret":"your-webhook-secret"}'
```

The client setup is on the [Payments page](/codemash/cloud/payments.md#use-it-from-code). API: [Save Payments Integration](/codemash/api-reference/payments/integrations/save-payments-integration.md)