Introduction
What the High Wire merchant API does, the environments it runs in, how a request looks, and where each guide fits.
The High Wire merchant API is a payments gateway. From your server you authorize, capture, void
and refund card payments, charge saved cards again, create hosted checkout links, and read any
payment back with its full history. Every call is a JSON request over HTTPS, authenticated with
HTTP Basic, under /v1.
This site has two halves. The guides (this section) explain each flow with field tables and
complete examples, and are the place to start. The API reference is generated from the
OpenAPI document and lists every endpoint and schema; the same document is served at
/openapi/gateway-payments.json, and plain-text versions of
these pages at /llms.txt and /llms-full.txt.
Three ways to take a payment
| Surface | Where the card is entered | Guide |
|---|---|---|
| Direct card charges | On your server. You send the card number and charge it in one call, or authorize now and capture later. For environments allowed to handle card data. | Card payments |
| Hosted checkout | On a page High Wire hosts. Your server sends the cart, receives a link, and hands it to the shopper. No card data and no browser code on your side. | Hosted checkout |
| Payment SDK | In your own page, inside secure fields High Wire serves. Your server never sees the card; the browser confirms the payment. | Payment SDK |
All three produce the same payment object, which you read, refund and reconcile through this API. A card saved during a direct charge or an SDK checkout can be charged again with the customer present. Which surfaces your account can use is part of its configuration; High Wire confirms it at onboarding.
Environments
| Environment | API base URL | Hosted checkout host |
|---|---|---|
| Staging | https://api-payments-staging.highwirepayments.com/v1 | checkout-staging.highwirepayments.com |
| Production | https://api-payments.highwirepayments.com/v1 | checkout.highwirepayments.com |
Staging and production are separate systems with separate credentials. Staging processes test cards only; High Wire gives you test card numbers for your account at onboarding. Every example in these guides targets staging.
A request in one minute
curl -X POST https://api-payments-staging.highwirepayments.com/v1/payments/auth-and-capture \
-u "YOUR_API_KEY:YOUR_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0193c2e9-4f9a-7c2f-9c83-1b2b3c4d5e6f" \
-d '{ "amount": 7200, "cardNumber": "5555555555554444", "cardExpiration": "1133", "cardCvv": "456", "cardholderName": "Jordan Example", "cardholderEmail": "jordan@example.com", "cardholderPhone": "+14155550101", "cardholderBillingAddress": "100 Example Street", "cardholderBillingZipcode": "94105", "cardholderBillingCity": "Springfield", "cardholderBillingState": "CA" }'- Authentication: HTTP Basic with your username and secret, server-side only.
- Amounts are integers in cents; the currency is USD.
- Every
POSTanswers201, with the object it created or acted on. Reads answer200. - Ids are UUID v7 strings. Persist the
paymentIdevery call returns. - Idempotency: send an
Idempotency-Keyon every write so a retry can never charge twice. - Errors come in a handful of JSON shapes, told apart by their fields. A declined charge is a
400whose body carriesstatus: "DECLINED"and adeclinedReason.
The details are in Errors and conventions.
Endpoints
| Method and path | What it does | Guide | Reference |
|---|---|---|---|
POST /v1/payments/auth-and-capture | Charge a card now. | Card payments | authAndCapture |
POST /v1/payments/auth | Hold funds on a card for later capture. | Card payments | auth |
POST /v1/payments/{id}/capture | Capture an authorized payment, in full. | Card payments | capture |
POST /v1/payments/{id}/void | Cancel an authorized or in-flight payment. | Card payments | void |
POST /v1/payments/charge-saved-method | Charge a saved card again. | Saved payment methods | chargeSavedMethod |
POST /v1/payments/checkout-session | Create a hosted checkout link. | Hosted checkout | createCheckoutSession |
POST /v1/payments/{id}/checkout-session/link | Reissue a hosted checkout link, revoking the previous one. | Hosted checkout | reissueCheckoutLink |
POST /v1/payments/{id}/refund | Refund a captured payment, in full or in part. | Refunds | refund |
GET /v1/payments/{id} | Read a payment with its history. | Payment lifecycle | getPayment |
Guides
Authentication
Credentials, rotation, and the 401 and 403 responses.
Make your first payment
Charge a test card, read it back, refund it.
Card payments
Authorize and capture, auth then capture or void, 3-D Secure, device data, declines.
Hosted checkout
Create a payment link and confirm the payment before you fulfil.
Saved payment methods
Save a card on a charge and charge it again within its bounds.
Refunds
Full and partial refunds, refund status, disputes.
Payment lifecycle
The payment object, every status, and how to poll.
Account limits
Merchant limits and velocity checks, and what they return.
Idempotency key
Retry writes safely.
Errors and conventions
Every response shape, status code and retry rule.