1. The rules
One rule above all: apps never touch card details or the payment gateway. They create an order, send the customer to ADNYS Pay, and activate the order only when ADNYS Pay confirms it.
Your app does
- Creates the order in its own database
- Sends the customer to ADNYS Pay from the server
- Confirms the payment server-to-server (API or signed webhook)
- Activates the order once — even if told twice
Your app never
- Shows card fields or collects card numbers
- Connects to Tap, Stripe or any gateway directly
- Marks an order paid because the browser came back
- Takes the amount from the URL, a form or JavaScript
2. How a payment works
- 1Create
Your server calls
POST /payments/createwith the amount from your database and gets apayment_url. - 2Checkout
The customer is redirected to the ADNYS Pay checkout: product, order number, amount, partner logos.
- 3Pay
They pay on the gateway's secure page (Tap). Card data never reaches ADNYS Pay or your app.
- 4Confirm
ADNYS Pay confirms with the gateway server-to-server and cross-checks amount, currency and reference.
- 5Return
The customer sees a receipt, then returns to your
return_url?payment_id=…&order_id=…. - 6Verify & activate
Your success page checks
GET /payments/{id}; the signedpayment.paidwebhook arrives too. Either one activates the order — once.
3. Get started
Explore with the demo key
Use the public sandbox key below to call the API and open test checkouts today. Nothing to install.
Sandbox →Get your app's sandbox key
Ask the ADNYS Pay admin to register your app and create a sandbox key. Build and test your whole flow with it.
App kit →Go live
Pass the checklist, swap in the live key, and make one AED 1.00 live payment (refunded by finance).
Checklist →What the admin sets up for your app (Admin → Products & API)
| Item | Example | Notes |
|---|---|---|
| Product code | getfit | Sent as product |
| Sandbox key + secret | pk_sandbox_… / sk_sandbox_… | Simulated payments only — for building & testing |
| Live key + secret | pk_live_… / sk_live_… | Real money. Server-side only; secret shown once |
| Webhook secret | whsec_… | Verifies notifications from ADNYS Pay |
| Allowed host | getfit.adnys.com | All URLs must be HTTPS on this host |
| Return / Cancel / Webhook URL | https://getfit.adnys.com/adnys/success.php … | Defaults when not sent in the request |
| Currency | AED | USD needs a separate gateway account (not active yet) |
4. Sandbox & test keys
Payments made with a sandbox key go through a simulated card page on pay.adnys.com where you choose Approve, Decline or Cancel. No gateway is called and no money moves — even while ADNYS Pay is live. Statuses, webhooks and receipts work exactly like real payments, and sandbox payments never count as income.
- API base
https://pay.adnys.com/api/v1- Product
demo- API key
pk_sandbox_dd7f59093d26f0662d1bcec9- API secret
sk_sandbox_be3bdaa6e1b2c7bfb79dccd9030ca3e3279b301d99537512
Shared by everyone, rate-limited, and limited to pay.adnys.com return pages — it cannot send webhooks to your app. Demo payments are deleted after 7 days. For your own app, ask for its own sandbox key.
| On the simulated card page | Result | Webhook |
|---|---|---|
| Approve payment | paid | payment.paid |
| Decline — insufficient funds | failed with a bank reason | payment.failed |
| Cancel and go back | cancelled, customer can retry | — |
5. Try it now
B. Call the API from this page
Signs a real POST /payments/create request with the demo key in your browser, sends it, and shows the response. The same request as a curl command appears below.
Signed request
Response
Same request with curl valid for 5 minutes · nonce works once
6. PHP apps: the adnys app kit
The same folder works in every PHP app. You edit two files; the kit does signing, redirects, verification and webhooks.
your-app/public_html/adnys/
├── config.php ← EDIT: keys, product, site address
├── hooks.php ← EDIT: connect your orders table
├── pay.php ← pay button target
├── success.php ← return page (verifies with the API)
├── cancel.php ← cancelled / failed
├── webhook.php ← signed notifications
├── payment.php ← API client (don't edit)
├── _init.php ← loader (don't edit)
└── .htaccess ← blocks config from the web
- Download the kit and upload the
adnysfolder to your app'spublic_html. - config.php — paste the key, secret and webhook secret (sandbox first), product code and site address.
- hooks.php —
adnys_get_order()returns the order from your DB;adnys_mark_paid()activates it (idempotent); alsoadnys_mark_failed(),adnys_mark_refunded(). - Pay button:
<a href="/adnys/pay.php?order_id=GF-2026-00125">Pay securely with ADNYS Pay</a> - Check
https://yourapp.adnys.com/adnys/config.phpshows 403 Forbidden.
7. API reference
Base URL https://pay.adnys.com/api/v1 · JSON in and out · server-to-server only (never from a browser or mobile app in production).
Authentication — every request
| Header | Value |
|---|---|
X-ADNYS-Key | your API key |
X-ADNYS-Timestamp | Unix seconds — within 5 minutes of server time |
X-ADNYS-Nonce | random 16–64 chars [A-Za-z0-9_-], new for every request |
X-ADNYS-Signature | hex HMAC-SHA256(secret, timestamp + "\n" + nonce + "\n" + METHOD + "\n" + path + "\n" + body) |
Idempotency-Key | optional, 8–100 chars — same key returns the same payment |
path excludes the query string (sign /api/v1/payments/ADP-… even when calling ?refresh=1). body is the exact raw JSON sent, or empty for GET.
<?php
// adnys/pay.php in the app kit does exactly this
require __DIR__ . '/payment.php';
$pay = new AdnysPay('https://pay.adnys.com', 'pk_…', 'sk_…', 'whsec_…');
$order = load_order_from_your_db($_GET['order_id']); // amount from YOUR database
$r = $pay->createPayment([
'product' => 'getfit',
'order_id' => $order['order_no'],
'amount' => $order['amount'],
'currency' => 'AED',
'description' => 'GetFIT Monthly Subscription',
'customer' => ['name' => $order['name'], 'email' => $order['email'], 'phone' => $order['phone']],
'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',
]);
header('Location: ' . $r['payment_url'], true, 303);const crypto = require('crypto');
async function adnysRequest(method, path, bodyObj, key, secret) {
const body = bodyObj ? JSON.stringify(bodyObj) : '';
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}\n${path}\n${body}`).digest('hex');
const res = await fetch('https://pay.adnys.com' + path, {
method,
headers: { 'X-ADNYS-Key': key, 'X-ADNYS-Timestamp': ts, 'X-ADNYS-Nonce': nonce,
'X-ADNYS-Signature': sig, 'Content-Type': 'application/json' },
body: body || undefined,
});
return res.json();
}
// Create a payment, then redirect the customer to r.payment_url
const r = await adnysRequest('POST', '/api/v1/payments/create', {
order_id: 'GF-2026-00125', amount: 149.00, currency: 'AED',
description: 'GetFIT Monthly Subscription',
customer: { name: 'Aisha Rahman', email: 'aisha@example.com' },
}, process.env.ADNYS_PAY_KEY, process.env.ADNYS_PAY_SECRET);import hmac, hashlib, json, os, secrets, time, requests
def adnys_request(method, path, body_obj=None):
body = json.dumps(body_obj, separators=(',', ':')) if body_obj else ''
ts, nonce = str(int(time.time())), secrets.token_hex(16)
msg = f"{ts}\n{nonce}\n{method}\n{path}\n{body}".encode()
sig = hmac.new(os.environ['ADNYS_PAY_SECRET'].encode(), msg, hashlib.sha256).hexdigest()
headers = {'X-ADNYS-Key': os.environ['ADNYS_PAY_KEY'], 'X-ADNYS-Timestamp': ts,
'X-ADNYS-Nonce': nonce, 'X-ADNYS-Signature': sig, 'Content-Type': 'application/json'}
return requests.request(method, 'https://pay.adnys.com' + path, headers=headers, data=body or None).json()
r = adnys_request('POST', '/api/v1/payments/create', {
'order_id': 'GF-2026-00125', 'amount': 149.00, 'currency': 'AED',
'description': 'GetFIT Monthly Subscription',
'customer': {'name': 'Aisha Rahman', 'email': 'aisha@example.com'}})
# redirect the customer to r['payment_url']POST /payments/create
| Field | Rules |
|---|---|
order_id required | Your order number, max 100 chars |
amount required | > 0, max 2 decimals — from your database |
currency required | Enabled for your app (currently AED) |
product | If sent, must match the key's product |
description | Max 255 chars — shown on checkout and receipt |
customer | {name, email, phone} — email gets the receipt (live only) |
return_url, cancel_url, webhook_url | HTTPS on your allowed host; default to the app's saved URLs |
metadata | Up to 20 keys, stored with the payment |
// 201 Created (200 if an open payment is reused)
{
"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",
"sandbox": false
}
- Redirect the customer to
payment_url(HTTP 303). It expires after 60 minutes. - Same
order_id+ amount still open → the same payment comes back (double clicks are safe). - Order already paid →
409 order_already_paidwith itspayment_id: verify it and treat as paid. - Amount changed? Use a new
order_id. - Sandbox and live payments are kept apart — the same order number can be used in both.
GET /payments/{payment_id} add ?refresh=1 to re-check with the gateway
{
"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_…",
"customer": { "name": "…", "email": "…", "phone": "…" },
"paid_at": "2026-10-27T09:16:42Z",
"sandbox": false
}
statusispaid(orpartially_refunded)order_id= your orderamount= your database amountcurrency= your currency
GET /payments?order_id=GF-2026-00125 — all payments for one of your orders (latest first). Sign the path /api/v1/payments.
Errors
{ "success": false, "error": { "code": "validation_error", "field": "amount", "message": "amount must be a positive number" } }
| HTTP | code | What to do |
|---|---|---|
| 400 | invalid_json, bad_idempotency_key | Fix the request |
| 401 | unauthorized | Wrong key/secret, bad signature, or server clock off by > 5 min |
| 403 | unauthorized | Product disabled in ADNYS Pay |
| 404 | not_found | Not your app's payment (or sandbox vs live mismatch) |
| 409 | order_already_paid | Verify and mark paid — don't charge again |
| 409 | idempotency_conflict / replay | Same key with different data, or a reused nonce |
| 422 | validation_error, no_payment_channel | See field; currency not active |
| 429 | rate_limited | Public demo busy — wait, or use your own sandbox key |
| 500 | server_error | Retry later; show "Payment unavailable, try again" |
8. Webhooks
ADNYS Pay POSTs to your webhook_url when a payment changes. This is the reliable path — it works even if the customer closes the browser.
| Event | When |
|---|---|
payment.paid | Confirmed by the gateway |
payment.failed | Declined / failed |
payment.refunded | Full or partial refund issued in the admin |
- Read the raw body.
- Header
X-ADNYS-Signature: t=…,v1=… - Reject if
|now − t| > 300seconds. v1must equal hexHMAC-SHA256(webhook_secret, t + "." + rawBody)(constant-time compare).- For
payment.paid, re-check withGET /payments/{id}before activating. - Reply
2xxwithin 15 s. Otherwise retried after 1 m, 5 m, 15 m, 1 h, 3 h, 6 h, 12 h, 24 h.
POST /adnys/webhook.php
X-ADNYS-Event: payment.paid
X-ADNYS-Signature: t=1761556602,v1=5f2c…
{
"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"
}
<?php
// Verify a webhook from ADNYS Pay (the app kit's webhook.php does this for you)
$raw = file_get_contents('php://input'); // raw body, before json_decode
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_ADNYS_SIGNATURE'] ?? ''), $sig); // t=…, v1=…
$expected = hash_hmac('sha256', $sig['t'] . '.' . $raw, WEBHOOK_SECRET);
if (abs(time() - (int) $sig['t']) > 300 || !hash_equals($expected, (string) $sig['v1'])) {
http_response_code(400); exit('invalid signature');
}
$evt = json_decode($raw, true);
if ($evt['event'] === 'payment.paid') {
// Re-check with GET /api/v1/payments/{id} against YOUR order amount, then activate (idempotent)
}
http_response_code(200); echo 'ok'; 9. Pages your app needs
Order / pay page
- Shows item, amount and order number from your DB
- One button: "Pay securely with ADNYS Pay" → your server route
- Optional: "You'll pay on pay.adnys.com, the secure payment portal of ADNYS FZE."
- Already paid → show "Paid", no button
Success page — return_url
- Gets
?payment_id=…&order_id=…— hints only - Verify with the API, then show "Payment successful"
- Not confirmed yet → "Confirming… please don't pay again" + Check again
- Never activate from the redirect alone
Cancel page — cancel_url
- "Payment not completed — you have not been charged"
- Try again button back to the pay page
- Keep the order pending
- Show a support contact
Webhook endpoint — webhook_url
- Public HTTPS,
POSTonly - No login, no CSRF check, no redirects
- Verify signature → update order →
200 - Safe to receive the same event twice
Minimum orders table
| Column | Purpose |
|---|---|
order_no (unique) | Sent as order_id |
amount, currency | The price — the only source of truth |
status | pending → paid / failed / refunded |
adnys_payment_id, paid_at | For support and receipts |
Already handled by ADNYS Pay — don't rebuild
- Branded checkout with product, amount, order number and payment-partner logos
- Gateway's secure card page — ADNYS never sees card data
- Bank decline reasons and retry
- Result page, printable receipt and receipt email
- Refunds (by ADNYS finance), revenue, reconciliation and exports
10. Payment statuses
| status | Meaning | Your order |
|---|---|---|
| created | Created, customer hasn't chosen a method | pending |
| pending / processing | On the payment page / being confirmed | pending |
| paid | Confirmed by the gateway server-to-server | paid → activate |
| failed | Declined by the bank — customer can retry | pending |
| cancelled | Customer cancelled | pending |
| expired | Link unused for 60 minutes | pending — create a new payment |
| partially_refunded | Part returned | still paid |
| refunded | Fully refunded | refunded → remove access |
A failed, cancelled or expired payment can still become paid if the gateway confirms a genuine late success — always follow the webhook.
11. Test & go-live checklists
Test with your sandbox key
- Pay button opens ADNYS Pay with the right product, amount, order
- Approve → order paid in your app
- Close the browser after Approve → still paid (webhook)
- Double-click Pay → only one payment
- Decline → cancel/failed page, order pending, retry works
- Cancel → no charge, order pending
- Changing the amount in the URL has no effect
- Wrong webhook signature → 400
- Same webhook twice → activated once
/adnys/config.php→ 403 Forbidden
Go live
- All sandbox tests pass
- Swap in the live key and secret (server-side only)
- Allowed host and URLs are your production ones
- One AED 1.00 live payment → paid in your app and in the admin; finance refunds it
- Refund policy linked: adnys.com refund policy
- Support contact on pay, success and cancel pages
12. Security rules
- Keys and secrets live on the server only — never in Git, JavaScript or mobile apps.
- The amount always comes from your database.
- Activate only after a server-to-server check (API or verified webhook).
- Verify every webhook signature and timestamp with a constant-time compare.
- Make "mark paid" idempotent.
- HTTPS everywhere; keep the server clock synced (signatures expire in 5 minutes).
- Log the
payment_idwith your order; never log secrets. - Key leaked? Ask the admin to rotate it immediately.
13. Support
ADNYS PAY | ADNYS FZE · SRTIP, Sharjah, UAE · info@adnys.com · +971 56 116 6349
Always include the payment ID (ADP-…) and your order ID. Service status: /api/v1/health