ADNYS Pay for developers · v3.2.0

Take payments in any ADNYS product, the safe way

Every ADNYS app — GetFIT, Beats, EduLogiTech and the next one — takes payments only through pay.adnys.com. This page has the rules, a step-by-step guide, the API, and a sandbox you can try right now with no real money.

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

  1. 1
    Create

    Your server calls POST /payments/create with the amount from your database and gets a payment_url.

  2. 2
    Checkout

    The customer is redirected to the ADNYS Pay checkout: product, order number, amount, partner logos.

  3. 3
    Pay

    They pay on the gateway's secure page (Tap). Card data never reaches ADNYS Pay or your app.

  4. 4
    Confirm

    ADNYS Pay confirms with the gateway server-to-server and cross-checks amount, currency and reference.

  5. 5
    Return

    The customer sees a receipt, then returns to your return_url?payment_id=…&order_id=….

  6. 6
    Verify & activate

    Your success page checks GET /payments/{id}; the signed payment.paid webhook arrives too. Either one activates the order — once.

3. Get started

A

Explore with the demo key

Use the public sandbox key below to call the API and open test checkouts today. Nothing to install.

Sandbox →
B

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 →
C

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)

ItemExampleNotes
Product codegetfitSent as product
Sandbox key + secretpk_sandbox_… / sk_sandbox_…Simulated payments only — for building & testing
Live key + secretpk_live_… / sk_live_…Real money. Server-side only; secret shown once
Webhook secretwhsec_…Verifies notifications from ADNYS Pay
Allowed hostgetfit.adnys.comAll URLs must be HTTPS on this host
Return / Cancel / Webhook URLhttps://getfit.adnys.com/adnys/success.php …Defaults when not sent in the request
CurrencyAEDUSD 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.

Public demo keySANDBOX ONLY
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 pageResultWebhook
Approve paymentpayment.paid
Decline — insufficient fundsfailed with a bank reasonpayment.failed
Cancel and go backcancelled, customer can retry—

5. Try it now

A. One-click test checkout

See exactly what your customers see: the ADNYS Pay checkout, the card step (simulated), the result page, the receipt — then the return to "your app".

Sandbox — no card needed, no money moves.

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.

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
  1. Download the kit and upload the adnys folder to your app's public_html.
  2. config.php — paste the key, secret and webhook secret (sandbox first), product code and site address.
  3. hooks.php — adnys_get_order() returns the order from your DB; adnys_mark_paid() activates it (idempotent); also adnys_mark_failed(), adnys_mark_refunded().
  4. Pay button: <a href="/adnys/pay.php?order_id=GF-2026-00125">Pay securely with ADNYS Pay</a>
  5. Check https://yourapp.adnys.com/adnys/config.php shows 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

HeaderValue
X-ADNYS-Keyyour API key
X-ADNYS-TimestampUnix seconds — within 5 minutes of server time
X-ADNYS-Noncerandom 16–64 chars [A-Za-z0-9_-], new for every request
X-ADNYS-Signaturehex HMAC-SHA256(secret, timestamp + "\n" + nonce + "\n" + METHOD + "\n" + path + "\n" + body)
Idempotency-Keyoptional, 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);

POST /payments/create

FieldRules
order_id requiredYour order number, max 100 chars
amount required> 0, max 2 decimals — from your database
currency requiredEnabled for your app (currently AED)
productIf sent, must match the key's product
descriptionMax 255 chars — shown on checkout and receipt
customer{name, email, phone} — email gets the receipt (live only)
return_url, cancel_url, webhook_urlHTTPS on your allowed host; default to the app's saved URLs
metadataUp 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_paid with its payment_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
}
Treat an order as paid only when all four match
  1. status is paid (or partially_refunded)
  2. order_id = your order
  3. amount = your database amount
  4. currency = 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" } }
HTTPcodeWhat to do
400invalid_json, bad_idempotency_keyFix the request
401unauthorizedWrong key/secret, bad signature, or server clock off by > 5 min
403unauthorizedProduct disabled in ADNYS Pay
404not_foundNot your app's payment (or sandbox vs live mismatch)
409order_already_paidVerify and mark paid — don't charge again
409idempotency_conflict / replaySame key with different data, or a reused nonce
422validation_error, no_payment_channelSee field; currency not active
429rate_limitedPublic demo busy — wait, or use your own sandbox key
500server_errorRetry 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.

EventWhen
payment.paidConfirmed by the gateway
payment.failedDeclined / failed
payment.refundedFull or partial refund issued in the admin
  1. Read the raw body.
  2. Header X-ADNYS-Signature: t=…,v1=…
  3. Reject if |now − t| > 300 seconds.
  4. v1 must equal hex HMAC-SHA256(webhook_secret, t + "." + rawBody) (constant-time compare).
  5. For payment.paid, re-check with GET /payments/{id} before activating.
  6. Reply 2xx within 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, POST only
  • No login, no CSRF check, no redirects
  • Verify signature → update order → 200
  • Safe to receive the same event twice

Minimum orders table

ColumnPurpose
order_no (unique)Sent as order_id
amount, currencyThe price — the only source of truth
statuspending → paid / failed / refunded
adnys_payment_id, paid_atFor 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

statusMeaningYour order
createdCreated, customer hasn't chosen a methodpending
pending / processingOn the payment page / being confirmedpending
Confirmed by the gateway server-to-serverpaid → activate
failedDeclined by the bank — customer can retrypending
cancelledCustomer cancelledpending
expiredLink unused for 60 minutespending — create a new payment
partially_refundedPart returnedstill paid
refundedFully refundedrefunded → 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

  1. Keys and secrets live on the server only — never in Git, JavaScript or mobile apps.
  2. The amount always comes from your database.
  3. Activate only after a server-to-server check (API or verified webhook).
  4. Verify every webhook signature and timestamp with a constant-time compare.
  5. Make "mark paid" idempotent.
  6. HTTPS everywhere; keep the server clock synced (signatures expire in 5 minutes).
  7. Log the payment_id with your order; never log secrets.
  8. 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