Make your first payment

Charge a test card on staging, read the payment back, and refund it, in three calls.

You need staging credentials (see Authentication) and a test card number. Staging processes test cards only; High Wire gives you the numbers for your account at onboarding. The examples use a common test number. Use test cards only, and never paste real card data into a shell, a log or a ticket.

1. Charge the card

The simplest flow is auth-and-capture: authorize and capture the funds in one call. Send an Idempotency-Key so a retry can never charge twice.

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"
  }'

201 Created:

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

Store paymentId. status: "CAPTURED" means the money moved. A 400 with status: "DECLINED" and a declinedReason is a decline; a 400 with fieldErrors is a validation error. Both are explained in Errors and conventions.

2. Read the payment back

curl https://api-payments-staging.highwirepayments.com/v1/payments/01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b \
  -u "YOUR_API_KEY:YOUR_SECRET"

200 OK (abridged):

{
  "id": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b",
  "object": "payment",
  "status": "CAPTURED",
  "currency": "usd",
  "amount": 7200,
  "paymentMethodType": "CARD",
  "paymentMethodDetails": { "brand": "mastercard", "bin": "555555", "last4": "4444", "expirationMonth": 11, "expirationYear": 2033 },
  "transactions": [
    { "id": "0192a6b3-2c1d-7e4f-8a9b-3c4d5e6f7a8b", "object": "transaction", "type": "AUTH_AND_CAPTURE", "status": "SUCCEEDED", "amount": 7200, "createdAt": "2026-10-19T14:05:00.000Z", "updatedAt": "2026-10-19T14:05:01.000Z" }
  ],
  "amounts": { "requested": 7200, "authorized": 7200, "captured": 7200, "voided": null, "refunded": null },
  "createdAt": "2026-10-19T14:05:00.000Z",
  "authorizedAt": "2026-10-19T14:05:01.000Z",
  "capturedAt": "2026-10-19T14:05:01.000Z",
  "voidedAt": null,
  "updatedAt": "2026-10-19T14:05:01.000Z"
}

This read is the source of truth for a payment's state. See Payment lifecycle for every field and status.

3. Refund it

curl -X POST https://api-payments-staging.highwirepayments.com/v1/payments/01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b/refund \
  -u "YOUR_API_KEY:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0193c30a-1f2e-7b6c-8d9a-0e1f2a3b4c5d" \
  -d '{ "amount": 500, "reason": "customer request" }'

201 Created:

{
  "refundId": "01928e55-3c4d-7c8e-8b1a-fedcba987654",
  "paymentId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b",
  "status": "SUCCEEDED",
  "amount": 500,
  "remainingRefundableAmount": 6700,
  "cardNumber": "555555xxxxxxxx4444"
}

Omit amount to refund the remaining balance in full. Reading the payment again now shows status: "PARTIALLY_REFUNDED" and the refund at the top of transactions.

Where to go next

Hold funds first and settle later, handle 3-D Secure, or send browser signals with the charge: Card payments.
Take payments without touching card data: Hosted checkout.
Charge a saved card again right after the purchase: Saved payment methods.
Make every write safe to retry: Idempotency key.

1. Charge the card

2. Read the payment back

3. Refund it

Where to go next

On this page