Everything you need to know about integrating with the Paayed API, connecting third-party tools, and building custom workflows.
The Paayed API lets you integrate payments directly into your application, website, or platform. It follows RESTful conventions, uses JSON for request and response bodies, and authenticates via API keys.
All API requests are made to https://api.paayed.com/v1/
The API allows up to 100 requests per minute per API key. If you exceed this, you will receive a 429 status code. Implement exponential backoff in your retry logic.
API keys authenticate your requests to the Paayed API. You need separate keys for testing and live transactions.
If a key is compromised, click Regenerate next to the key. The old key is immediately invalidated. Update your application with the new key before regenerating.
All API requests must include your secret key for authentication.
Pass your secret key in the Authorization header using Bearer token format:
Authorization: Bearer sk_live_your_secret_key
A typical authenticated request looks like this:
POST /v1/payments with your Authorization header and a JSON body containing the payment details (amount, currency, source).
The sandbox environment lets you test your integration without processing real payments.
Sandbox mirrors the live API exactly. Same endpoints, same request formats, same response structures. The only difference: no real money moves.
Use any future expiry date and any 3-digit CVV.
When you are ready to go live, replace your sandbox API keys with your live keys. No code changes are needed beyond the key swap.
Create a payment by sending a POST request to the payments endpoint.
POST /v1/payments
A successful request returns a payment object with a unique payment_id, the status (pending, successful, or failed), and a timestamp.
Include an Idempotency-Key header to prevent duplicate charges. If a request with the same key is sent again, the API returns the original response instead of creating a new payment.
Tokenisation lets you collect card details securely without them touching your server.
Card details never pass through your server, which significantly reduces your PCI compliance scope. You only need to complete SAQ A-EP instead of the full SAQ D.
Payment tokens expire after 15 minutes. If the token expires before you use it, ask the customer to re-enter their card details.
Webhooks notify your application in real time when events happen in your Paayed account.
Each webhook includes a X-Paayed-Signature header. Verify this signature using your webhook secret (found in your dashboard) to confirm the request came from Paayed and was not tampered with.
If your endpoint returns a non-2xx status, Paayed retries up to 5 times with exponential backoff over 24 hours.
Issue full or partial refunds on completed payments through the API.
POST /v1/refunds
Create, send, and manage invoices programmatically.
POST /v1/invoices
Include: customer_id, line items (description, quantity, unit price), due date, and currency.
After creating an invoice, send it to the customer:
POST /v1/invoices/{id}/send
The customer receives an email with a link to view and pay the invoice online.
Enable automatic reminders in your invoice settings. Paayed sends reminders at 3 days before, on the due date, and 7 days after the due date.
Store and manage customer records for repeat billing and invoicing.
POST /v1/customers
Include: name, email, and optionally phone and address.
Attach a tokenised card to a customer for future payments:
POST /v1/customers/{id}/payment_methods
This lets you charge the customer later without them re-entering their card details (useful for subscriptions and repeat invoices).
Set up automatic recurring charges through the API.
POST /v1/subscriptions
Include: customer_id, amount, currency, interval (weekly, monthly, quarterly, annually), and start_date.
If a recurring payment fails, the API retries after 3 and 7 days. A subscription.payment_failed webhook is sent for each failed attempt.
Hosted checkout is the fastest way to accept payments without building your own payment form.
The hosted checkout page shows your business name and logo (pulled from your Paayed settings). You can also pass line item descriptions to display on the checkout page.
Because card details are entered on Paayed’s page, your PCI scope is SAQ A (the simplest level).
Create shareable payment links programmatically.
POST /v1/payment_links
Include: amount, currency, description, and optional expiry_date.
Returns a payment link object with a unique url that you can share with customers via email, SMS, or messaging apps.
When the customer clicks the link, they see a Paayed-hosted payment page with the amount and description. After paying, they see a confirmation screen.
Each payment link has a unique ID. When a payment is made through the link, the resulting transaction references the link ID, making it easy to track which link generated which payment.
Connect Paayed to Xero to sync invoices, payments, and settlements automatically.
Data syncs every 15 minutes. You can also trigger a manual sync from the integrations page.
Connect Paayed to QuickBooks Online to keep your accounting records in sync.
With the integration active, bank reconciliation in QuickBooks is simplified. Each Paayed settlement matches a single bank deposit with all constituent transactions and fees pre-categorised.
Accept Paayed payments on your WooCommerce store with the official plugin.
Configure the payment form title, description, and whether to capture payments immediately or authorise only.
Use Paayed as a payment provider on your Shopify store.
Customers see Paayed as a payment option at checkout. Card details are collected via Paayed’s secure tokenisation, keeping your store PCI compliant.
Successful payments update Shopify order status automatically. Refunds initiated in Shopify are processed through Paayed and reflected in your Paayed dashboard.
Common API error codes and how to resolve them.
The Paayed API uses versioning to ensure backward compatibility.
The current API version is v1. All endpoints are prefixed with /v1/.
Breaking changes are introduced in new major versions only. Non-breaking changes (new fields, new endpoints) are added to the current version without notice.
When a new version is released, the previous version is supported for at least 12 months. Deprecation notices are sent via email and displayed in the dashboard.
API changes are documented in the Changelog section of the API documentation at docs.paayed.com. Subscribe to the changelog RSS feed to receive updates automatically.
