---
title: "Gateways"
description: "Connect your payment gateway accounts, test them, and quote surcharges."
image: "https://docs.ordercard.io/og.png"
---

> API Reference Index
> Fetch the complete API index at: https://docs.ordercard.io/api/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateways

A gateway is one of your merchant accounts: Fortis, NMI, Authorize.net, Converge (Elavon), Deluxe, or the built-in test gateway that sandbox keys can use without any account. Charge a vaulted card through any of them by id; the card does not belong to a gateway, so you can move processors without re-collecting cards.

Credentials are encrypted in the vault and only ever come back masked: secrets show their last four characters. The [gateway guides](/gateways) list each provider's fields and quirks.

Each gateway also has an `events_url`. Give it to gateways that can post transaction status updates; OrderCard records them against the matching transaction.

## List gateways

`GET /v1/gateways`

Lists the gateways of the key's team and environment, newest first.

- **Operation id:** `gateways.list`
- **Required ability:** `gateways:read`
- **Rate limit:** 300 requests/minute per API key

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | no | test, fortis, nmi, authorize_net, converge or deluxe. |
| `limit` | integer | no | 1 to 100, default 25. |
| `cursor` | string | no | The meta.next_cursor of the previous page. |

#### Request

```bash
curl https://api.ordercard.io/v1/gateways \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — A page of gateways.

```json
{ "data": [ {
    "object": "gateway",
    "id": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q",
    "type": "nmi",
    "type_label": "NMI",
    "name": "NMI main",
    "environment": "live",
    "active": true,
    "is_default": true,
    "credentials": {
      "security_key": "••••9876",
      "processor_id": null
    },
    "surcharge": {
      "enabled": true,
      "rate": 3,
      "on_recurring": false,
      "decided_by": "ordercard",
      "unsupported_reason": null,
      "disclosure": "A 3% surcharge is added to credit card payments. It is not more than our cost of accepting credit cards. Debit and prepaid cards are not surcharged."
    },
    "settings": { "surcharge": { "enabled": true, "rate": 3 } },
    "events_url": "https://api.ordercard.io/gateway-events/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/3f9c…",
    "last_verified_at": "2026-10-17T15:10:00+00:00",
    "last_verification_error": null,
    "created_at": "2026-10-17T15:09:12+00:00",
    "updated_at": "2026-10-17T15:10:00+00:00",
    "deleted": false
  } ], "links": { "...": "..." }, "meta": { "...": "..." } }
```

## Connect a gateway

`POST /v1/gateways`

Connects a gateway account. Credentials are encrypted in the vault and only ever returned masked. The first gateway of an environment becomes its default.

- **Operation id:** `gateways.create`
- **Required ability:** `gateways:write`
- **Rate limit:** 300 requests/minute per API key

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | yes | test (sandbox only), fortis, nmi, authorize_net, converge or deluxe. |
| `name` | string | yes | Your label, max 100 characters. Example: `NMI main` |
| `credentials` | object | yes | The fields the gateway type needs. fortis: user_id, user_api_key, location_id. nmi: security_key, processor_id (optional). authorize_net: login_id, transaction_key. converge: account_id, user_id, pin. deluxe: client_id, client_secret, partner_token. test: none. |
| `is_default` | boolean | no | Make it the environment's default gateway. |
| `active` | boolean | no | Default true. An inactive gateway refuses new charges; refunds still work. |
| `settings.surcharge` | object | no | How OrderCard surcharges credit cards on this gateway. Not accepted for Fortis, which decides surcharges itself (use sync). |
| `settings.surcharge.enabled` | boolean | no | Surcharge credit and charge cards. Needs a rate. |
| `settings.surcharge.rate` | number | no | Percent, above 0 and at most 3. Example: `3` |
| `settings.surcharge.on_recurring` | boolean | no | Also surcharge charges sent with initiator recurring. Default false. |
| `settings.surcharge.send_surcharge_element` | boolean | no | Authorize.net only: send the surcharge as its own field (supported on TSYS). Default true. |

#### Request

```bash
curl -X POST https://api.ordercard.io/v1/gateways \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "nmi", "name": "NMI main", "credentials": { "security_key": "..." } }'
```

#### Responses

##### 201 — The connected gateway.

```json
{
  "object": "gateway",
  "id": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q",
  "type": "nmi",
  "type_label": "NMI",
  "name": "NMI main",
  "environment": "live",
  "active": true,
  "is_default": true,
  "credentials": {
    "security_key": "••••9876",
    "processor_id": null
  },
  "surcharge": {
    "enabled": true,
    "rate": 3,
    "on_recurring": false,
    "decided_by": "ordercard",
    "unsupported_reason": null,
    "disclosure": "A 3% surcharge is added to credit card payments. It is not more than our cost of accepting credit cards. Debit and prepaid cards are not surcharged."
  },
  "settings": { "surcharge": { "enabled": true, "rate": 3 } },
  "events_url": "https://api.ordercard.io/gateway-events/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/3f9c…",
  "last_verified_at": "2026-10-17T15:10:00+00:00",
  "last_verification_error": null,
  "created_at": "2026-10-17T15:09:12+00:00",
  "updated_at": "2026-10-17T15:10:00+00:00",
  "deleted": false
}
```

##### 422 — A credential is missing.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The transaction key field is required.",
    "errors": { "credentials.transaction_key": ["The transaction key field is required."] }
  }
}
```

