A payment, in one request.
A canonical REST API over a clean data model — customers, invoices, payments, mandates. Idempotent, versioned, and webhook-driven.
How does the Saldivo API payment flow work?
The Saldivo API creates a verified payment workflow from one payment request. A developer creates or syncs the customer, attaches an invoice reference, sends the amount, currency, payment preference, return URL, and metadata, then listens for signed webhooks as the payment moves through creation, authorisation, settlement, failure, refund, or dispute states. The same payment object stores payer identity, provider reference, invoice metadata, and audit certificate URL, which makes reconciliation deterministic after settlement. Writes are idempotent, API versions are dated, and webhook event ids are stable so integrations can retry safely without duplicating a client collection or losing audit evidence.
Four resources. One canonical shape.
A payer, with a verified Certivus identity attached.
An amount owed, captured from your ledger or the API.
A collection by card or open banking, with its audit trail.
Recurring authority — direct debit and VRP. In build.
Signed webhooks
payment.settled, payment.failed, mandate.signed — verifiable and retried.
Test mode = production
Settle, fail and refund on demand against the same schema, then flip one key to go live.
Idempotent & versioned
Every write takes an idempotency key. The API is dated and never breaks underneath you.
Start with payment creation, then automate the whole lifecycle.
The API keeps the commercial workflow small: create a customer, attach or import an invoice, request payment, and listen for signed events. Each write is idempotent, each object has a stable identifier, and every settlement carries enough metadata to reconcile without scraping provider dashboards.
1. Model the payer
Create or sync a customer record, then attach the Certivus identity reference used by your compliance and audit workflows.
2. Create the payment request
Send invoice id, amount, currency, method preference, return URL and metadata. Saldivo handles the right card or open-banking handoff.
3. Trust webhooks, not polling
Subscribe to signed events such as payment.settled, payment.failed and payment.refunded. Retries are safe because event ids are stable.
4. Reconcile from one record
Use the payment id, invoice id, payer id, provider reference and audit certificate URL to close the ledger entry automatically.
Predictable behaviour for payment software.
Idempotency on every write
Create, retry and recover safely. If your job runner repeats a request after a timeout, Saldivo returns the same object instead of creating a duplicate collection.
Versioned responses
API versions are dated so a deployed integration does not change underneath you. New fields are additive; breaking changes move to a new version.
Signed event delivery
Webhook signatures let your application verify that settlement, failure, refund and mandate events came from Saldivo. Retries use stable event ids so consumers can de-duplicate easily.
Reconciliation metadata
Every payment can carry invoice id, client id, ledger code and provider reference. That makes downstream matching deterministic instead of relying on free-text bank narratives.