How it works

When your customer completes the iwocaPay checkout, you receive the money instantly and the order can be reconciled automatically with your back end.

The iwocaPay ecommerce API is a JSON REST API. You must use HTTPS for all interactions with our API.

When you’re ready to build, follow the Step by step guide.

How the integration works

The journey begins with a trade customer on your ecommerce site.

1. Your customer chooses Check out with iwocaPay, at which point you create an order using the API. See Creating an order for more information.
2. The request returns an order object, containing an order_url field.
3. Redirect your customer to the URL in order_url to complete their checkout with us.
4. The customer goes through our journey and completes the payment process, all via our self-hosted checkout.
5. We redirect the customer back to your site, to a predefined redirect_url.

You can use the API to query the status of an order at any time. See Retrieving an order for more information.

Orders

Each checkout is associated with an order. The order is the source of truth for a transaction, and any change (such as a price adjustment) requires a new order to be created.

Order lifecycle

When you create an order via the API, it moves through a series of statuses as the customer progresses through checkout. Understanding this lifecycle is important for designing your integration, particularly how your system should respond to each status change, and what happens when things don’t go to plan.

Status	What it means	What triggers it
CREATED	Order exists but the customer hasn’t started to enter their details on the iwocaPay hosted checkout	You sent a create order request
PENDING	Customer has started the iwocaPay checkout (entered their details)	Customer starts sign up for Pay Later or Pay Now
APPROVED	Customer has been approved for Pay Later with sufficient funding	Credit decision made, credit limit created
SUCCESSFUL	Payment complete: you will receive the funds	Customer accepts terms (Pay Later) or payment executes (Pay Now)
UNSUCCESSFUL	Order will not be completed	Customer declined, order cancelled, or payment failed

Considerations

Checkout timing

How long the checkout takes depends on whether the customer has already been credit-assessed by iwocaPay. If they have been credit assessed, and subsequently approved, they will have a ‘spending limit’, which is their credit limit for making purchases with iwocaPay.

New customers (no existing Spending Limit): The customer needs to enter their personal and business details, go through a credit assessment, and complete security checks — all within the iwocaPay checkout. Most customers complete this in under 30 minutes, but in some cases we need to run manual checks, which can take around an hour. This is an important consideration if your checkout has a time limit, your prices change frequently, or your quotes expire. If this applies to your business, we strongly recommend sharing your Spending Limit Link with customers before they reach checkout (see below).

New customers (Spending Limit Link completed beforehand): If a customer has already completed their credit assessment via your Spending Limit Link, all of those checks are done before they reach your checkout. They simply log in, select their payment terms, and confirm — checkout takes a few minutes. This is the fastest path for new customers and eliminates the risk of them abandoning the checkout process.

Returning customers: Customers who have already checked out with iwocaPay and have an existing Spending Limit don’t need to go through any checks again. Checkout takes a few minutes.

What is the Spending Limit Link?

Your Spending Limit Link lets customers get credit-assessed independently, outside of any specific order. They complete the application, see how much they’re eligible to spend with iwocaPay, and are then ready to check out instantly whenever they place an order with you. Every seller has a Spending Limit Link available in the iwocaPay Dashboard. You can share it on your website, in emails, on invoices, or in marketing materials — it doesn’t require any API integration. See Concepts for further details on how it works.

Getting paid

iwocaPay pays you when the order reaches SUCCESSFUL status. The customer has completed checkout and accepted their terms. The funds are sent to your bank account, net of any applicable fee. You don’t need to wait for the customer to repay iwocaPay.

Unsuccessful orders

An order reaches UNSUCCESSFUL status for several reasons: the customer was declined, the customer abandoned checkout, you cancelled the order via the API, or the payment failed. The status alone doesn’t distinguish between these.

Cancelling an order: You can cancel an order by making a DELETE request to the order endpoint. This sets the status to UNSUCCESSFUL and timestamps the cancelled_at field on the order. You can cancel orders in CREATED, PENDING, APPROVED, or UNSUCCESSFUL status. You cannot cancel an order that has already reached SUCCESSFUL — at that point, the customer has been funded and you’ve been paid. See Cancelling an order.

Tracking status changes

iwocaPay provides webhooks so you get live updates as an order’s status changes. Webhooks are configured per order, not account-wide: each order has its own webhook destination. To enable them, supply a webhook_url when you create the order — iwocaPay then sends a notification to that URL every time the order’s status changes. If you omit webhook_url, no webhook is sent for that order.

See Webhooks for the payload shape and how to verify the signature.

Reconciliation

To match payments to orders in your accounting software:

