# ADNYS Pay — Developer Guide

**How every ADNYS product takes payments through pay.adnys.com**

ADNYS FZE · SRTIP, Sharjah, UAE · info@adnys.com · Version 3.1 (October 2026)

**Online version with a live sandbox and a test checkout:** https://pay.adnys.com/developers

---

## 1. The one rule

Every ADNYS product — GetFIT, Beats Digital Invites, EduLogiTech, ADNYS and any future app — takes payments **only through ADNYS Pay** (`https://pay.adnys.com`).

| Your app **does** | Your app **never** |
|---|---|
| Creates the order in its own database | Shows card fields or collects card numbers |
| Sends the customer to ADNYS Pay | Connects to Tap, Stripe or any gateway directly |
| Confirms payment server-to-server | Marks an order paid because the browser came back |
| Activates the order when ADNYS Pay confirms | Takes the amount from the URL or the browser |

The payment gateway (Tap Payments) key lives only on pay.adnys.com. Apps get their own API key, which can only create and read their own payments.

---

## 2. How a payment works

```
 Customer          Your app (server)             pay.adnys.com                Tap Payments
    │  clicks "Pay"      │                             │                            │
    │──────────────────▶ │  1. POST /payments/create   │                            │
    │                    │ ──────────────────────────▶ │                            │
    │                    │  ◀── payment_url ────────── │                            │
    │ ◀─ 303 redirect ── │                             │                            │
    │  2. ADNYS Pay checkout (order summary, secure badges)                         │
    │ ───────────────────────────────────────────────▶ │  3. Tap hosted card page   │
    │ ─────────────────────────────────────────────────────────────────────────────▶│
    │                                                  │ ◀─ 4. confirmed s2s ────── │
    │  5. Result page + receipt + email               │                            │
    │ ◀─────────────────────────────────────────────── │                            │
    │  6. "Back to app" → return_url?payment_id=…&order_id=…                        │
    │ ─────────────────▶ │  7. GET /payments/{id} → verify                          │
    │                    │ ◀── 8. webhook payment.paid (signed, retried) ──         │
    │  order activated   │                             │                            │
```

1. Your server creates the payment with the **amount from your database**.
2. The customer sees the ADNYS Pay checkout (product, amount, partner logos, "Pay securely").
3. They pay on Tap's secure page. Card details never touch ADNYS Pay or your app.
4. ADNYS Pay confirms the result with Tap **server-to-server** (amount, currency and reference are cross-checked).
5. The customer sees the result page and gets a receipt email.
6. They return to your `return_url` with `payment_id` and `order_id` in the query string.
7. Your success page verifies the payment with the API before showing "Paid".
8. ADNYS Pay also sends a signed **webhook** to your app. This is the reliable path — it works even if the customer closes the browser.

Steps 7 and 8 can arrive in any order and more than once. Your "mark paid" code must be safe to run twice.

---

## 3. Before you start (one-time setup per app)

Ask the ADNYS Pay admin to add your app in **Admin → Products & API**. You will receive:

| Item | Example | Where it goes |
|---|---|---|
| Product code | `getfit` | `config.php` |
| Sandbox key + secret | `pk_sandbox_…` / `sk_sandbox_…` | `config.php` while building and testing — simulated payments only |
| Live API key | `pk_live_…` | `config.php` (server only) when going live |
| Live API secret | `sk_live_…` | `config.php` (server only) — shown once |
| Webhook secret | `whsec_…` | `config.php` (server only) |

The admin also sets these for your app:

| Setting | Example |
|---|---|
| Allowed host | `getfit.adnys.com` |
| Return URL | `https://getfit.adnys.com/adnys/success.php` |
| Cancel URL | `https://getfit.adnys.com/adnys/cancel.php` |
| Webhook URL | `https://getfit.adnys.com/adnys/webhook.php` |
| Currencies | `AED` (USD needs a separate Tap account — not active yet) |

All URLs must be **HTTPS** and on the **allowed host**. Anything else is rejected.

---

### Sandbox (test keys)

