Pending, processing, successful, failed: building around payment statuses

Developer resources7 min readPayve

Every Payve payment reports one of four statuses. How to model them in your own system, when to trust a webhook, and how to test each outcome in the sandbox.

A payments integration is mostly a state machine. Your system creates a payment, the payment moves through a few states, and your product reacts — releasing an order, notifying a user, closing an invoice. Get the states right and the rest of the integration is straightforward. Get them wrong and you ship goods for money that never arrived, or tell a customer a payout failed when it landed.

Payve keeps the states your system has to handle small on purpose. Every payout, pay-in and conversion reports exactly one of four statuses. This guide covers what each one means, how to keep your own records in step, and how to rehearse every outcome before you go live.

The four statuses

  • pending — the request is accepted and queued. For a payout, the amount has already been taken from your balance, but nothing has been sent yet.
  • processing — the payment has been sent to a payment channel and Payve is waiting for the outcome.
  • successful — the money reached the recipient, or, for a pay-in, your wallet was credited.
  • failed — the channel rejected the payment or it timed out, or it was reversed after an earlier success.

The full definitions live in the payouts reference. Two of them deserve a closer look.

processing is not a result

The most common integration bug is treating processing as good enough. It is not. Processing means the money is in a channel’s hands and the answer has not come back. Do not release goods, credit a customer or mark an invoice paid until you see successful. Show the person waiting a calm, accurate message instead: the payment is on its way.

failed can follow successful

Occasionally a receiving bank accepts a payment and then returns it. When that happens the payout moves from successful to failed and your wallet is credited back. Your system must allow that transition. If your model treats successful as final and refuses any later change, your records will disagree with your balance. The webhooks reference lists the reversal event alongside the others.

Keep your records in step

Payve tells your system about status changes in two ways: signed webhooks pushed to your endpoint, and the API, which you can ask at any time. Use both.

  • Store the payment’s id and your own reference the moment you create it, before you send the request, so a crash mid-request leaves a record you can look up.
  • Verify the signature on every webhook against the raw body before you parse it. The webhooks reference shows exactly what is signed.
  • Record each event id you process and treat a repeat as a no-op. Webhooks can arrive more than once.
  • Before an irreversible action — shipping goods, paying a seller onward — fetch the payment from the API and act on the status it returns, not only on the event body.
  • Accept events out of order. Apply a status change only if it moves the payment forward, or from successful to failed.
  • Run a periodic job that fetches payments still pending or processing on your side. A missed webhook should never be the only record of what happened.

Retries and statuses work together

A request that times out leaves you not knowing whether the payment was created. Send every money-moving request with an Idempotency-Key and reuse the same key when you retry it; you get the original result back instead of a second payment. Our earlier article on idempotency keys and the idempotency reference cover the details. Once you have the payment back, its status tells you what to do next.

Rehearse every outcome in the sandbox

Each status should be exercised before you go live, including the uncomfortable ones. The sandbox uses test keys, moves no real money, and lets you choose outcomes on purpose: specific beneficiary account numbers make a payout fail or reverse, and the simulator in the dashboard lets you pay into a test virtual account or approve a pending mobile-money charge. The test credentials page lists them.

  • A payout that succeeds — your system should move it to paid and notify the right people.
  • A payout the channel rejects — your system should show the failure and leave the order or invoice open.
  • A payout that succeeds and is later reversed — your records should follow it to failed and match your balance.
  • A pay-in that arrives — your system should release whatever it was waiting for exactly once.
  • The same webhook delivered twice — nothing should happen the second time.

A short checklist

  • Model the four statuses and the successful-to-failed transition explicitly.
  • Treat only successful as done.
  • Verify webhook signatures, deduplicate on event id, confirm through the API before irreversible actions.
  • Send an Idempotency-Key on every money-moving request and reuse it on retry.
  • Sweep anything still open on your side on a schedule.
  • Test every outcome in the sandbox before switching to live keys.

Ready to start? Get sandbox keys from the developers page, then follow the API reference.