وثائق المطورين

Hosted Checkout

أنشئ جلسة دفع ووجّه العميل إلى صفحة دفع آمنة مستضافة.

يتيح Hosted Checkout قبول المدفوعات دون التعامل مع بيانات البطاقة في أنظمتك. يُوجَّه العميل إلى صفحة دفع آمنة لإتمام العملية، مع معالجة 3-D Secure تلقائياً عند الحاجة.

1
١. إنشاء الجلسة
أرسل طلباً من خادمك لإنشاء جلسة دفع.
2
٢. تحويل العميل
وجّه العميل إلى redirectUrl المُعاد في الاستجابة.
3
٣. استلام النتيجة
استلم الحالة النهائية عبر إعادة التوجيه أو الويب هوك.

نقطة النهاية

POST https://app-api.nmapay.com/api/v1/payment-gateway/initiate

معاملات الطلب

Field	Type	Required	Description
orderId	String	Yes	Unique identifier for the order
currency	String	Yes	ISO 4217 currency code, e.g. SAR
amount	Decimal	Yes	Total amount to be charged
customerDetails	Object	Yes	name, email, phone (idNumber, idType, taxNumber optional)
address	Object	No	country, state, city, address, zip
recurringInit	String	No	Set to Y to initialise a recurring payment
auth	String	Yes	Y for authorisation-only, otherwise N
successUrl	String	Yes	Redirect target after successful 3DS authentication
failureUrl	String	Yes	Redirect target after failed 3DS authentication
issueDate	Date	No	Invoice issue date (YYYY-MM-DD), defaults to today
expireDate	Date	No	Invoice expiry, defaults to issueDate + 7 days

مثال الطلب

curl --location 'https://app-api.nmapay.com/api/v1/payment-gateway/initiate' \
--header 'X-API-KEY: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "orderId": "12345",
  "currency": "SAR",
  "amount": 100,
  "customerDetails": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+9665xxxxxxx"
  },
  "address": {
    "country": "SA",
    "state": "Riyadh",
    "city": "Riyadh",
    "address": "10 Olaya St, Floor 5"
  },
  "recurringInit": "N",
  "auth": "N",
  "successUrl": "https://your-site.com/success",
  "failureUrl": "https://your-site.com/failure"
}'

الاستجابة

{
  "code": 200,
  "message": "Success",
  "errorCode": null,
  "data": {
    "redirectUrl": "https://app.nmapay.com/pay/checkout?sessionId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

وجّه العميل إلى redirectUrl لإتمام الدفع، ثم اعتمد على الويب هوك لتأكيد الحالة النهائية.