• Each order has a unique order_id and your reference field.
• The reference field appears in your bank transactions, which is how you match the iwocaPay order to the bank transaction.
• If iwocaPay is free for your customers (i.e., your business is covering the fees), the cash amount we send you is net of the iwocaPay fees and therefore won’t match the iwocaPay order amount. In this case, use the settlement reports provided in your iwocaPay Dashboard, which list all payments made to your account.

Handling edge cases

The happy path (customer checks out, gets approved, you get paid) works smoothly. But your integration also needs to handle the cases where things don’t follow that path. These are the scenarios that most commonly cause problems for sellers after launch, and planning for them upfront will save significant time.

Abandoned checkouts

If a customer starts checkout but doesn’t complete it (they close the tab, get distracted, or simply leave), the order stays in CREATED or PENDING status indefinitely. iwocaPay does not automatically cancel abandoned orders or send a cancellation signal to your system.

This means:

• If your system reserves stock on order creation, that stock remains locked.
• The customer may receive reminder emails from iwocaPay prompting them to complete checkout.
• If the customer returns and starts a new order for the same items, you may end up with duplicate orders.

What you should do: Implement your own timeout logic. If an order has been in CREATED or PENDING status for longer than your acceptable window, cancel it via the DELETE endpoint. This terminates the order and prevents the customer from completing the transaction. The order status is then UNSUCCESSFUL.

Reducing the risk of abandonment: Encouraging new customers to complete the credit assessment process via the Spending Limit Link before they check out can reduce the risk of abandoned orders. This makes checkout a quick confirmation process rather than requiring the customer to add their details and go through security checks.

Customer clicks back

If a customer clicks their browser’s back button during checkout, they return to your site but the order remains open on our side. iwocaPay does not send a signal when this happens. If the customer then re-adds items to their cart and starts a new checkout, you’ll create a second order while the first is still active.

What you should do: Cancel the previous order if the customer creates a new one. There is no automatic cancellation, so you need to do this yourself by making a DELETE request to the order endpoint (see Cancelling an order), passing the id of the original order. This sets that order to UNSUCCESSFUL and leaves only the new order active.

Customer declined

If a customer is declined by iwocaPay, the order status is automatically set to UNSUCCESSFUL. If you have webhooks configured, you’ll receive a notification. The customer sees a decline screen on the iwocaPay checkout.

The customer is then returned to your site via the redirect URL, and your system needs to handle this gracefully — the order in your system may still show as pending or processing depending on your platform.

What you should do: When you receive an UNSUCCESSFUL webhook, update the order in your system accordingly (cancel it, release stock, notify the customer as appropriate for your platform).

Stock and inventory

iwocaPay does not manage your stock. How stock behaves depends entirely on your integration:

• If you reserve stock when you create the order (before the customer has completed checkout), that stock is locked while the customer completes checkout.
• If the customer abandons or is declined, you need to release that stock yourself.

What you should do: Decide when in the flow you want to reserve stock. Some sellers reserve on order creation and accept the risk of temporary holds. Others only reserve on SUCCESSFUL status, accepting the risk that stock may sell out during checkout. There’s no single right answer — it depends on your inventory model and how time-sensitive your stock is.

Third-party system interactions

If you use an ERP, order management system, or accounting software alongside your ecommerce platform, be aware that these systems may have their own rules about orders. For example:

• An ERP may auto-cancel orders that haven’t been paid within a set window.
• An accounting system may generate an invoice on order creation, before the customer has actually paid.
• A logistics system may begin fulfilment preparation on order creation.

These rules can conflict with iwocaPay’s checkout timing. For example, if your ERP cancels an order after 15 minutes but your customer is a new iwocaPay customer who has to undergo a manual security check, you might encounter cases where the order is cancelled whilst your customer is mid-way through the iwocaPay checkout — this could be resolved by updating your ERP auto-cancellation rules.

What you should do: Map out which systems receive signals from your order flow and what automated rules they apply. If any of those rules assume near-instant payment, you’ll need to either adjust the rules or delay the signal to those systems until the order reaches SUCCESSFUL status.

Available customisations

You can customise the following per order in the order creation request. For features you enable at the account level, see Custom features.

Allowed payment terms (per order): By default, customers see all the payment terms you’ve enabled in your Dashboard (for example, Pay in 3 month terms, Pay in 12 month terms). You can override this per order by passing allowed_payment_terms in the order creation request, restricting which options the customer sees at checkout. Available values: PAY_LATER, PAY_NOW.

Common use cases: offering Pay Now only for low-value orders, or restricting to Pay Later only for specific product categories.

Note

allowed_payment_terms must contain PAY_LATER.

Per-order redirect URL: By default, customers are redirected to your configured redirect URL after checkout. You can pass a different redirect_url per order if you need customers to land on different pages depending on the product, campaign, or checkout context.