Developers Get your keys

Orders API · v1

Pay in four at your checkout.
You are paid in full.

Create an order, send the customer to payzy, ship when the signed webhook says so. The customer agrees in the payzy app and pays the first quarter there by EDAHABIA or CIB card; payzy pays your shop and carries the rest.

How it works

  1. 1Your server creates an order with the total, the goods and your own order number. payzy answers with a checkout_url.
  2. 2The customer opens it, sees the four instalments, and agrees in the payzy app (a QR code on a computer, a button on a phone).
  3. 3They pay the first quarter in the app by EDAHABIA or CIB card. The order becomes completed.
  4. 4payzy tells your server with a signed checkout.completed webhook, and sends the customer back to your return_url. You ship.
  5. 5payzy pays you the price less your fee on your daily statement, and collects the three remaining instalments itself.

Never ship on the customer returning to your return_url: anybody can type an address. Ship on the webhook, or after GET /orders/{reference} says completed.

WooCommerce plugin

A WooCommerce shop needs no code: the payzy plugin does everything on this page for it. It adds "Pay in 4 with payzy" to the checkout (the block checkout and the classic one), marks orders paid when payzy says so, sends refunds from the order screen, calls off payzy's order when you cancel one, and puts the price line, with the shopper's own check, under each product's price.

  1. Download payzy-for-woocommerce.zip, and in WordPress go to Plugins → Add New → Upload Plugin.
  2. In the shop portal, Online page: make a test key, and set the order notifications address to https://your-shop/wp-json/payzy/v1/webhook.
  3. In WooCommerce → Settings → Payments → payzy: paste the key and the webhook secret, tick "Offer payzy at checkout", save. The plugin checks the key with payzy straight away.
  4. Place a test order and complete it from payzy's page; when all is well, swap in a live key.

Needs WordPress 6.5 or later, WooCommerce 8.0 or later, and the shop's currency in Algerian dinars (DZD). In English, French and Arabic.

Quick start

Base URL: https://app.thepayzy.online/api/v1. Amounts are integers in centimes of dinar: 2400000 is 24 000.00 DA. Orders run from 5 000 DA to 150 000 DA.

curl https://app.thepayzy.online/api/v1/orders \
  -H "Authorization: Bearer pz_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "total": 2400000,
    "goods": "Robot pâtissier Moulinex",
    "order_reference": "WC-1001",
    "return_url": "https://boutique.dz/checkout/done"
  }'

The answer:

{
  "success": true,
  "message": "",
  "server_time": "2026-10-02T10:15:00+00:00",
  "data": {
    "reference": "K74Q2M",
    "order_reference": "WC-1001",
    "livemode": false,
    "status": "waiting",
    "total": 2400000,
    "current_total": 2400000,
    "currency": "DZD",
    "goods": "Robot pâtissier Moulinex",
    "first_instalment": 600000,
    "checkout_url": "https://app.thepayzy.online/pay/K74Q2M",
    "expires_at": "2026-10-02T10:45:00+00:00",
    "completed_at": null,
    "under_review": false
  }
}

Keys and test mode

Keys are made by the shop's manager in the shop portal → Online selling, and shown once. Send one as Authorization: Bearer ….

Testpz_test_…

Test orders: the same API, the same hosted page and the same signed webhooks, but no customer can see them and no money moves. On the order's checkout_url, choose Customer paid or Customer walked away. Available before payzy has checked your domain.

Livepz_live_…

Real orders, real customers. Needs the website domain payzy checked when your shop joined; return_url and the webhook address must be on it.

Test and live never mix: a test key cannot see a live order, and an order number used in test can be used again for real.

Answers and errors

Every answer has the same envelope. A refusal carries a real HTTP status and a stable code; switch on code, never on message (written for people, in their language).

