Returns a paginated list of payment links for the active business in the current mode.

Creates a payment link and returns its full record, including payPageUrl — the shareable URL you send to the customer. Omit amount to create an open-amount link where the customer enters the amount at checkout.

Partially updates a payment link. Only the fields you send are changed.

Disables a payment link so it can no longer be paid. Returns the updated record with status: DISABLED.

Returns a paginated list of invoices for the active business in the current mode, with optional status, customer, date-range, and sort filters.

Creates an invoice from line items and issues it immediately. SwiftPayIQ does not message the customer for you over this API — there is no WhatsApp/SMS channel. Instead the response returns payPage.url, the hosted checkout page; deliver that link to your customer however you like (your own email/SMS, a redirect, a QR code, etc.). API-created invoices come back with status: SENT, source: API, and deliveryChannel: API.

Partially updates an invoice. Only DRAFT invoices can be edited. Sending items replaces the full line-item list.

Deletes a DRAFT invoice. Issued or paid invoices cannot be deleted — cancel them instead.

Cancels an issued or sent invoice. Returns the updated record with status: CANCELLED.

The second half of the connection handover.

The merchant authorises your platform inside their SwiftPayIQ portal and is redirected back to you carrying a short-lived code. That code grants nothing on its own — your server swaps it here, authenticated with your partner key, and receives the merchant's own API key in return.

The merchant key is returned exactly once. It is stored hashed and can never be retrieved again, so persist it before you respond to the request. Lose it and the merchant has to authorise you again.

Single use, and codes expire five minutes after they are issued.

A code does not always come back

If the merchant connects a business they already had — rather than one created through the setup page you sent them to — the link is recorded as pending review and waits for a SwiftPayIQ admin to approve it. Their consent is real and dated; what is missing is our decision.

In that case no code is issued, and the merchant returns to your redirect address without a ?code= parameter. This is deliberate: an established merchant's business is not handed to a platform on the strength of one button press.

Handle the no-code return. Treat it as "waiting on SwiftPayIQ", not as a failure and not as a finished connection. Send the merchant back through the setup page and you will get partner.link_already_pending_review — the request is already on file.

The other half of the review flow.

When a merchant connects a business they already had, the link waits for a SwiftPayIQ admin. That decision happens out of band, days after the merchant consented, so there is no redirect to carry a code back to you. This is where your server finds out.

Each entry carries a fresh one-time code. Swap it at /partner/connections/exchange exactly as you would one that arrived by redirect.

Codes are minted per call and live five minutes, so call this when you are ready to exchange rather than on a slow timer. An entry disappears once you hold a key for that merchant, so a run that fails halfway is safe to repeat — you will simply be offered the ones you did not finish.

An empty array means nothing is waiting. Poll it a few times a day, or when the PARTNER_CONNECTION_READY notification reaches your SwiftPayIQ inbox.

For a platform whose merchants sign up on your side rather than ours.

Creates an unverified account, a DRAFT business and a pending link, and returns a claim URL to send the merchant.

What it does not do: issue a password, send a one-time code, or earn you anything yet. The merchant opens the claim URL, sets their own password and verifies their own phone — and that verification is the only thing that activates the link and starts commission. You cannot consent on their behalf.

An existing SwiftPayIQ phone number is refused rather than claimed: invite that merchant through the connection flow instead.

For a platform that would rather not build sign-up, one-time codes and document upload itself.

Returns a single-use URL. Open it for the merchant in a new tab; every screen that touches a password or a one-time code stays on our pages, so the merchant's credentials never pass through your servers.

The page reads the merchant's own records each time rather than storing a step number, so somebody who stops halfway through uploading documents and comes back later lands on exactly the same screen.

Register a return address first. Without one this call fails with partner.no_redirect_uri — a journey that ends nowhere is not a finished journey. Ask our team to set it for your account.

When the merchant finishes we send them to that address with ?code=, the same one-time code described on POST /partner/connections/exchange, swapped the same way from your server.

Two ways the journey can end

A business created through this page is yours to connect: the merchant presses connect and comes back to you with ?code=.

A business the merchant already had goes to review instead. They come back with no ?code=, and a SwiftPayIQ admin decides. Build for both endings — the second one is the normal case for any merchant who was already trading with us.

Sent when a payment completes successfully. This is the event most integrations care about — fulfil the order when you receive it (after verifying the signature).

How webhooks are delivered

SwiftPayIQ sends an HTTP POST to the endpoint URL you configured in the dashboard, with a JSON body of the shape:

{ "event": "payment.succeeded", "data": { /* … */ } }

Headers on every delivery:

Your endpoint should respond with any 2xx status as quickly as possible. A non-2xx response (or a timeout — the request is aborted after 10 seconds) is treated as a failure and retried.

Verifying the signature

Every delivery is signed with the signing secret of your webhook (shown when you create or rotate it in the dashboard; it starts with whsec_). Verify it before trusting the payload:

1. Read the X-SwiftPay-Signature header and parse the t (timestamp) and v1 (signature) values.
2. Reject the request if t is more than 5 minutes away from your current time (replay protection).
3. Build the signed string: "{t}.{rawRequestBody}" — use the raw, unparsed request body bytes exactly as received.
4. Compute HMAC-SHA256(signingSecret, signedString) and hex-encode it.
5. Compare it to v1 using a constant-time comparison. If they match, the request is authentic.

// Node.js (Express) example
const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const t = parts.t, v1 = parts.v1;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // 5 min
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));
}

> Capture the raw request body for signature verification — re-serializing parsed JSON will change the bytes and the signature will not match.

Retries

If your endpoint doesn't return 2xx, delivery is retried up to 6 attempts total (5 retries) with increasing back-off: 1 min → 5 min → 30 min → 2 hours → 8 hours (about 10.5 hours end-to-end). A 4xx response other than 408/429 is treated as a permanent failure and is not retried. Make your handler idempotent — the same event may arrive more than once. You can inspect delivery history and re-send from the dashboard.

Sent when a payment attempt fails. Same delivery, signing, and retry rules as payment.succeeded.

Sent when a previously successful payment is refunded. Same delivery, signing, and retry rules as payment.succeeded.

Sent when an invoice is fully paid. Only fired for payments linked to an invoice — data.invoiceId is populated. Same delivery, signing, and retry rules as payment.succeeded.

Sent when a payment link is paid. Only fired for payments linked to a payment link — data.paymentLinkId is populated. Same delivery, signing, and retry rules as payment.succeeded.