Quickstart

What crosses the wire

• You send a payment request from your server

  A JSON body carrying the amount, the currency, a reference to the payment method and an idempotency key, authenticated with your sandbox secret key. The API reference names each of those inputs and marks which are optional.

• You get back a payment with a state

  The response reports whether the payment authorized, was declined or needs further authentication, and carries a request id you should log. State, not the HTTP status alone, is what your application branches on.

• The webhook arrives separately

  The lifecycle event is delivered to your endpoint out of band, signed, and possibly after your original response has already returned. Treat the two as independent arrivals rather than a single round trip.

When to use it

• Evaluating RapidCents

  The fastest way to see the request and response shapes against a real environment instead of reading about them.

• Onboarding a new developer

  A repeatable path that ends in a working payment rather than a page of theory, and that surfaces the webhook step early.

• Rehearsing a cutover

  The same four moves are what a production switch repeats with live keys, so running them again before go-live is cheap insurance.

How to implement Quickstart

What fails, and how you find out

• The secret key leaked into the client

  If a secret key appears in a browser bundle or a mobile binary, treat it as compromised and rotate it. Browser card entry uses a publishable key, which cannot move money.

• Signature check fails on a valid event

  Almost always because the body was parsed, re-serialized or trimmed by middleware before verification. Capture the raw bytes first, verify, then parse.

• The payment succeeded but your order did not

  Your response handler and your webhook handler both ran, or neither did. Key the order update on the event id so a duplicate delivery is a no-op rather than a second fulfilment.

Sandbox versus production

• Outcomes are chosen, not risked

  In production the issuer decides. In sandbox the card number decides, so an approval is always an approval and a decline is always the same decline, which is what makes the run repeatable in CI.

• A tunnel is enough

  Sandbox webhooks reach any HTTPS tunnel to localhost. Production needs a routable endpoint with a certificate, so the deployment step is the one thing the quickstart does not rehearse.

• Settlement is compressed

  The funded event that follows a sandbox capture arrives in minutes. On production it follows your funding schedule, so timing assumptions built during the quickstart need rechecking.