Authentication

payitgo has two kinds of credentials:

Your shop's backend only ever needs an API key. Access tokens are for the dashboard: team, keys, webhook secret rotation, balances and payouts.

API keys

Sending the key

Send the key on every /v1 request, in either header:

Authorization: Bearer 4f9c2a7e1b8d3f6a0c5e9b2d7a4f1c8e3b6d9a2f5c8e1b4d7a0f3c6e9b2d5a8f

X-API-Key: 4f9c2a7e1b8d3f6a0c5e9b2d7a4f1c8e3b6d9a2f5c8e1b4d7a0f3c6e9b2d5a8f

When both are present, X-API-Key wins. A complete request:

curl -s https://api.payitgo.co/v1/tokens \
  -H "Authorization: Bearer $PAYITGO_KEY"

A key is 64 hex characters. Treat it as an opaque string: it does not say its mode.

Test keys and live keys

The key decides the mode of everything the request does. There is no mode parameter on /v1. You choose the mode when you create a key, and the dashboard shows it as a Test or Live badge next to the key.

To ask payitgo which mode a key is in, call GET /v1/webhook with it: the answer's livemode is the key's mode (Webhooks).

• GET /v1/tokens lists the tokens of the key's mode.
• POST /v1/payments creates a payment in the key's mode.
• GET /v1/payments and GET /v1/payments/{id} only see payments of the key's mode. A test key gets 404 for a live payment, and the other way round.
• /v1/webhook reads and changes the webhook of the key's mode. Each mode has its own URL and its own signing secret (Webhooks).

Every payment and every webhook notification carries "livemode": true or false, so your code can always tell which mode it is looking at.

Live mode is off until the owner turns it on

A new account starts in test mode. Until the account owner turns live mode on, every request with the live key is refused:

HTTP/1.1 403 Forbidden

{"error": "live mode is off for this account: the owner can turn it on in the dashboard; until then use a test key"}

The owner turns it on with POST /merchant/live (see Account and team). Turning it off again stops new live payments; payments already open still complete.

Storefront keys

A key can belong to a store (one of your shops, see Stores). A storefront key works like any other key, with these differences:

• Every payment it creates carries the store's store_id.

• It only sees its own store's payments: GET /v1/payments lists that store's payments (its store_id filter is ignored), and GET /v1/payments/{id} answers 404 {"error": "payment not found"} for another store's payment.

• It can read the webhook (GET /v1/webhook) and send a test (POST /v1/webhook/test), but it cannot change the account's webhook URL. PUT and DELETE /v1/webhook answer:

  HTTP/1.1 403 Forbidden
  
  {"error": "a storefront's key cannot change the account's webhook: set webhook_url on its payments instead"}
  

  A store that runs its own backend sets webhook_url on each payment it creates, and verifies the notifications with the same signing secret (per-payment webhook URL).

Read-only keys

A key created with "access": "read" can only read: GET /v1/payments, GET /v1/payments/{id}, GET /v1/tokens and GET /v1/webhook. Anything else answers:

HTTP/1.1 403 Forbidden

{"error": "this api key is read-only: it can only read (GET)"}

Give one to a service that reports on payments (an accounting export, a mobile app's order history) and should never create them.

API key errors

Managing keys

Your first test key and live key are issued at signup. Owners and developers can create more (one per environment or service, say) and revoke old ones. These routes take a dashboard access token (see below), not an API key.

The API key object

payitgo stores only a hash of the secret. The secret is returned once, when the key is created, and can never be shown again.

Create a key

POST /merchant/api-keys?mode=test · owner or developer

curl -s 'https://api.payitgo.co/merchant/api-keys?mode=test' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label": "staging"}'

201 Created:

{
  "api_key": {
    "id": "5e1a9c3d7b2f40e8a6c4d2b1",
    "merchant_id": "3f8a1c27b94e05d6a2c71e90",
    "livemode": false,
    "label": "staging",
    "access": "full",
    "last4": "c0da",
    "created_by": "9b2e4c71d8a05f3e6c1a7b24",
    "created_at": "2026-10-10T09:02:33.526679611Z"
  },
  "secret": "e919a75364398a449f860aeadddc57fa0502145a4e63959ddb33c417a48dc0da"
}

Store secret on your server now: it is not shown again.

List keys

GET /merchant/api-keys?mode=test · owner or developer

Lists the keys of one mode, revoked ones included. Without mode=test you get the live keys.

curl -s 'https://api.payitgo.co/merchant/api-keys?mode=test' -H "Authorization: Bearer $ACCESS_TOKEN"

200 OK:

{
  "api_keys": [
    {
      "id": "0e7c5a3f9b1d2846a1f3c5e7",
      "merchant_id": "3f8a1c27b94e05d6a2c71e90",
      "livemode": false,
      "store_id": "6d2a9e4c1b7f30a58e2c4d91",
      "label": "eu-shop",
      "last4": "d05e",
      "created_by": "9b2e4c71d8a05f3e6c1a7b24",
      "created_at": "2026-10-10T08:59:52.982Z",
      "last_used_at": "2026-10-10T08:59:53.054Z"
    },
    {
      "id": "4f2a9c1e7b3d5a08c6e1d7b2",
      "merchant_id": "3f8a1c27b94e05d6a2c71e90",
      "livemode": false,
      "label": "default",
      "last4": "5a8f",
      "created_by": "9b2e4c71d8a05f3e6c1a7b24",
      "created_at": "2026-10-10T08:57:25.904Z",
      "last_used_at": "2026-10-10T08:58:44.128Z"
    }
  ]
}

Revoke a key

DELETE /merchant/api-keys/{id} · owner or developer

The key stops working at once: its next request gets 401 {"error": "invalid api key"}.

curl -s -X DELETE https://api.payitgo.co/merchant/api-keys/5e1a9c3d7b2f40e8a6c4d2b1 -H "Authorization: Bearer $ACCESS_TOKEN"

200 OK:

{"message": "api key revoked"}

An unknown id answers 404 {"error": "not found"}.

Rotating a key: create the new key, deploy it, check that requests succeed, then revoke the old one.

Dashboard access tokens

The /merchant/… routes are for people. Sign in with email and password to get an access token:

POST /merchant/login

curl -s https://api.payitgo.co/merchant/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@acme.example", "password": "a-long-password"}'

200 OK:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJraW5k…",
  "expires_at": "2026-10-10T09:17:33.92212983Z",
  "role": "owner"
}

The response also sets an httpOnly cookie, refresh_token, on the path /merchant/auth. POST /merchant/auth/refresh exchanges it for a new access token (same response as login) for up to 7 days. POST /merchant/auth/logout ends the session ({"message": "logged out"}), and POST /merchant/auth/logout-all ends every session of yours ({"message": "all sessions revoked"}).

Keep keys secret

• Use secret keys from your server only. Never put them in a browser, a mobile app, a public repository or a support ticket. The checkout routes your customers' browsers call need no key (Checkout).
• If a key may have leaked, revoke it at once. An API key cannot withdraw money (payouts need a signed-in team member with the owner or finance role), but it can create payments and change your webhook URL in your name.
• A lost secret cannot be shown again: create a new key and revoke the lost one.