DEVELOPER PLATFORM
Errors
RapidCents API errors return a typed code, a human-readable message and, where relevant, a retry hint. Three categories behave differently: a malformed or unauthorized request, which no retry fixes; a platform failure, which a retry with the same idempotency key usually does fix; and an issuer decline, which splits into soft and hard. A soft decline may succeed later; a hard decline never will. Branch on the code rather than the message text, since wording is not part of the contract.
- Sandbox with documented test cards
- Signed webhooks
- Typed errors and idempotent retries
- Dedicated developer support
What crosses the wire
Where it sits
On the response to any call, and on the event that reports a later failure. The same code vocabulary is used in both places, so a decline caught synchronously and a renewal that failed overnight are handled by one mapping.
What comes back
An HTTP status that classifies the failure broadly, and inside the body a typed code, a message written for a human reader, and a request id. The reference enumerates the codes; the message text is not part of the contract.
What you do with it
Map each code to an action once, in one place: fail the request, retry it, ask the customer for a different method, or escalate. Applications that branch on message strings break the first time wording is improved.
When to use it
Handling declines
Branch on the code, not the message string, which is written for humans and may change without notice.
Recovering recurring charges
Soft declines feed the retry schedule; hard declines should stop the schedule and prompt the customer for a new card instead of burning attempts.
Deciding what to show a customer
Some codes carry information the cardholder can act on, and some carry information the issuer expects you not to disclose. The mapping decides which message the checkout renders.
How to implement Errors
Map every documented code to an action in your own system, and default unknown codes to a safe failure.
Retry only soft and platform failures, on a backoff, with the same idempotency key.
Cap the number of attempts per payment method rather than per request.
Surface actionable messages to customers, not raw processor text.
Log the code and the request id together so support can trace a specific attempt.
What fails, and how you find out
Retrying a hard decline
It cannot succeed, and repeated attempts on a closed or blocked account are visible to the issuer. The recovery path is a new payment method, not another attempt.
Retrying without the idempotency key
A retry that omits the key is a new request. If the first attempt actually landed, the customer is charged twice and the duplicate is discovered at reconciliation rather than at the till.
Showing the raw message to the customer
Processor wording is written for an operator, not a cardholder. Rendering it produces a checkout that tells people to contact a bank they do not bank with.
Unknown codes falling through
A code you have not mapped should fail closed and alert, not fall into the retry branch by default. New codes appear as the platform changes, and the changelog is where they are announced.
Sandbox versus production
You choose the error
Production declines depend on the issuer and cannot be summoned on demand. In sandbox a documented test card produces a specific code every time, which is the only way to write a test that asserts on one.
Platform failures are simulated too
Timeouts and retryable failures can be provoked deliberately, so the idempotency path gets exercised rather than assumed. That path is the one nobody tests until it costs a duplicate charge.
The vocabulary is identical
Sandbox does not use a reduced or friendlier code set. A mapping built against sandbox codes is the mapping production needs, which is what makes the exercise worth doing before go-live.
Questions about Errors
What is the difference between a soft and hard decline?
A soft decline is temporary, such as insufficient funds or a velocity limit, and may clear on a later retry. A hard decline, such as a closed account, is permanent and must not be retried.
Should I retry a declined card immediately?
No. Immediate retries are treated as suspicious by issuers. Space attempts out and cap them, which is what the recurring engine does automatically.
How do I trace a single failed request?
Every response carries a request id. Log it alongside the error code and support can locate the exact attempt.
Is an HTTP 200 always a successful payment?
No. A 200 means the call was accepted and processed; whether the payment authorized is reported by the state in the body. Treating the status code as the outcome is how declined orders get fulfilled.
What should I retry, and how many times?
Retry platform failures and soft declines, on a backoff, with the same idempotency key, and cap attempts per payment method rather than per request. A hard decline gets zero retries at any interval.
How do I tell a duplicate charge from two legitimate ones?
By the idempotency key. Two charges created under the same key are one payment reported twice; two charges under different keys are two payments, and the request ids in your logs say which happened.
Why did a payment that succeeded still fail later?
Authorization and settlement are separate. A payment can authorize and then fail to settle, or settle and then be disputed. Those arrive as events with their own codes, which is why the same mapping has to cover asynchronous failures.
What should I do with an error code I have never seen before?
Fail closed and alert. An unmapped code must not fall into the retry branch by default. New codes appear as the platform changes and are announced in the changelog, so an unknown code is a signal to go and read it rather than something to swallow.
How much of a decline reason can I show the customer?
Only what your mapping allows. Some codes carry information a cardholder can act on and some carry information the issuer expects not to be disclosed. Rendering raw processor text produces a checkout that tells people to call a bank they do not bank with.
Continue the integration
The RapidCents API reference on a workstation, with a sample request, the matching response, and a test terminal. API Reference
REST endpoints for payments, customers, refunds, webhooks and settlements with request and…
Explore
A RapidCents webhook delivery timeline next to the payment that triggered it, with a test terminal on the desk. Webhooks
Signed webhook events for payment lifecycle with idempotent processing guidance.
Explore
RapidCents sandbox testing: documented test cards, a simulated decline, and a terminal for the in-person cases. Testing
Test card numbers, simulated declines and sandbox settlement events.
ExploreA RapidCents subscription charge created over the API, using the same billing engine as the dashboard. Recurring Payments API
Build subscriptions, installments and retry logic against the same billing engine used by the…
Explore
Take the next step
Talk to a RapidCents specialist
RapidCents Fee Check reads a processing statement and shows interchange separately from the markup. Upload a statement for an instant breakdown, or open a merchant account and start accepting payments on one account.
- No obligation
- Payment specialists, not a call centre
- Secure statement upload
