Payments troubleshooting
Being rolled out. The interface described here is the one of the next release: it may still change, and may not be enabled on your tenant yet.
What it is for
This page gathers the error responses of the payment API and the situations where a payment, a subscription period or a webhook does not go as expected.
How to read an error
All API errors use the application/problem+json format, for example:
{
"title": "Unprocessable Entity",
"status": 422,
"detail": "invalid cart",
"errors": [ { "field": "lines[0].unit_amount", "message": "must be a decimal string" } ]
}
errors[] points to the faulty field. Always start there.
By response code
| Code | Meaning | To check |
|---|---|---|
400 | unreadable request (invalid JSON), or Idempotency-Key missing on a charge or a refund | the body and the headers |
401 | token missing, expired or unreadable | request a new token (client_credentials) |
403 | the token's application is not declared in your BillingAccount, the account is not ready, the scope is missing, or the mode (one_time, subscription, usage) is not allowed | identity.applications, scopes, billingModes; GET /v1/account |
404 | unknown identifier for your account (another account's data is never visible) | the identifier and its prefix (cart_, cus_, sub_, pay_, chg_, inv_) |
409 | state conflict: cart already paid, subscription already cancelled, payment already refunded, PDF not ready yet, or Idempotency-Key already used with a different body | read the object again; one key per operation |
422 | value rejected: amount, currency, country, return address not allowed, lifetime above carts.maxTTL… | errors[] |
503 | your Stripe or PayPal keys are not usable (yet) | GET /v1/account: the provider's loaded |
Your account is not ready
GET /v1/account returns ready: false, or a provider with loaded: false:
- The secret exists and holds the right keys:
sng secret describe stripe-keys(secretKey,publishableKey) orsng secret describe paypal-keys(clientId,clientSecret). - The
modematches the keys:testwith test keys,livewith production keys. - The keys are not revoked in your Stripe or PayPal dashboard.
- The application in
identity.applicationsexists (sng iam app list).
Your customers cannot pay
| What your customer sees | Cause | Fix |
|---|---|---|
| "link expired" | cart or link past its lifetime | create a new cart or a new link |
| No payment method offered | providers restricted by providers in the cart, or provider not ready | check the cart and GET /v1/account |
| Card declined | declined by the bank or by Stripe | the customer tries another method; details are in your Stripe dashboard |
| Authentication requested at every charge | requirement of their bank | send action_url; offer PayPal |
Periods and charges
| Situation | What happens | To do |
|---|---|---|
| Subscription period declined | subscription.past_due, new attempts per dunning.retryDelays | send the customer a portal link to change payment method |
| Retries exhausted | subscription.unpaid or subscription.canceled depending on dunning.finalAction | contact your customer; create a new subscription if needed |
Pay-as-you-go charge requires_action or failed | charge.action_required or charge.failed, with action_url | send action_url to the customer |
| Fear of a double charge after re-running your job | none if the same Idempotency-Key is reused | one stable key per customer and period |
Webhooks
See the "If it does not work" table of the Webhooks page: invalid signature, clock skew, events received several times.
What is not available yet
These requests are not configuration errors: the feature does not exist yet.
- Payment page on your own domain.
- SEPA direct debit.
- Several currencies in one invoice.
- Transmission of invoices to e-invoicing platforms (PDP).
Contact support
If the problem persists, contact support with: the time of the call, the route, the response
code, the error detail and the identifier concerned (cart_…, pay_…, inv_…). Never send
your Stripe or PayPal keys or your webhook secret.