Payments created with a **sandbox key** go through a **simulated card page** on pay.adnys.com with three buttons — **Approve**, **Decline** and **Cancel**. No gateway is called and no money moves, even while ADNYS Pay is live. Statuses, webhooks and receipts behave exactly like real payments; sandbox payments are never counted as income and never send customer emails. API responses include `"sandbox": true`.

A **public demo key** (product `demo`) is published on https://pay.adnys.com/developers so anyone can try the API and the checkout straight away. It is rate-limited and can only return to pay.adnys.com pages. For your app, ask the admin for its own sandbox key.

---

## 4. Option A — PHP apps: use the `adnys` app kit (recommended)

The kit (`adnys-app-kit.zip`) is the same folder for every app. You only edit two files.

```
your-app/public_html/adnys/
├── config.php    ← EDIT: keys, product code, your site address
├── hooks.php     ← EDIT: connect to your orders table (the only code you change)
├── pay.php       ← pay button target
├── success.php   ← return page (verifies with the API)
├── cancel.php    ← customer cancelled / payment failed
├── webhook.php   ← signed notifications from ADNYS Pay
├── payment.php   ← API client (don't edit)
├── _init.php     ← loader (don't edit)
└── .htaccess     ← blocks browser access to config files (don't delete)
```

**Steps**

1. Upload the `adnys` folder to your app's `public_html` → `https://yourapp.adnys.com/adnys/`.
2. `config.php`: paste key, secret, webhook secret, product code and site address; set `after_paid_page` and `after_cancel_page`.
3. `hooks.php`: implement four functions against your database:

| Function | Must do |
|---|---|
| `adnys_get_order($orderId)` | Return `order_id`, `amount`, `currency`, `description`, `status`, `customer{name,email,phone}` from **your DB**. Return `null` if not found / not this user's. |
| `adnys_mark_paid($orderId, $paymentId)` | Set the order paid and activate it. **Idempotent** — only activate when the status actually changes. |
| `adnys_mark_failed($orderId, $paymentId)` | Optional: mark failed (only if still pending). |
| `adnys_mark_refunded($orderId, $amount, $full)` | Mark refunded; cancel access if `$full`. |

4. Add the pay button:
   ```html
   <a href="/adnys/pay.php?order_id=GF-2026-00125" class="btn">Pay securely with ADNYS Pay</a>
   ```
5. Test (section 10). Then check `https://yourapp.adnys.com/adnys/config.php` shows **403 Forbidden**.

---

## 5. Option B — any language: the API

Base URL: `https://pay.adnys.com/api/v1` · JSON in and out · server-to-server only (never call from a browser or mobile app directly).

### 5.1 Authentication (every request)

| Header | Value |
|---|---|
| `X-ADNYS-Key` | your API key (`pk_live_…`) |
| `X-ADNYS-Timestamp` | current Unix time in seconds (must be within 5 minutes of the server) |
| `X-ADNYS-Nonce` | random string, 16–64 chars `[A-Za-z0-9_-]`, **new for every request** |
| `X-ADNYS-Signature` | lowercase hex `HMAC-SHA256(secret, timestamp + "\n" + nonce + "\n" + METHOD + "\n" + path + "\n" + body)` |
| `Content-Type` | `application/json` (POST) |
| `Idempotency-Key` | optional, 8–100 chars `[A-Za-z0-9_-:.]` — same key returns the same payment |

- `path` is the path **without** the query string, e.g. `/api/v1/payments/create`.
- `body` is the exact raw JSON you send (empty string for GET).
- A nonce can be used once; repeats are rejected with `409`.

**Signing example (Node.js)**

```js
const crypto = require('crypto');
function adnysHeaders(key, secret, method, path, body = '') {
  const ts = Math.floor(Date.now() / 1000).toString();
  const nonce = crypto.randomBytes(16).toString('hex');
  const sig = crypto.createHmac('sha256', secret)
    .update(`${ts}\n${nonce}\n${method.toUpperCase()}\n${path}\n${body}`).digest('hex');
  return { 'X-ADNYS-Key': key, 'X-ADNYS-Timestamp': ts, 'X-ADNYS-Nonce': nonce,
           'X-ADNYS-Signature': sig, 'Content-Type': 'application/json' };
}
```

