Card payments API

Coming soon

The endpoints on this page are not available in production yet. They are listed at summary level so that you can plan an integration; routes, fields and permissions may change before they are released. Once they are released, they will be documented in full in the API reference.

Today, card payments are made through the Accounting endpoints — see Accounting.

These endpoints take card payments from a company's customers through the company's payment provider — Cardknox or Stripe — and record them in Accounting. All routes are relative to https://api.rushhourapp.com/api/v1 and use the usual response envelope.

Before you start

• Card numbers never go to the RushHour API. Collect cards with the payment provider's own secure fields — Cardknox's iFields or Stripe's Payment Element — and send RushHour the token or payment method the provider gives you. GET Payments/Gateway tells you which provider the company uses and the public key to load its fields with.
• Send an idempotency key with every payment. Each charge and each refund carries an idempotencyKey you generate — a new GUID per attempt works; a key is 8 to 64 letters, digits, - or _. If a request times out, send it again with the same key: RushHour returns the payment it already made instead of charging the card twice. A key reused for a different customer or amount is refused with payments.idempotency_key_reused.
• A decline is an answer, not an error. A declined card returns 200 with success: false, the error payments.card_declined with the provider's reason, and the payment in data. When the provider didn't answer, the error is payments.outcome_unknown: don't start a new payment — send the same request with the same key again, or call POST Payments/{id}/Sync, until the payment settles.
• Amounts are in currency units, for example 125.50, not in cents. currencyCode is a three-letter ISO code; leave it out to use the company's currency.
• Some actions need a person. Capturing, voiding and refunding a payment, creating and sending payment requests, and changing payment settings, are refused for API tokens with 403 Forbidden and the code auth.interactive_session_required.

Card payments

Method and route	What it does	Permission
GET Payments/Gateway	Which provider the company takes payments through, what it can do (charge, authorize, save cards, refunds, partial capture), and the public keys for the provider's card fields.	Signed in
POST Payments/Charge	Charges or authorizes a card for a customer. The card is a saved card, a Cardknox token, or a Stripe payment method. Optionally applies the payment to invoices, links it to an order, and saves the card.	Charge customer cards
POST Payments/Stripe/PaymentIntent	Starts a Stripe payment and returns the client secret to confirm it with Stripe's Payment Element.	Charge customer cards
POST Payments/{id}/Sync	Reads the payment's current state from the provider, for example after the customer finished a bank security check, and records it in Accounting the first time it succeeds. Safe to repeat.	View Invoices and Payments
POST Payments/Stripe/SetupIntent	Starts saving a card with Stripe without charging it.	Charge customer cards
POST Payments/SavedMethods	Saves a card on a customer, from a Cardknox token or a completed Stripe setup.	Edit customers, or Charge customer cards
POST Payments/{id}/Capture	Captures an authorized payment, in full or for a smaller amount.	Charge customer cards
POST Payments/{id}/Void	Releases an authorization, or cancels a payment that hasn't settled.	Refund and void payments
POST Payments/{id}/Refund	Refunds all or part of a captured payment. Takes amount, an optional reason and an idempotencyKey.	Refund and void payments
GET Payments/{id}	One payment.	View Invoices and Payments
GET Payments	A page of payments, filtered by from, to, customerId, status, gateway, invoiceId or orderId. Use page and pageSize (25 by default, at most 200).	View Invoices and Payments

The charge request

POST Payments/Charge takes:

Field	Meaning
idempotencyKey	A new GUID for this attempt.
customerId	The customer who pays.
amount, currencyCode	How much to charge or authorize.
intent	Charge to take the money now, or Authorize to hold it for a later capture.
description	Optional text for the payment.
invoiceIds	Optional list of { invoiceId, amount } the payment is applied to. Without it, a payment for an order is applied to the order's invoice, and otherwise recorded as credit on the customer's balance.
orderId, paymentRequestId	Optional links to an order or a payment request.
saveCard, setAsDefault	Save a new card on the customer, and make it their default card.
source	The card: { "kind": "SavedMethod", "customerPaymentMethodId": … }, { "kind": "CardknoxToken", "cardToken": …, "cvvToken": …, "cardExpiry": "MMYY", "cardholderName": …, "billingZip": …, "billingStreet": … } or { "kind": "StripePaymentMethod", "paymentMethodId": "pm_…" }.

