Developer documentation

1. Create a merchant in the console and configure Payzone with your paywall URL, merchant account and secret keys.
2. Generate an API key (prefix pg_live_). The plaintext value is shown once.
3. Call the REST API to create a payment link.
4. Forward the returned payment_url to your customer (WhatsApp, email, SMS…).
5. Receive a server-to-server webhook on terminal status.

Every REST request must include a bearer API key. Treat keys as secrets and rotate them via the console.

Authorization: Bearer pg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST /api/public/v1/payment-links

curl -X POST https://pg.1confirmed.com/api/public/v1/payment-links \
  -H "Authorization: Bearer pg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "payzone",
    "amount_cents": 12500,
    "currency": "MAD",
    "description": "Invoice #A-1042",
    "reference": "INV-A-1042",
    "customer_name": "Sara Bennani",
    "customer_email": "sara@example.com",
    "customer_phone": "+212600112233"
  }'

Response:

{
  "id": "8b9b…",
  "reference": "INV-A-1042",
  "payment_url": "https://pg.1confirmed.com/pay/8b9b…",
  "status": "pending"
}

Configure your Payzone account callback URL to https://pg.1confirmed.com/api/public/callback/{merchantCode}. PG verifies the X-Callback-Signature HMAC-SHA256 header against the merchant secret before updating the payment status — invalid signatures return 401.

Register one or more endpoints from the console. Every delivery is signed:

POST https://your-app.example.com/hooks/pg
x-pg-event: payment.succeeded
x-pg-signature: hex(hmac_sha256(endpoint_secret, body))

{
  "event": "payment.succeeded",
  "created_at": "2026-06-23T13:45:01.000Z",
  "data": {
    "payment_request_id": "8b9b…",
    "reference": "INV-A-1042",
    "gateway": "payzone",
    "gateway_transaction_id": "PZN-9817263",
    "status": "succeeded"
  }
}

Verify the signature with a constant-time comparison. Failed deliveries are retried automatically with an exponential schedule (5m, 15m, 1h, 4h, 12h) before being marked exhausted.

• payment.processing — gateway acknowledged but not finalized.
• payment.succeeded — funds captured.
• payment.failed — gateway returned a terminal failure.
• payment.cancelled — customer cancelled before completion.

When a payment reaches a terminal state and a customer_phone was provided, PG dispatches a WhatsApp confirmation through the 1Confirmed messaging API. This requires the ONECONFIRMED_API_KEY backend secret. When the secret is absent the rest of the flow continues unchanged.

The API uses standard HTTP status codes and returns a JSON body:

{ "error": "Invalid signature" }

• 400 — validation error (check error field).
• 401 — missing/invalid API key or callback signature.
• 403 — API key does not belong to the requested merchant.
• 404 — unknown merchant or payment reference.
• 503 — gateway not configured for this merchant.