### 5.2 Create a payment

`POST /api/v1/payments/create`

```json
{
  "product": "getfit",
  "order_id": "GF-2026-00125",
  "amount": 149.00,
  "currency": "AED",
  "description": "GetFIT Monthly Subscription",
  "customer": { "name": "Aisha Rahman", "email": "aisha@example.com", "phone": "+971501234567" },
  "return_url": "https://getfit.adnys.com/adnys/success.php",
  "cancel_url": "https://getfit.adnys.com/adnys/cancel.php",
  "webhook_url": "https://getfit.adnys.com/adnys/webhook.php",
  "metadata": { "user_id": "8812", "plan": "monthly" }
}
```

| Field | Rules |
|---|---|
| `order_id` | **required**, your order number, max 100 chars |
| `amount` | **required**, > 0, max 2 decimals, from **your database** |
| `currency` | **required**, must be enabled for your app (currently `AED`) |
| `product` | optional; if sent, must match the API key's product |
| `description` | optional, max 255 chars — shown on checkout and receipt |
| `customer` | optional but recommended (name, email, phone with country code) — email receives the receipt |
| `return_url`, `cancel_url`, `webhook_url` | optional; default to the app's saved URLs; HTTPS on the allowed host |
| `metadata` | optional, up to 20 keys, stored with the payment |

**Response `201`** (or `200` when an open payment is reused)

```json
{
  "success": true,
  "payment_id": "ADP-7Q2K9M4X1B",
  "payment_url": "https://pay.adnys.com/checkout/ADP-7Q2K9M4X1B?t=…",
  "status": "created",
  "amount": 149.0,
  "currency": "AED",
  "expires_at": "2026-10-27T10:15:00Z"
}
```

Redirect the customer to `payment_url` (HTTP 303). The link expires after **60 minutes**.

**Order rules applied by ADNYS Pay**
- Same `order_id` + same amount + still open → the **same** payment is returned (no duplicates if the customer clicks twice).
- Order already paid → `409 order_already_paid` with the existing `payment_id`. Treat it as paid (verify it) and don't charge again.
- If the amount of an order changes, create a **new** `order_id`.

### 5.3 Read a payment

`GET /api/v1/payments/{payment_id}` — add `?refresh=1` to re-check with the gateway when status is pending.
(Sign the path **without** `?refresh=1`.)

```json
{
  "success": true,
  "payment_id": "ADP-7Q2K9M4X1B",
  "order_id": "GF-2026-00125",
  "product": "getfit",
  "status": "paid",
  "amount": 149.0,
  "currency": "AED",
  "refunded_amount": 0,
  "payment_method": "card",
  "provider_reference": "chg_LV…",
  "customer": { "name": "Aisha Rahman", "email": "aisha@example.com", "phone": "+971501234567" },
  "description": "GetFIT Monthly Subscription",
  "created_at": "2026-10-27T09:15:00Z",
  "paid_at": "2026-10-27T09:16:42Z",
  "expires_at": "2026-10-27T10:15:00Z"
}
```

**Treat an order as paid only when all match:** `status` is `paid` (or `partially_refunded`), `order_id` = your order, `amount` = your DB amount, `currency` = your currency.

`GET /api/v1/payments?order_id=GF-2026-00125` — all payments for one of your orders (latest first, max 20). Sign path `/api/v1/payments`.

### 5.4 Errors

```json
{ "success": false, "error": { "code": "validation_error", "field": "amount", "message": "amount must be a positive number" } }
```

| HTTP | `code` | Meaning / what to do |
|---|---|---|
| 400 | `invalid_json`, `bad_idempotency_key` | Fix the request |
| 401 | `unauthorized` | Wrong key/secret, bad signature or clock off by > 5 min |
| 403 | `unauthorized` | Product disabled in ADNYS Pay |
| 404 | `not_found` | Payment doesn't exist or isn't your app's |
| 409 | `order_already_paid` | Verify and mark the order paid — don't charge again |
| 409 | `idempotency_conflict` | Same Idempotency-Key with different data |
| 409 | `unauthorized` (replay) | Nonce reused — generate a new one per request |
| 422 | `validation_error` | See `field` |
| 422 | `no_payment_channel` | Currency not active (e.g. USD) |
| 429 | `rate_limited` | Public demo key busy — wait, or use your own sandbox key |
| 500 | `server_error` | Retry later; show "Payment unavailable, try again" |