{ "success": false, "message": "…", "server_time": "…", "code": "order_reference_reused" }
HTTPcodeMeaning
401api_key_invalidNo key, a wrong one, or one revoked.
404checkout_not_foundNo such order for this key (or the other mode's).
409order_reference_reusedThat order number already exists with another total or other goods.
409checkout_already_paidToo late to cancel: refund it instead.
409order_not_completedOnly a completed order can be refunded.
422validationA field is missing or wrong; data.fields names each.
422return_url_invalidThe return_url is not HTTPS on your domain.
429too_many_requestsSlow down and retry after a moment.

Orders

POST/orders

Create. Once-only by order_reference: the same order sent again returns the first (200, not 201).

GET/orders/{reference}

An order as it stands.

GET/orders?status=completed&page=1

Your orders, newest first, 50 a page, with has_more.

POST/orders/{reference}/cancel

Call it off, before the first quarter is paid.

POST/orders/{reference}/refunds

Refund a completed order, whole or in part.

FieldType
totalintegerRequired. Centimes, 500000 to 15000000.
goodsstringRequired. What is sold, as the customer reads it in the contract.
order_referencestring ≤ 64Required. Your order number: letters, digits and _-:.#/.
return_urlhttps URLRequired. On your domain. The customer returns with payzy_reference and payzy_status (completed or cancelled).

An order stays open for 30 minutes for the customer to agree, then 30 more for them to pay the first quarter, or it lapses.

Statuses

waitingThe customer has not agreed yet.
agreedAgreed; the first quarter is not paid yet. Do not ship. If under_review is true, payzy is checking the purchase (usually under 30 minutes).
completedThe first quarter is paid and the purchase has started. Ship.
cancelledCalled off by you or the customer, or lapsed unpaid.
expiredNobody agreed in time.
refundedGiven back in whole.

Refunds

Without amount, the whole order is refunded and ends. With less, its price comes down by that much: the customer's later instalments shrink first, and anything they paid beyond the new price goes back to them. Your next statement takes back what payzy paid you for it.

POST /orders/K74Q2M/refunds
{ "amount": 400000, "reason": "One accessory out of stock" }

Account

GET /me says which shop and which mode a key belongs to, your webhook address and the order limits: what a plugin's "test the connection" button needs.

Webhooks

Set your address in the shop portal (HTTPS, on your domain); the signing secret is shown there. Each event is a POST with a JSON body. Answer any 2xx within 10 seconds; anything else is retried after 1, 5, 30, 120, 360, 720 and 1440 minutes. The same event can arrive twice: act once per id. The portal lists every delivery, can resend one, and can send a ping to try your endpoint.

checkout.completedThe first quarter is paid. Ship.
checkout.cancelledCalled off or lapsed. Release the stock.
order.refundedA refund, in data.refund (full or part, and the amount).
pingSent from the portal to test your endpoint.
POST /payzy/webhook
Payzy-Event: checkout.completed
Payzy-Delivery: evt_9x2kq0a7m3c1b5d8e4f6g0h2
Payzy-Signature: t=1759400100,v1=5f2b…c9

{
  "id": "evt_9x2kq0a7m3c1b5d8e4f6g0h2",
  "type": "checkout.completed",
  "created_at": "2026-10-02T10:15:00+00:00",
  "livemode": true,
  "data": {
    "reference": "K74Q2M",
    "order_reference": "WC-1001",
    "channel": "online",
    "total": 2400000,
    "currency": "DZD",
    "status": "active"
  }
}

Verifying signatures

Payzy-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of t + "." + raw body with your webhook secret. Use the raw body, compare in constant time, and refuse anything older than five minutes.

$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_PAYZY_SIGNATURE'] ?? ''), $sig);

$expected = hash_hmac('sha256', ($sig['t'] ?? '').'.'.$body, getenv('PAYZY_WEBHOOK_SECRET'));
if (! hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
if ($event['type'] === 'checkout.completed') {
    // Mark order $event['data']['order_reference'] as paid, once.
}
http_response_code(200);

Pay with payzy button

For your own checkout page, without drawing the button yourself. It shows "Pay in 4 with payzy" with the four parts, and the shopper's "Can I pay with payzy?" check. On a click it asks your server to make the order (your key never reaches the browser), then sends the shopper to payzy's page. It follows nothing but payzy's own page for an order, and draws nothing outside the basket range.

<script src="https://thepayzy.online/button.js" defer></script>
<div data-payzy-button
     data-payzy-price="24000"          <!-- the cart's total, in dinars -->
     data-payzy-action="/payzy/start"> <!-- your endpoint, on your own site -->
</div>

Your endpoint receives a POST from the shopper's browser (with your site's cookies, and X-CSRF-TOKEN from <meta name="csrf-token"> when the page has one). It makes the order from the cart on your server, never from anything the browser sends, and answers {"checkout_url": "…"}:

Route::post('/payzy/start', function (Request $request) {
    $cart = Cart::forSession($request->session());   // your cart, your prices

    $order = Http::withToken(env('PAYZY_KEY'))->post('https://app.thepayzy.online/api/v1/orders', [
        'total' => $cart->totalInCentimes(),
        'goods' => $cart->summary(),
        'order_reference' => $cart->orderNumber(),
        'return_url' => route('checkout.done'),
    ])->throw()->json('data');

    return ['checkout_url' => $order['checkout_url']];
});

Change data-payzy-price when the cart changes and the button follows. It fires payzy:start and payzy:error events on the element; data-payzy-lang sets its language (otherwise the page's). As everywhere, ship on the checkout.completed webhook, not on the shopper's return.

Price widget

One line beside each price: "or 4 × 6 000,00 DA, no fees, with payzy", in the page's language, the amounts exactly as payzy splits them.

<script src="https://thepayzy.online/widget.js" defer></script>
<span data-payzy-price="24000"></span>             <!-- price in dinars -->
<span data-payzy-price="24000" data-payzy-lang="ar"></span>
<span data-payzy-price="24000" data-payzy-check="off"></span>  <!-- without the link below -->

After the line, the widget adds a link, "Can I pay with payzy?", to the shopper's own check for that price (below). data-payzy-check="off" leaves it out.

Can I pay with payzy?

Shoppers can find out before they reach your checkout whether they can pay with payzy, and whether a price fits what they can spend. They prove their number with a code and see the answer themselves; your shop never sees it, and nothing about it goes through your server or the API.

Link to it from a product page, a cart or a help page, with the price in dinars:

https://thepayzy.online/check?amount=24000&lang=fr

The shopper sees one of: they can pay, and up to how much (and whether this price fits, with the four parts); they have no account yet, or still need to send their ID card, and how to; their documents are being checked; or new purchases are paused, and what to do. It applies the checkout's own rules, so its answer holds at your checkout unless something changes in between: a payment falling overdue, or several purchases in one day.

Showing payzy only to shoppers who can use it is not possible and not wanted: a shop never learns who is a payzy customer, or what they can spend.

Going live

  • Every status handled with a test key, completed and cancelled, from the hosted page.
  • Signatures verified on the raw body, old ones refused, each event acted on once.
  • Shipping only on completed, never on the return to your site.
  • Keys and the webhook secret on your server only, never in a page or an app.
  • A live key made, and the test key revoked if you no longer need it.

Questions? shops@thepayzy.online