The response is the payment: its status, the amounts charged, captured and refunded, the card's brand and last four digits, the provider's reference, the linked invoice, order, Accounting payment and payment request numbers, its refunds, and canCapture, canVoid, canRefund and amountRefundable. When Stripe needs the customer to complete a bank security check, the response also carries requiresAction: true and a clientSecret to finish it with Stripe.js; then call POST Payments/{id}/Sync.

Payment statuses

Pending, RequiresAction, Authorized, Captured, PartiallyRefunded, Refunded, Voided, Failed, Expired and Canceled.

A refund does not change the payment recorded in Accounting; see Refunds.

POST Accounting/Payment with a saved card will also accept an optional idempotencyKey in the same format. With a key, sending the same payment again never charges the card a second time; without one, it works exactly as today.

Payment requests

A payment request is a secure page you send a customer so they pay, authorize or save a card themselves — see Payment requests.

Method and route	What it does	Permission
GET PaymentRequests/Availability	Whether the company can create and send payment requests, and through which provider.	View Invoices and Payments
GET PaymentRequests	A page of requests, newest first, filtered by customerId, invoiceId, orderId, status or search.	View Invoices and Payments
GET PaymentRequests/{id}	One request, with the link to its page.	View Invoices and Payments
POST PaymentRequests	Creates a request for a customer, an invoice, an order or a quote. Takes the targetType (Customer, Invoice, Order or Quote), the customerId and the invoice or order, the intent (Charge, Authorize or SaveCard), an optional amount (the invoice balance or the order's or quote's price by default), description, expiresInDays (1 to 90, 30 by default), whether the customer may use or save a card, and optionally sendEmail with an email address.	Manage payment requests
POST PaymentRequests/{id}/Send	Emails the request again, optionally to a different email address, while it can still be paid.	Manage payment requests
POST PaymentRequests/{id}/Revoke	Stops the request at once. A request that is paid, authorized or used to save a card can't be revoked (paymentrequests.already_paid), nor one with a payment in progress (paymentrequests.payment_in_progress).	Manage payment requests

Request statuses are Open, Opened, Authorized, Paid, CardSaved, Expired, Revoked and Failed. A request that passed its expiry date reads Expired. Its link is returned only inside url. When sendEmail is set and the email fails, the request is still created, with a warning in otherMessages.

The page your customer opens uses its own public endpoints under PaymentRequests/Public/. They work only with the request's link, are rate-limited, and are not meant for integrations.

Stripe setup

These endpoints are used by Settings → Integrations to set up Stripe for a company — see Stripe customer payments. They need the Company Admin role, and every change needs a person signed in.

Method and route	What it does
GET Integrations/Stripe/Status	Whether Stripe is available, which ways of using it the company may choose, the chosen one, and the connected account's state: whether it can take charges and receive payouts, and what Stripe still needs.
POST Integrations/Stripe/Connect/AccountLink	Returns a single-use link to Stripe's onboarding for the company's connected account. The link expires after a few minutes.
POST Integrations/Stripe/Connect/Sync	Reads the connected account's state from Stripe again.
PUT Integrations/Stripe/Settings	Saves how the company uses Stripe, its own keys when it uses them, the statement descriptor suffix, and phone and mail orders. Secret keys are never returned.
POST Integrations/Stripe/TestConnection	Checks the account or keys with Stripe without saving anything, and returns the account name and whether it is in live mode and can take charges.
POST Integrations/Stripe/Disconnect	Stops new Stripe payments for the company. Payment history is kept.

POST Integrations/TestConnection with type set to Cardknox checks Cardknox keys the same way: the typed key, or the saved one. The key is never returned.

Errors

Payment errors use the usual errors list, with codes that start with payments., paymentrequests. or stripepayments. — for example payments.no_gateway_configured when the company has no payment provider set up. A declined card is reported as payments.card_declined, with the provider's reason in the message. payments.recording_failed means the card was charged but the payment isn't recorded in Accounting yet; a sync records it, without charging again.

RushHour receives the payment providers' own notifications to keep payments up to date. It does not send webhooks to your systems — see Webhooks.