Authentication

Your server authenticates with an API key that belongs to one gateway. Keys start with w3g_. Send it as a bearer token:

curl https://api.staging.paywire.xyz/payments/merchants/me \
  -H "Authorization: Bearer w3g_..."

X-Api-Key: w3g_... works too, if your HTTP client makes the Authorization header awkward.

An API key can create payment links and manage your keys and webhook secret. Keep it on your server. Never put it in a web page, a mobile app or a public repository.

What a key can do

Action	Endpoint
Read your gateway	`GET /payments/merchants/me`
Create payment links	`POST /payments/links`
Issue and revoke API keys	`POST /payments/merchants/me/api-keys`, `DELETE /payments/merchants/me/api-keys/{keyId}`
Read and rotate the webhook secret	`GET /notifications/merchants/me/webhook-secret`, `POST /notifications/merchants/me/webhook-secret/rotate`

The payer-side endpoints (reading a link’s checkout, creating an order, reading an order) need no key: anyone with the link or order id can use them, which is what lets the payer pay.

Getting your first key

A Paywire admin creates your gateway in the dashboard; its first key is shown once. After that you can issue more keys yourself with the API.

Rotating a key

A gateway can have up to 5 active keys, so you can rotate without downtime:

Issue a new key

curl -X POST https://api.staging.paywire.xyz/payments/merchants/me/api-keys \
  -H "Authorization: Bearer $OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "production 2026-10" }'

The response holds the new key in apiKey, shown this once, and its keyId.

Deploy it

Switch your servers to the new key and check they work.

Revoke the old key

curl -X DELETE https://api.staging.paywire.xyz/payments/merchants/me/api-keys/$OLD_KEY_ID \
  -H "Authorization: Bearer $NEW_KEY"

The old key stops working at once; anything still using it gets 401.

Find a key’s id with GET /payments/merchants/me: it lists every key with its id, prefix (the first characters, to recognise it) and revokedAt.

Errors

Status	Meaning
`401`	No key, an unknown key, or a revoked key
`403`	The key is valid but can’t do this (for example, managing dashboard users)
`409` `Merchant.TooManyKeys`	Already 5 active keys; revoke one first
`409` `Merchant.Disabled`	The gateway is disabled and can’t take new payments

Get started

Concepts

Integrate

What a key can do

Getting your first key

Rotating a key

Errors

​What a key can do

​Getting your first key

​Rotating a key

​Errors

What a key can do

Getting your first key

Rotating a key

Errors