Create a hosted checkout link
Creates a checkout for the supplied cart and returns the link to the page HighWire hosts for it. The total is computed here: the line items plus shipping and tax, minus the discount. Whoever holds the link can pay, on any device, until expiresAt, so hand it only to the shopper. It is returned once: a replay under the same Idempotency-Key answers without checkoutUrl, and POST /payments/{paymentId}/checkout-session/link issues a new one. Creating the link takes no money and checks none of your limits; the amount counts against them once the payment is captured. The payment settles asynchronously (poll GET /payments/{paymentId}). Answers 400 with code HW_UNSUPPORTED when hosted checkout is not enabled for the account.
Authorization
basic Basic HTTP authentication
In: header
Header Parameters
Optional client-supplied retry key (≤255 chars; UUID v4 recommended). Don't use sensitive data — emails, PANs, or other personal identifiers. Identical requests retried with the same key return the original response. Mismatched bodies return 422; in-flight duplicates return 409. Keys are scoped per merchant + endpoint and expire after 24 hours. On 5xx, retry with the same key: a retry cannot create a duplicate charge. A replay does not return checkoutUrl: the link is shown once.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/payments/checkout-session" \ -H "Content-Type: application/json" \ -d '{ "lineItems": [ { "name": "Test Widget", "amount": 2000, "quantity": 1 } ], "currency": "usd", "successUrl": "https://merchant.example.com/checkout/success", "cancelUrl": "https://merchant.example.com/checkout/cancel", "savePaymentMethodForFutureUse": false }'{ "paymentId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b", "status": "PENDING", "amount": 7200, "currency": "usd", "checkoutUrl": "https://checkout.highwirepayments.com/01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b#hw_hc_…", "expiresAt": "2026-09-30T12:00:00.000Z", "customerId": "string", "paymentMethodId": "string"}{ "statusCode": 400, "message": "Some fields are invalid, please check the errors", "fieldErrors": { "amount": [ "amount must not be less than 1", "amount must be an integer number" ], "cardNumber": [ "cardNumber must be 12-19 digits with no spaces or separators" ] }}{ "statusCode": 401, "error": "Unauthorized", "message": "Invalid credentials"}{ "statusCode": 403, "error": "Forbidden", "message": "Merchant account can only process refunds and voids"}Charge a saved payment method POST
Charges an active saved payment method again, with the customer present — an upsell after the checkout that saved it. The payment method must belong to the supplied customer and authenticated merchant. Every reuse is bounded by the card, whichever of its ids is charged (a checkout that saves a card again may return a new one): accepted for 24 hours after the card was first saved (never extended), at most 2 approved reuses per card (in-progress ones included; a decline does not count) and at most 5 attempts in all, counted together with reuses through the SDK, each for at most the amount of the payment that first saved the card; a reuse outside those bounds answers 409 with a `reason` and charges nothing. The gateway finds the payment that first saved the card itself. Depending on how your account processes payments, the charge either captures immediately (response status CAPTURED) or is accepted and collected asynchronously (response status PENDING — the payment settles to CAPTURED or DECLINED shortly after; follow it with GET /payments/{paymentId}). An issuer that asks for authentication declines the reuse (`Additional authentication required`): this flow has no way to show a challenge.
Retrieve a payment GET
Returns the authenticated merchant's payment with status, amount totals, payment-method details, and transaction and refund history. Payments owned by another merchant are not returned.