---

## 6. Webhooks (server notifications to your app)

ADNYS Pay `POST`s to your `webhook_url` when a payment changes.

| Event | When |
|---|---|
| `payment.paid` | Payment confirmed by the gateway |
| `payment.failed` | Payment declined / failed |
| `payment.refunded` | Full or partial refund issued from ADNYS Pay admin |

**Headers:** `X-ADNYS-Event: payment.paid` · `X-ADNYS-Signature: t=1761556602,v1=<hex>`

**Body**

```json
{
  "event": "payment.paid",
  "payment_id": "ADP-7Q2K9M4X1B",
  "order_id": "GF-2026-00125",
  "product": "getfit",
  "status": "paid",
  "amount": 149.0,
  "currency": "AED",
  "refunded_amount": 0,
  "payment_method": "card",
  "paid_at": "2026-10-27T09:16:42Z",
  "sent_at": "2026-10-27T09:16:44Z"
}
```

**Verify every webhook**
1. Read the **raw** request body (before JSON parsing).
2. Split the header into `t` and `v1`.
3. Reject if `|now − t| > 300` seconds.
4. Compute `HMAC-SHA256(webhook_secret, t + "." + rawBody)` as lowercase hex and compare to `v1` with a constant-time compare.
5. For `payment.paid`, also call `GET /payments/{id}` and check order, amount and currency against **your DB** before activating.