#### Caveats

- Creating a gateway does not contact it. Call the test endpoint to check the credentials.

## Retrieve a gateway

`GET /v1/gateways/{id}`

Returns one gateway with masked credentials and its surcharge set-up.

- **Operation id:** `gateways.get`
- **Required ability:** `gateways:read`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The gateway's id. Example: `gw_01jaxr2d5f8g0h3j6k9m2n5p8q` |

#### Request

```bash
curl https://api.ordercard.io/v1/gateways/gw_01jaxr2d5f8g0h3j6k9m2n5p8q \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — The gateway.

```json
{
  "object": "gateway",
  "id": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q",
  "type": "nmi",
  "type_label": "NMI",
  "name": "NMI main",
  "environment": "live",
  "active": true,
  "is_default": true,
  "credentials": {
    "security_key": "••••9876",
    "processor_id": null
  },
  "surcharge": {
    "enabled": true,
    "rate": 3,
    "on_recurring": false,
    "decided_by": "ordercard",
    "unsupported_reason": null,
    "disclosure": "A 3% surcharge is added to credit card payments. It is not more than our cost of accepting credit cards. Debit and prepaid cards are not surcharged."
  },
  "settings": { "surcharge": { "enabled": true, "rate": 3 } },
  "events_url": "https://api.ordercard.io/gateway-events/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/3f9c…",
  "last_verified_at": "2026-10-17T15:10:00+00:00",
  "last_verification_error": null,
  "created_at": "2026-10-17T15:09:12+00:00",
  "updated_at": "2026-10-17T15:10:00+00:00",
  "deleted": false
}
```

## Update a gateway

`PATCH /v1/gateways/{id}`

Changes the name, flags, surcharge settings or credentials. Credentials you leave out keep their value; changing any credential clears the last successful connection test.

- **Operation id:** `gateways.update`
- **Required ability:** `gateways:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The gateway's id. Example: `gw_01jaxr2d5f8g0h3j6k9m2n5p8q` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Your label. |
| `credentials` | object | no | Only the fields you want to change. |
| `is_default` | boolean | no | Make it the default gateway. |
| `active` | boolean | no | Turn the gateway on or off. |
| `settings.surcharge` | object | no | How OrderCard surcharges credit cards on this gateway. Not accepted for Fortis, which decides surcharges itself (use sync). |
| `settings.surcharge.enabled` | boolean | no | Surcharge credit and charge cards. Needs a rate. |
| `settings.surcharge.rate` | number | no | Percent, above 0 and at most 3. Example: `3` |
| `settings.surcharge.on_recurring` | boolean | no | Also surcharge charges sent with initiator recurring. Default false. |
| `settings.surcharge.send_surcharge_element` | boolean | no | Authorize.net only: send the surcharge as its own field (supported on TSYS). Default true. |

#### Request

```bash
curl -X PATCH https://api.ordercard.io/v1/gateways/gw_01jaxr2d5f8g0h3j6k9m2n5p8q \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "settings": { "surcharge": { "enabled": true, "rate": 3 } } }'
```

#### Responses

##### 200 — The updated gateway.

```json
{
  "object": "gateway",
  "id": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q",
  "type": "nmi",
  "type_label": "NMI",
  "name": "NMI main",
  "environment": "live",
  "active": true,
  "is_default": true,
  "credentials": {
    "security_key": "••••9876",
    "processor_id": null
  },
  "surcharge": {
    "enabled": true,
    "rate": 3,
    "on_recurring": false,
    "decided_by": "ordercard",
    "unsupported_reason": null,
    "disclosure": "A 3% surcharge is added to credit card payments. It is not more than our cost of accepting credit cards. Debit and prepaid cards are not surcharged."
  },
  "settings": { "surcharge": { "enabled": true, "rate": 3 } },
  "events_url": "https://api.ordercard.io/gateway-events/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/3f9c…",
  "last_verified_at": "2026-10-17T15:10:00+00:00",
  "last_verification_error": null,
  "created_at": "2026-10-17T15:09:12+00:00",
  "updated_at": "2026-10-17T15:10:00+00:00",
  "deleted": false
}
```

## Remove a gateway

`DELETE /v1/gateways/{id}`

Removes the gateway. Its transactions stay, and captures, voids and refunds of them still go to the gateway with the stored credentials.

