وثائق المطورين
الربط المدمج S2S
اشحن البطاقات مباشرة من خادمك مع دعم كامل لتحدي 3-D Secure.
تتيح واجهة SALE من خادم إلى خادم شحن البطاقات من نظامك الخلفي مع إعادة توجيه 3DS. تتطلب هذه الطريقة التزاماً أعلى بمتطلبات PCI لأن بيانات البطاقة تمرّ عبر أنظمتك.
POST https://app-api.nmapay.com/api/v1/payment-gateway/s2s/saleمعاملات الطلب
| Field | Type | Required | Description |
|---|---|---|---|
| orderId | String | Yes | Unique identifier per transaction |
| amount | Number | Yes | Transaction amount |
| currency | String | Yes | ISO currency code, e.g. SAR |
| paymentMethod | String | Yes | Must be card |
| auth | String | Yes | Y for authorisation-only, otherwise N |
| card | Object | Yes | cardNumber, cardHolder, cardExpiryMonth, cardExpiryYear, cardCvv |
| customer | Object | Yes | name, email, phone |
| successUrl | String | Yes | Redirect after successful 3DS |
| failureUrl | String | Yes | Redirect after failed 3DS |
| hash | String | Yes | Request hash — see Authentication |
curl --location 'https://app-api.nmapay.com/api/v1/payment-gateway/s2s/sale' \
--header 'X-API-KEY: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"orderId": "12345",
"amount": 100,
"currency": "SAR",
"paymentMethod": "card",
"auth": "N",
"recurringInit": "N",
"customer": { "name": "John Doe", "email": "john@example.com", "phone": "+9665xxxxxxx" },
"card": {
"cardNumber": "5123450000000008",
"cardHolder": "JOHN DOE",
"cardExpiryMonth": "01",
"cardExpiryYear": "2039",
"cardCvv": "100"
},
"successUrl": "https://your-site.com/success",
"failureUrl": "https://your-site.com/failure",
"hash": "<GENERATED_HASH>"
}'معالجة تحدي 3DS
عند وجود الحقل html في الاستجابة، فهذا يعني أن المصادقة الإضافية مطلوبة والعملية في حالة Pending. اعرض محتوى html كما هو دون تعديل: داخل iframe في الويب أو WebView في التطبيق.
لا تُعدّل محتوى الـ HTML. سيُعاد توجيه العميل تلقائياً إلى successUrl أو failureUrl بعد إتمام المصادقة.
عمليات ما بعد البيع
| Operation | Endpoint | Purpose |
|---|---|---|
| Capture | /payment-gateway/s2s/capture | Capture a previously authorised amount |
| Void | /payment-gateway/s2s/void | Cancel an authorisation before settlement |
| Refund | /payment-gateway/s2s/refund | Return funds fully or partially |
| Recurring | /payment-gateway/s2s/recurring | Charge a stored, tokenised card |
| Status | /payment-gateway/status | Query the current transaction status |