SMS Integration with EdfaPay

Integrate SMS notifications with EdfaPay to send OTP codes, transaction confirmations, and merchant alerts to your users.

⚠️

EdfaPay only supports SMS requests compatible with the Taqnyat SMS provider. Requests from other providers with different formats will fail unless adapted to Taqnyat's API.

Overview

EdfaPay's SMS module supports the following notification types:

• OTP notifications — Send one-time passwords for payment verification
• Transaction confirmations — Notify customers of completed transactions
• Merchant notifications — Alert merchants about payment activity

The SMS delivery flow is tightly coupled with the Taqnyat API format to ensure reliability.

Supported SMS Requests

Only requests matching Taqnyat's API structure are supported. Requests from other providers (such as Madar) that use different HTTP methods, parameter names, or authentication methods will fail.

Taqnyat API Reference: Postman Collection – Taqnyat SMS API

How to Send SMS

Endpoint

POST https://api.taqnyat.sa/v1/messages

Headers

Request Body

{
  "sender": "YOUR_SENDER_ID",
  "recipients": ["9665XXXXXXXX"],
  "body": "Your OTP is 123456. This message has been sent by EdfaPay."
}

Successful Response

{
  "status": "Success",
  "message": null,
  "data": {
    "message": {
      "id": "0b1a3cfc-0688-4f22-8374-90e6d220ae62",
      "status": "pending"
    }
  }
}

Alerts & Best Practices

🚫

Taqnyat-only support. Using a provider with different HTTP methods or parameters will result in failed SMS delivery.

⚠️

POST method is mandatory. Sending requests as GET will return 405 – Method Not Allowed.

⚠️

JSON body required. The request body must include the sender, recipients, and body fields. Query parameters in the URL are not supported.

🔑

Valid token required. Ensure your SMS_BEARER_TOKEN is valid and active. Invalid tokens will cause delivery failure.

💡

White-label or custom providers. If you use a white-label dashboard or a different SMS provider, a wrapper or adapter may be required to convert requests to Taqnyat format. Contact EdfaPay support before attempting non-Taqnyat providers.

🧪

Test before going live. Always test your SMS flow in the sandbox environment to confirm delivery before switching to production.

Recommendations for New Integrations

• Always include your merchant ID, order ID, and phone number when triggering an SMS.
• To use a different SMS provider, share their API documentation with EdfaPay for review.
• Do not assume that any SMS API using GET parameters or different headers will work without adaptation.

Middleware for Non-Taqnyat SMS Providers

If your platform integrates with an SMS provider other than Taqnyat (such as Madar), requests from EdfaPay will fail by default because the payment gateway (PG) only supports Taqnyat's API format. To ensure delivery, implement a middleware (adapter) layer on your side that sits between EdfaPay and your SMS provider.

⚠️

The EdfaPay PG sends SMS requests in POST JSON format for Taqnyat. If your provider uses a different format (e.g., Madar), your middleware must transform the request accordingly.

How the Middleware Works

1. Receive the request from EdfaPay PG

   • HTTP Method: POST
   • Header: Authorization: Bearer <token>
   • Body (JSON): sender, recipients, body

2. Transform the request for your SMS provider

   • Convert the HTTP method if required (e.g., GET → POST for Madar)
   • Build a JSON body according to your provider's requirements
   • Include provider-required headers (Authorization, Content-Type)

3. Send the request to your SMS provider over HTTPS

4. Return status to the PG (optional) — your middleware can return delivery success/failure to EdfaPay for monitoring

Example Workflow

EdfaPay PG ──POST JSON + Auth──▶ Middleware
Middleware ──POST JSON + Auth──▶ SMS Provider (e.g., Madar)
SMS Provider ──delivers──▶ End User

Example: Middleware to Madar

Your middleware receives the EdfaPay PG request and transforms it into a POST request with JSON body for Madar.

curl -X POST 'https://api.madar.sa/sms/send' \
  --header 'Authorization: Bearer <provider_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "sender": "PartnerName",
    "recipients": ["966533340735"],
    "body": "Your OTP is 123456"
  }'

Common Middleware Errors

🔑

Never expose tokens in the URL. The EdfaPay PG sends the token in the Authorization header. Your middleware must also use headers (not query parameters) when forwarding to your SMS provider.

🧪

Test your middleware in sandbox first. Confirm end-to-end SMS delivery before switching to production. Log all provider responses in your middleware for debugging.

💡

Document provider-specific requirements. Record any differences in authentication, request format, or rate limits in your integration notes for transparency with EdfaPay support.

💡

Log all requests/responses with timestamps for easier debugging.