Gateways | OrderCard Documentation

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 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.

Required ability: gateways:read
Rate limit: 300 requests/minute per API key

Query parameters

typestringoptional: test, fortis, nmi, authorize_net, converge or deluxe.
limitintegeroptional: 1 to 100, default 25.
cursorstringoptional: The meta.next_cursor of the previous page.

Requestbash

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

200A page of gateways.

{ "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.

Required ability: gateways:write
Rate limit: 300 requests/minute per API key

Body parameters

typestringrequired: test (sandbox only), fortis, nmi, authorize_net, converge or deluxe.
namestringrequired: Your label, max 100 characters.
Example: NMI main
credentialsobjectrequired: 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_defaultbooleanoptional: Make it the environment's default gateway.
activebooleanoptional: Default true. An inactive gateway refuses new charges; refunds still work.
settings.surchargeobjectoptional: How OrderCard surcharges credit cards on this gateway. Not accepted for Fortis, which decides surcharges itself (use sync).
settings.surcharge.enabledbooleanoptional: Surcharge credit and charge cards. Needs a rate.
settings.surcharge.ratenumberoptional: Percent, above 0 and at most 3.
Example: 3
settings.surcharge.on_recurringbooleanoptional: Also surcharge charges sent with initiator recurring. Default false.
settings.surcharge.send_surcharge_elementbooleanoptional: Authorize.net only: send the surcharge as its own field (supported on TSYS). Default true.

Caveats

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

Requestbash

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": "..." } }'

201The connected gateway.

{
  "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
}

422A credential is missing.

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

Retrieve a gateway

GET/v1/gateways/{id}

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

Required ability: gateways:read
Rate limit: 300 requests/minute per API key

Path parameters

idstringrequired: The gateway's id.
Example: gw_01jaxr2d5f8g0h3j6k9m2n5p8q

Requestbash

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

200The gateway.

{
  "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.

Required ability: gateways:write
Rate limit: 300 requests/minute per API key

Path parameters

idstringrequired: The gateway's id.
Example: gw_01jaxr2d5f8g0h3j6k9m2n5p8q

Body parameters

namestringoptional: Your label.
credentialsobjectoptional: Only the fields you want to change.
is_defaultbooleanoptional: Make it the default gateway.
activebooleanoptional: Turn the gateway on or off.
settings.surchargeobjectoptional: How OrderCard surcharges credit cards on this gateway. Not accepted for Fortis, which decides surcharges itself (use sync).
settings.surcharge.enabledbooleanoptional: Surcharge credit and charge cards. Needs a rate.
settings.surcharge.ratenumberoptional: Percent, above 0 and at most 3.
Example: 3
settings.surcharge.on_recurringbooleanoptional: Also surcharge charges sent with initiator recurring. Default false.
settings.surcharge.send_surcharge_elementbooleanoptional: Authorize.net only: send the surcharge as its own field (supported on TSYS). Default true.

Requestbash

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 } } }'

200The updated gateway.

{
  "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.

Required ability: gateways:write
Rate limit: 300 requests/minute per API key

Path parameters

idstringrequired: The gateway's id.
Example: gw_01jaxr2d5f8g0h3j6k9m2n5p8q

Requestbash

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

200The removed gateway.

{ "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.

Required ability: gateways:write
Rate limit: 300 requests/minute per API key

Path parameters

idstringrequired: The gateway's id.
Example: gw_01jaxr2d5f8g0h3j6k9m2n5p8q

Requestbash

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

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

{
  "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.

Required ability: gateways:write
Rate limit: 300 requests/minute per API key

Path parameters

idstringrequired: The gateway's id.
Example: gw_01jaxr2d5f8g0h3j6k9m2n5p8q

Requestbash

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

200The gateway with its synced settings.

{
  "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
}

409The gateway type keeps no configuration to read.

{ "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.

Required ability: transactions:write
Rate limit: 300 requests/minute per API key

Path parameters

idstringrequired: The gateway's id.
Example: gw_01jaxr2d5f8g0h3j6k9m2n5p8q

Body parameters

payment_method_tokenstringoptional: A vaulted card. Send this, card_type or first6.
card_typestringoptional: 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
first6stringoptional: The card's first 6 to 8 digits, for pages without hosted fields.
Example: 424242
amountintegerrequired: The amount before surcharge, in minor units (cents).
Example: 10000
billing.statestringoptional: Billing state; some states ban surcharges.
billing.postal_codestringoptional: Billing postal code.
billing.countrystringoptional: Two-letter country code.
initiatorstringoptional: customer (default), merchant or recurring.

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.

Requestbash

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 }'

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

{
  "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."
}