Authentication
HTTP Basic credentials for the merchant API, how they are issued, scoped and rotated, and the exact 401 and 403 responses.
Every request to the merchant API carries your account's credentials with HTTP Basic authentication:
Authorization: Basic base64(<username>:<secret>)curl -u does the encoding for you:
curl https://api-payments-staging.highwirepayments.com/v1/payments/01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b \
-u "YOUR_API_KEY:YOUR_SECRET"Credentials
- High Wire issues a username and a secret for your account, per environment, when you onboard. There is no self-service or programmatic registration; request access to get started.
- The secret is shown once, when it is created or rotated, and cannot be retrieved later. Store it in your secrets manager.
- To rotate the secret, ask your High Wire contact. The previous secret stops working the moment the new one is issued.
- Credentials are environment-scoped: staging credentials work only against the staging host, production credentials only against production. See Environments.
- Server-side only. Never ship these credentials in browser or mobile code. The browser
surfaces of High Wire (the Payment SDK and the hosted checkout page)
identify your account with a publishable key (
hw_pk_test_…orhw_pk_live_…) and per-session tokens instead; Basic credentials are refused there, and publishable keys are refused on this API. See Payment SDK authentication.
Request rules
- Send the header on every request. The API does not send a
WWW-Authenticatechallenge on401, so a challenge-response client, or a browser prompt, will not work.
Account states
| State | What the API allows |
|---|---|
| Active | Everything. |
| Refund-only | Only POST /v1/payments/{id}/void, POST /v1/payments/{id}/refund and GET /v1/payments/{id}. Every other route answers 403. |
| Not active | Nothing: every call answers 401 Invalid credentials, exactly like a wrong secret, so an inactive account cannot be used to confirm a leaked secret. |
A state change is made by High Wire, not through the API. If you unexpectedly receive 401 with
credentials you know are right, or 403, contact your High Wire contact.
Error responses
These answers are never stored under an Idempotency-Key and never create a payment. They use the
plain error shape.
| Status | message | When |
|---|---|---|
401 | Missing Authorization header, Invalid Authorization header format, Invalid basic auth credentials format, Invalid basic auth credentials, Invalid credentials | The header is missing or malformed, the credentials are not valid, or the account is not active. An unknown username, a wrong secret and an inactive account are deliberately indistinguishable. |
403 | Merchant account can only process refunds and voids | A refund-only account called a route other than void, refund or retrieve. |
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Invalid credentials"
}{
"statusCode": 403,
"error": "Forbidden",
"message": "Merchant account can only process refunds and voids"
}If a secret leaks, ask High Wire to rotate it immediately; the leaked one stops working at once.