**Respond** `2xx` within 15 seconds once handled (also for orders you don't recognise). Any other response is retried after **1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h, 24 h**; after that the ADNYS Pay admin is alerted. Webhooks can arrive more than once — handle them idempotently.

---

## 7. Pages your app must have

### 7.1 Order / pay page (in your app)
- Shows what is being bought, the amount and currency **from your DB**, and the order number.
- One button: **"Pay securely with ADNYS Pay"** that goes to your **server** route (e.g. `/adnys/pay.php?order_id=…`), which creates the payment and redirects.
- Optional line under the button: *"You'll be taken to pay.adnys.com, the secure payment portal of ADNYS FZE."*
- If the order is already paid, show "Paid" — no pay button.
- Never put the API key, secret or amount logic in JavaScript, HTML forms or mobile app code.

### 7.2 Success page (`return_url`)
- Receives `?payment_id=…&order_id=…`. These are **hints only**.
- Load the order from your DB, call the API (`refresh=1`), and check status + order + amount + currency.
- Verified → mark paid (idempotent) → "Payment successful — order GF-2026-00125 is confirmed" + link to the customer's account.
- Not yet confirmed → "Confirming your payment… this usually takes a few seconds. Please don't pay again." + a **Check again** button. The webhook will complete it.
- Never show "Paid" or activate anything from the redirect alone.

### 7.3 Cancel page (`cancel_url`)
- Used when the customer cancels, the payment fails, or the link expires.
- Show "Payment not completed — you have not been charged" + **Try again** (back to the pay page) + a support contact.
- Keep the order **pending** so it can be paid again.

### 7.4 Webhook endpoint (`webhook_url`)
- Public HTTPS URL, `POST` only, no login, no CSRF check, no redirects.
- Verifies the signature (section 6), updates the order, returns `200`.

### 7.5 Your orders table (minimum)

| Column | Purpose |
|---|---|
| `order_no` (unique) | sent as `order_id` |
| `amount`, `currency` | the price — the only source of truth |
| `status` | `pending` → `paid` / `failed` / `refunded` / `partially_refunded` |
| `adnys_payment_id` | `ADP-…` of the paid payment (show it in support screens) |
| `paid_at` | when it was confirmed |

---

## 8. What the ADNYS Pay checkout already does (don't rebuild it)

- Branded **ADNYS Pay** checkout: product name and logo, amount, order number, "Secure checkout", payment-partner logos (Tap, Visa, Mastercard, Apple Pay, Google Pay).
- Hands the customer to **Tap's** secure hosted page — ADNYS Pay and your app never see card data.
- Shows the bank's reason when a payment fails and lets the customer retry.
- Shows the result page with a **printable receipt** (company details, TRN if set) and emails the receipt.
- Expires unused links after 60 minutes.
- Refunds are done by ADNYS finance in the ADNYS Pay admin; your app is told by `payment.refunded`.
- Revenue, fees, reconciliation and CSV exports for every app are in the ADNYS Pay admin. Income counts **live** payments only.

---

## 9. Payment statuses

| API `status` | Meaning | Your order |
|---|---|---|
| `created` | Payment created, customer hasn't chosen a method | pending |
| `pending` / `processing` | Customer is on the payment page / confirmation in progress | pending |
| `paid` | Confirmed by the gateway server-to-server | **paid → activate** |
| `failed` | Declined by the bank (customer can retry) | pending or failed |
| `cancelled` | Customer cancelled | pending |
| `expired` | Link not used within 60 minutes | pending (create a new payment) |
| `partially_refunded` | Part of the amount returned | your choice (still paid) |
| `refunded` | Fully refunded | refunded → remove access |

A `failed`, `cancelled` or `expired` payment can still turn `paid` later if the gateway confirms a genuine late success — always follow the webhook.

---

## 10. Testing

**Sandbox key** (recommended for building): simulated card page — choose Approve, Decline or Cancel. Works any time, even when ADNYS Pay is live.

**TEST mode** (ADNYS Pay sidebar shows yellow TEST MODE): the whole site uses Tap's test environment; use Tap's published test cards. Test payments are tagged **TEST** and never counted as income.

**LIVE mode** (green LIVE): real cards and real money. Do a final **AED 1.00** live payment and ask ADNYS finance to refund it.

**Test checklist**

- [ ] Pay button redirects to pay.adnys.com with the correct product, amount and order number
- [ ] Successful payment → order becomes **paid** in your app and **PAID** in ADNYS Pay admin
- [ ] Close the browser right after paying → order still becomes paid (webhook)
- [ ] Click "Pay" twice → only one payment is created
- [ ] Declined card → cancel page, order stays pending, retry works
- [ ] Cancel on the checkout → cancel page, no charge
- [ ] Changing `amount` in the URL or browser has **no effect**
- [ ] Tampered webhook (wrong signature) → rejected with 400
- [ ] Same webhook sent twice → order activated once
- [ ] Refund from ADNYS Pay admin → order marked refunded in your app
- [ ] `https://yourapp.adnys.com/adnys/config.php` → **403 Forbidden**

---

## 11. Security rules (must follow)

1. Keys and secrets stay on the server, in config files blocked from the web, never in Git, JavaScript or mobile apps.
2. The amount always comes from **your database**.
3. Activate orders only after a **server-to-server** check (API or verified webhook).
4. Verify every webhook signature and timestamp; compare with a constant-time function.
5. Make "mark paid" **idempotent**.
6. Use HTTPS everywhere; keep your server clock correct (NTP) — signatures expire after 5 minutes.
7. Log `payment_id` with your order for support; never log secrets or full request signatures.
8. If a key leaks, ask the ADNYS Pay admin to **rotate** it immediately (Products & API → API keys).

---

## 12. Go-live checklist

- [ ] App registered in ADNYS Pay with the correct allowed host and URLs
- [ ] LIVE keys in `config.php` (not test keys)
- [ ] All tests in section 10 pass
- [ ] AED 1.00 live payment confirmed, then refunded
- [ ] App's terms/refund policy link to `https://adnys.com/home/refund-policy.php` (or your own)
- [ ] Support contact visible on your pay, success and cancel pages

---

## 13. Support

**ADNYS FZE** — SRTIP, Sharjah, UAE · info@adnys.com · +971 56 116 6349
Payment portal: https://pay.adnys.com · Health check: https://pay.adnys.com/api/v1/health

When reporting a payment issue, always send the **payment ID** (`ADP-…`) and your **order ID**.
