Card payments

The direct API takes card details from your server and charges them. Use it only when your environment is validated to handle card data. Otherwise collect the card in the browser with the Payment SDK, or hand the shopper a hosted checkout link and never touch the card at all.

Both charge routes take the same request body and answer the same shape. Money that was captured is returned with a refund; an authorization that was not captured is released with a void.

Availability. Not every account can use the direct card routes; High Wire confirms at onboarding which surfaces yours supports. A route your account cannot use answers a charge decline that says so, see Declines.

Request body

Shared by auth-and-capture and auth.

The string fields are checked for presence only, except where a rule is listed. Unknown fields are dropped silently. A failed rule answers a validation error naming the field.

Device data

deviceData carries signals about the cardholder's browser for your payment processor, where they improve authorization rates and reduce 3-D Secure friction.

{
  "deviceData": {
    "device": {
      "ip": "203.0.113.42",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) …",
      "location": { "lat": 37.7749, "lon": -122.4194 }
    }
  }
}

• Collect the values in the browser with the Payment SDK's device-screening collector. Any extra keys it adds are dropped by the gateway. An embedded Payment SDK checkout sends no deviceData: HighWire reads the browser's address and location itself.
• Omit deviceData entirely when you have nothing to send. Never send an empty object or a hand-built substitute.

Authorize and capture

POST /v1/payments/auth-and-capture

Idempotency-Key: honoured.

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",
    "riskSessionKey": "01928e1c-2a4d-7c8e-8b1a-1234567890ab"
  }'

201 Created:

{
  "paymentId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b",
  "status": "CAPTURED",
  "amount": 7200,
  "cardNumber": "555555xxxxxxxx4444",
  "cardExpiration": "1133",
  "cardholderName": "Jordan Example"
}

Authorize now, capture later

POST /v1/payments/auth

Idempotency-Key: honoured. Same request body and the same responses as above; a success settles to AUTHORIZED instead of CAPTURED:

{
  "paymentId": "01929a10-5d2e-7f3b-8c4d-1e2f3a4b5c6d",
  "status": "AUTHORIZED",
  "amount": 7200,
  "cardNumber": "555555xxxxxxxx4444",
  "cardExpiration": "1133",
  "cardholderName": "Jordan Example"
}

The funds are held on the card. Capture them to settle, or void to release them. An authorization that is neither captured nor voided eventually lapses at the processor and the payment becomes EXPIRED; how long a hold lasts is decided by the card networks, so capture as soon as you can.

Capture

POST /v1/payments/{id}/capture

Idempotency-Key: honoured. No request body. Captures the full authorized amount; partial captures are not supported.

curl -X POST https://api-payments-staging.highwirepayments.com/v1/payments/01929a10-5d2e-7f3b-8c4d-1e2f3a4b5c6d/capture \
  -u "YOUR_API_KEY:YOUR_SECRET" \
  -H "Idempotency-Key: 0193c2f1-2b7d-7a4e-8f10-6c7d8e9f0a1b"

201 Created:

{
  "paymentId": "01929a10-5d2e-7f3b-8c4d-1e2f3a4b5c6d",
  "status": "CAPTURED",
  "amount": 7200,
  "cardNumber": "555555xxxxxxxx4444"
}

Void

POST /v1/payments/{id}/void

Idempotency-Key: ignored. No request body. Cancels, for its full amount, a payment that has not been captured: an uncaptured AUTHORIZED hold, a charge still PENDING at the processor, or a REQUIRES_ACTION payment whose customer abandoned the 3-D Secure challenge. A captured payment cannot be voided; refund it instead. Accounts limited to refunds and voids may call this route.

curl -X POST https://api-payments-staging.highwirepayments.com/v1/payments/01929a10-5d2e-7f3b-8c4d-1e2f3a4b5c6d/void \
  -u "YOUR_API_KEY:YOUR_SECRET"

201 Created:

{
  "paymentId": "01929a10-5d2e-7f3b-8c4d-1e2f3a4b5c6d",
  "status": "VOIDED",
  "amount": 7200,
  "cardNumber": "555555xxxxxxxx4444"
}

cardNumber is null for payments that carry no card number, such as wallet payments made through a checkout.

3-D Secure

3-D Secure surfacing is enabled per account by High Wire, together with your 3-D Secure return page (an HTTPS page on your site the customer lands on after the challenge). Until it is enabled, a charge whose issuer demands a challenge is declined with declinedReason: "Additional authentication required". Enable it once your integration renders nextAction and polls for the outcome.

When it is enabled and the issuer requires the customer to authenticate, the charge still answers 201, with status: "REQUIRES_ACTION" and a nextAction instead of a settled outcome. Nothing has been charged yet; the payment waits for the customer.

{
  "paymentId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b",
  "status": "REQUIRES_ACTION",
  "amount": 7200,
  "cardNumber": "555555xxxxxxxx4444",
  "cardExpiration": "1133",
  "cardholderName": "Jordan Example",
  "nextAction": {
    "kind": "REDIRECT",
    "url": "https://verify.example.com/3ds/s/7Qx2LwP7aZ0cT5uYbR1d",
    "method": "GET"
  }
}

Integration flow:

1. Render the challenge, typically an iframe whose src is nextAction.url.
2. The customer completes or fails it. The frame is then sent to your configured return page with a few query parameters describing the outcome. Treat them as a hint for your UI only, never as the settled outcome: anyone can open that page.
3. Poll GET /v1/payments/{id}. It keeps serving the pending nextAction until the payment settles to CAPTURED or AUTHORIZED on success, DECLINED when authentication fails (the transaction's declinedReason is Authentication failed), or EXPIRED when the challenge times out unanswered.

Notes:

• A replay under the same Idempotency-Key returns the same response, including the same challenge URL.
• An abandoned challenge can be cancelled with void, which settles the payment to VOIDED.
• When savePaymentMethodForFutureUse was true, the response carries customerId and paymentMethodId, but the method is a pending save: it becomes chargeable only once the payment settles successfully, and it is invalidated if the authentication fails, expires or is voided. See Saved payment methods.
• charge-saved-method never returns REQUIRES_ACTION; an issuer that insists on a challenge there declines the charge.

Declines

A decline is a 400 with the charge decline body. The payment is stored with status: DECLINED for your reporting. The response is stored under the Idempotency-Key, so a new attempt is a new operation with a new key.

A charge the processor accepted is never answered with a decline: it answers 201 with status: "PENDING" and settles shortly after. Do not retry a PENDING payment; poll it.