- **Operation id:** `gateways.delete`
- **Required ability:** `gateways:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The gateway's id. Example: `gw_01jaxr2d5f8g0h3j6k9m2n5p8q` |

#### Request

```bash
curl -X DELETE https://api.ordercard.io/v1/gateways/gw_01jaxr2d5f8g0h3j6k9m2n5p8q \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — The removed gateway.

```json
{ "object": "gateway", "id": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q", "active": false, "deleted": true, "...": "..." }
```

## Test the connection

`POST /v1/gateways/{id}/test`

Checks the stored credentials with the gateway without moving money, and records the result on the gateway.

- **Operation id:** `gateways.test`
- **Required ability:** `gateways:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The gateway's id. Example: `gw_01jaxr2d5f8g0h3j6k9m2n5p8q` |

#### Request

```bash
curl -X POST https://api.ordercard.io/v1/gateways/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/test \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — The result. ok is false when the gateway refused the credentials.

```json
{
  "object": "gateway_connection_test",
  "gateway": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q",
  "ok": false,
  "message": "NMI rejected the API security key. Use a private key with the API permission."
}
```

## Sync the surcharge set-up

`POST /v1/gateways/{id}/sync`

Reads the surcharge configuration a gateway keeps itself: the card product and surcharge settings of a Fortis location, or a Converge terminal's settings.

- **Operation id:** `gateways.sync`
- **Required ability:** `gateways:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The gateway's id. Example: `gw_01jaxr2d5f8g0h3j6k9m2n5p8q` |

#### Request

```bash
curl -X POST https://api.ordercard.io/v1/gateways/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/sync \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — The gateway with its synced settings.

```json
{
  "object": "gateway",
  "id": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q",
  "type": "nmi",
  "type_label": "NMI",
  "name": "NMI main",
  "environment": "live",
  "active": true,
  "is_default": true,
  "credentials": {
    "security_key": "••••9876",
    "processor_id": null
  },
  "surcharge": {
    "enabled": true,
    "rate": 3,
    "on_recurring": false,
    "decided_by": "ordercard",
    "unsupported_reason": null,
    "disclosure": "A 3% surcharge is added to credit card payments. It is not more than our cost of accepting credit cards. Debit and prepaid cards are not surcharged."
  },
  "settings": { "surcharge": { "enabled": true, "rate": 3 } },
  "events_url": "https://api.ordercard.io/gateway-events/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/3f9c…",
  "last_verified_at": "2026-10-17T15:10:00+00:00",
  "last_verification_error": null,
  "created_at": "2026-10-17T15:09:12+00:00",
  "updated_at": "2026-10-17T15:10:00+00:00",
  "deleted": false
}
```

##### 409 — The gateway type keeps no configuration to read.

```json
{ "error": { "code": "sync_not_supported", "message": "NMI keeps no configuration for OrderCard to read." } }
```

## Quote a surcharge

`POST /v1/gateways/{id}/surcharge`

Works out the surcharge for a card and amount before you charge, so checkout can show it. Pass a vaulted card's token, or, before the card is tokenized, the card type the hosted fields cardMeta event reports.

- **Operation id:** `gateways.surcharge`
- **Required ability:** `transactions:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The gateway's id. Example: `gw_01jaxr2d5f8g0h3j6k9m2n5p8q` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `payment_method_token` | string | no | A vaulted card. Send this, card_type or first6. |
| `card_type` | string | no | Before the card is tokenized: the type from the hosted fields cardMeta event (credit, charge, debit, prepaid or unknown). Quote credit while it is pending. Example: `credit` |
| `first6` | string | no | The card's first 6 to 8 digits, for pages without hosted fields. Example: `424242` |
| `amount` | integer | yes | The amount before surcharge, in minor units (cents). Example: `10000` |
| `billing.state` | string | no | Billing state; some states ban surcharges. |
| `billing.postal_code` | string | no | Billing postal code. |
| `billing.country` | string | no | Two-letter country code. |
| `initiator` | string | no | customer (default), merchant or recurring. |

#### Request

```bash
curl -X POST https://api.ordercard.io/v1/gateways/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/surcharge \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e", "amount": 10000 }'
```

#### Responses

##### 200 — The quote. waived_reason says why there is none: disabled, recurring, state, debit, prepaid, unknown_card or gateway.

```json
{
  "object": "surcharge_quote",
  "gateway": "gw_01jaxr2d5f8g0h3j6k9m2n5p8q",
  "card_type": "credit",
  "amount": 10000,
  "surcharge_amount": 300,
  "total_amount": 10300,
  "surcharge_rate": 3,
  "source": "platform",
  "waived_reason": null,
  "estimate": false,
  "disclosure": "A 3% surcharge is added to credit card payments. It is not more than our cost of accepting credit cards. Debit and prepaid cards are not surcharged."
}
```

#### Caveats

- For Fortis and Converge the quote is an estimate (estimate: true): they decide the final figure when the card is charged. Send max_total with the charge to never take more than you showed.

Source: https://docs.ordercard.io/api/gateways/index.mdx