Trial copy
Skip to content
PAYUNIT
ENع Sign in Create account
  1. Home
  2. Developers

Connect your store to PAYUNIT

From opening an account to money in your balance, step by step.

Create account Watch the video
  1. Open an account, verify your identity — Verification unlocks invoices and the API
  2. Create an API key — and a webhook address, on the Developers page
  3. Your server creates an invoice — One request returns the checkout link
  4. Your customer pays — with the method they prefer
  5. PAYUNIT notifies your server — Check the signature, then fulfil the order
  6. Money in your balance — In dollars, minus the fee

Two ways to connect

Pick the easier one. Both need a verified account and an API key.

With a plugin

  1. 1Install the plugin
  2. 2Paste your key
  3. Done

For your WooCommerce, WHMCS or other store, with no code.

The key is on the Developers page in your account.

With the API

  1. 1Account
  2. 2Key
  3. 3Invoice
  4. 4Checkout
  5. 5Webhook
  6. 6Balance

For your own site or app: one request creates the invoice, a signed webhook tells you it is paid.

See the code

Watch the full walkthrough

A short video, no sound.

Other version: العربية

The code, step by step

Real PAYUNIT requests and responses, with test values. Keep your key and secret in your server settings, never in code.

1Create an invoice

From your server only, with your API key in the Authorization header.

  • Authorization: Bearer pay_live_….…
  • Idempotency-Key — send it with every request and an invoice is never created twice.
  • amount — a decimal string in dollars, like "100.00".
POST /api/v1/invoices
curl -X POST 'https://test.payunit.co/api/v1/invoices' \
  -H 'Authorization: Bearer pay_live_9c1e5b27a0d4.YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042' \
  -d '{
    "amount": "100.00",
    "currency": "USD",
    "external_ref": "1042",
    "description": "Order #1042",
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/cart"
  }'
<?php
// Your server: create the invoice, then send the customer to pay.
$ch = curl_init('https://test.payunit.co/api/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAYUNIT_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: order-' . $order['id'],
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => '100.00',
        'currency' => 'USD',
        'external_ref' => (string)$order['id'],
        'description' => 'Order #' . $order['id'],
        'success_url' => 'https://example.com/thanks',
        'cancel_url' => 'https://example.com/cart',
    ]),
]);
$invoice = json_decode(curl_exec($ch), true);

header('Location: ' . $invoice['checkout_url']);
exit;
Response: 201 Created
HTTP/1.1 201 Created

{
    "id": "inv_WzWf7sl36aTK7TWV",
    "number": "860549779872",
    "status": "pending",
    "environment": "live",
    "amount": "100.00",
    "currency": "USD",
    "fee": "0.00",
    "net": "100.00",
    "external_ref": "1042",
    "description": "Order #1042",
    "checkout_url": "https://test.payunit.co/pay/inv_WzWf7sl36aTK7TWV",
    "created_at": "2026-10-09T06:52:11Z",
    "expires_at": "2026-10-16T06:52:11Z",
    "paid_at": null,
    "metadata": [],
    "payment": null
}

2Send the customer to checkout

Open checkout_url for them. They choose a method and pay, then come back to success_url.

PHP
header('Location: ' . $invoice['checkout_url']);
exit;

3Receive and verify the webhook

When the invoice is paid, PAYUNIT sends invoice.paid to your webhook address, signed with your secret.

  • Payunit-Signature: v1=HMAC_SHA256(secret, timestamp + "." + body)
  • Public HTTPS addresses only. Answer 200, otherwise it is sent again later.
PHP
<?php
// https://example.com/payunit/webhook
$secret = getenv('PAYUNIT_WEBHOOK_SECRET');   // whsec_...
$body   = file_get_contents('php://input');
$ts     = $_SERVER['HTTP_PAYUNIT_TIMESTAMP'] ?? '';
$sig    = $_SERVER['HTTP_PAYUNIT_SIGNATURE'] ?? '';

$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($expected, $sig) || abs(time() - (int)$ts) > 300) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
if ($event['event'] === 'invoice.paid') {
    // The same Payunit-Event-Id can arrive again: handle it once.
    mark_order_paid($event['data']['external_ref'], $event['data']['net']);
}
http_response_code(200);   // any other answer is retried later
What reaches your server
POST /payunit/webhook HTTP/1.1
Content-Type: application/json
Payunit-Event-Id: evt_xMflR7MpsFLAEpcf
Payunit-Timestamp: 1791528731
Payunit-Signature: v1=2785ed092900ecdff6d622978dd2c6f5128ffa24a9d1200c365c232e1fc6e8a9
User-Agent: PAYUNIT-Webhook/18.7.0

{
    "id": "evt_xMflR7MpsFLAEpcf",
    "event": "invoice.paid",
    "created_at": "2026-10-09T06:52:11Z",
    "data": {
        "environment": "live",
        "invoice_id": "inv_WzWf7sl36aTK7TWV",
        "invoice_number": "860549779872",
        "external_ref": "1042",
        "status": "paid",
        "amount": "100.00",
        "currency": "USD",
        "fee": "0.50",
        "net": "99.50",
        "metadata": [],
        "payment": {
            "reference": "984924871059",
            "method": "wallet",
            "payer_name": "Lina Customer",
            "payer_email": "[email protected]",
            "payer_phone": "+970599 ••• 012",
            "payer_country": "PS",
            "paid_at": "2026-10-09T06:52:11Z"
        }
    }
}

4Check the status (optional)

Ask for the invoice by its id at any time.

GET /api/v1/invoices/{id}
curl 'https://test.payunit.co/api/v1/invoices/inv_WzWf7sl36aTK7TWV' \
  -H 'Authorization: Bearer pay_live_9c1e5b27a0d4.YOUR_SECRET'

# 200 OK
{ "id": "inv_WzWf7sl36aTK7TWV", "status": "paid", "amount": "100.00",
  "fee": "0.50", "net": "99.50", "paid_at": "2026-10-09T06:52:11Z", ... }

5Get the money

The net amount lands in your PAYUNIT balance, in dollars. The fee depends on the method: 0.5% from a PAYUNIT balance, 1.5% in digital currency.

A real example

  1. Amount 100.00 $
  2. Fee −0.50 $
  3. Net 99.50 $
Fees

Open the docs

Questions

Developer questions

Where are the full docs?

On the Developers page in your account, with ready examples.

How do I verify a webhook?

Compute HMAC-SHA256 of the timestamp and body with your webhook secret, and compare it with Payunit-Signature.

What currency are invoices in?

In US dollars (USD), and 1 USDT = 1 $.

PAYUNIT

Start now, for free

Open your account in a minute. No monthly fee.

Open your free account Sign in