API Documentation

Base URL

https://dpay.ly/api

All API endpoints are prefixed with /api. All requests and responses use JSON. Include Content-Type: application/json and Accept: application/json headers with every request.

Authentication

All API requests require a Bearer token for authentication.

How to get your token: Sign in to the Dashboard, navigate to API Tokens, create a new token, and copy it immediately — it won't be shown again.

Include the token in the Authorization header of every request:

Authorization: Bearer YOUR_API_TOKEN

Example (cURL)

curl -X GET https://dpay.ly/api/auth/me \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Account Endpoints

GET /api/auth/me Get current user

Returns the authenticated user's profile, roles, and permissions.

Response

{
  "user": {
    "id": 1,
    "first_name": "Ahmed",
    "last_name": "Ali",
    "email": "ahmed@example.com"
  },
  "roles": ["merchant"],
  "permissions": ["payments.view", "payments.create", ...]
}

GET /api/auth/balance Get balance

{ "balance": 15000 }

POST /api/auth/logout Revoke all tokens

Revokes all API tokens for the authenticated user.

{ "message": "Logged out" }

Payment Sessions

Unified payment flow: Open a session → Customer verifies via OTP (or LightBox for Moamalat) → Payment confirmed.

POST /api/payment/sessions/open Create payment session

Requires authentication. Permission: payments.create

Request Body

Parameter	Type	Required	Description
`pay_method`	string	Required	Gateway: `edfali`, `masrefypay`, `yousrpay`, `saharapay`, `mobicash`, `moamalat`
`amount`	integer	Required	Amount in LYD (must be within min/max deposit limits)
`customer_mobile`	string	EDFali	Customer mobile number
`card_number`	string	Bank / MobiCash	Card number. Bank gateways: 7 digits (same bank) or 9 digits (cross-bank via OnePay). MobiCash: 7 digits.
`description`	string	No	Payment description (MobiCash)
`data`	object	No	Custom metadata attached to the session

Response

{
  "message": "Payment session created successfully",
  "session_id": 42,
  "status": "pending",
  "amount": 100,
  "fee": 2.5,
  "fee_amount": 2.5,
  "total": 102.5,
  "pay_method": "edfali",
  "expired_at": "2026-01-15T12:30:00.000000Z",
  "data": null,
  "payment_link": "/moamalat-pay/42"
}

POST /api/payment/sessions/verify Verify payment (OTP)

For OTP-based gateways (EDFali, MobiCash, MasrefyPay, YousrPay, SaharaPay). Moamalat payments are verified automatically by the LightBox UI.

Request Body

Parameter	Type	Required	Description
`session_id`	integer	Required	Payment session ID
`otp`	string	Required	OTP code received by customer

Success Response

{
  "message": "Payment verified successfully",
  "payment_id": 101,
  "status": "paid",
  "amount": 100,
  "pay_method": "edfali",
  "tx_id": "txn_abc123"
}

GET /api/payment/sessions/{id} Get session by ID

{
  "session_id": 42,
  "status": "paid",
  "amount": 100,
  "pay_method": "edfali",
  "expired_at": "2026-01-15T12:30:00.000000Z",
  "data": null
}

Payments

View and filter completed payment transactions.

GET /api/payments List payments (paginated)

Returns a paginated list of your completed payments. Permission: payments.view

POST /api/payments/filter Filter by date range

Parameter	Type	Required	Description
`from`	date	Required	Start date (YYYY-MM-DD)
`to`	date	Required	End date (YYYY-MM-DD)

Payment Methods

Retrieve available payment gateways and your merchant-specific configuration.

GET /api/pay-methods List all payment methods

Returns all payment methods with your merchant-specific fee, min_deposit, and max_deposit overrides applied.

[
  {
    "name": "EDFali",
    "active": true,
    "tag": "edfali",
    "fee": 2.5,
    "min_deposit": 1,
    "max_deposit": 5000
  },
  ...
]

Invoices

Create and manage payment invoices with shareable payment links.

GET /api/invoices List invoices

Paginated list. Optional query param: ?status=sent (draft, sent, paid, overdue, cancelled)

POST /api/invoices Create invoice

Parameter	Type	Required	Description
`customer_name`	string	No	Customer name (max 150)
`customer_email`	email	No	Customer email
`customer_phone`	string	No	Customer phone
`due_date`	date	No	Payment due date
`tax_rate`	number	No	Tax rate percentage (0-100)
`currency`	string	No	3-letter code (default: LYD)
`notes`	string	No	Invoice notes (max 2000)
`send`	boolean	No	Auto-send invoice (sets status to "sent")
`items`	array	Required	Line items array (min 1)
`items.*.description`	string	Required	Item description
`items.*.quantity`	number	Required	Quantity (min 0.01)
`items.*.unit_price`	integer	Required	Unit price in LYD

{
  "customer_name": "Ahmed Ali",
  "customer_email": "ahmed@example.com",
  "due_date": "2026-12-31",
  "send": true,
  "items": [
    { "description": "Web Development", "quantity": 1, "unit_price": 500 },
    { "description": "Hosting (monthly)", "quantity": 12, "unit_price": 25 }
  ]
}

Response (201)

{
  "message": "Invoice created successfully.",
  "invoice": { ... },
  "payment_url": "https://dpay.ly/invoice/abc-uuid-123"
}

GET /api/invoices/{id} Get invoice

Returns invoice with items and public payment URL.

PUT /api/invoices/{id} Update invoice

Update invoice details and items. Only works if the invoice has not been paid. Providing items replaces all existing items.

POST /api/invoices/{id}/send Send / publish invoice

Marks a draft invoice as "sent" and returns the payment URL. Only works on draft invoices with total > 0.

DELETE /api/invoices/{id} Cancel invoice

Cancels an invoice. Paid invoices cannot be cancelled.

EDFali SOAP-based Mobile Payment

Customer pays via mobile wallet with 4-digit OTP verification.

Flow

Open session with customer_mobile + amount
Customer receives 4-digit OTP via SMS
Verify session with the OTP

Error Codes

PW — Wrong PIN
Bal/BAL — Insufficient balance
ACC — Customer not found
Limit — Amount exceeds limits

Open

{
  "pay_method": "edfali",
  "amount": 100,
  "customer_mobile": "0912345678"
}

Verify

{
  "session_id": 1,
  "otp": "1234"
}

Bank Card Gateways

Direct bank card payments with OTP verification. Three gateways — one per bank.

MasrefyPay — Jumhouria Bank YousrPay — National Commercial Bank SaharaPay — Sahara Bank

Flow

Open session with card_number + amount
Customer receives OTP via SMS
Verify session with the OTP

Card Number Format

Same bank: 7 digits (e.g. 1234567)
Cross-bank (OnePay): 9 digits = 2-digit bank prefix + 7 digits (e.g. 331234567)

Each merchant configures their own userId, pin, and providerId in Pay Methods settings. Enable OnePay to accept cards from other banks.

Open (same-bank card)

{
  "pay_method": "masrefypay",
  "amount": 50,
  "card_number": "1234567"
}

Open (cross-bank via OnePay)

{
  "pay_method": "masrefypay",
  "amount": 50,
  "card_number": "331234567"
}

Verify

{
  "session_id": 2,
  "otp": "567890"
}

MobiCash Merchant API Key Payments

Card-based payment with Merchant API Key authentication and 5-minute session expiry.

Flow

Open session with card_number + amount
Customer receives OTP via SMS
Verify with OTP (uses payment_uuid internally)
Bank reference number returned on success

Details

Session Expiry: 300 seconds (5 minutes)
Currency: LYD
Test Card: 7279627

Open

{
  "pay_method": "mobicash",
  "amount": 10,
  "card_number": "7279627",
  "description": "Order #1234"
}

Verify

{
  "session_id": 3,
  "otp": "448481"
}

Moamalat Card Payments (LightBox + Webhook)

Full card payment with hosted LightBox UI and server-to-server webhook confirmation.

Flow

Open session with amount (returns payment_link)
Redirect customer to the payment link
Customer enters card details + OTP in LightBox UI
Payment is verified automatically (no API call needed)
Webhook confirms transaction server-to-server

Supported Methods

NUMO Cards
Visa / Mastercard
Mobile Wallets (Tahweel, mVisa)

Transaction Types

1 Sale
2 Refund
3 Void Sale
4 Void Refund

Open

{
  "pay_method": "moamalat",
  "amount": 200
}

Response

{
  "session_id": 4,
  "status": "pending",
  "amount": 200,
  "payment_link": "/moamalat-pay/4",
  ...
}

Merchant Webhooks

Receive real-time payment notifications at your configured webhook URL.

Configure your webhook_url in Pay Methods → Configure for each gateway.

Webhook Payload

When a payment is completed, a POST request is sent to your webhook URL with:

{
  "event": "payment.paid",
  "session_id": 42,
  "status": "paid",
  "amount": 100,
  "pay_method": "edfali",
  "tx_id": "txn_abc123",
  "system_reference": null,
  "network_reference": null,
  "paid_through": null,
  "payer_account": null,
  "data": { "order_id": "ORD-001" },
  "created_at": "2026-01-15T12:15:00+00:00",
  "paid_at": "2026-01-15T12:16:30+00:00"
}

Webhook delivery is fire-and-forget with 2 automatic retries (1-second delay). Ensure your endpoint responds with 2xx status within 10 seconds.

Error Handling

Standard HTTP status codes and consistent error response format.

Code	Meaning	Description
`200`	Success	Request completed successfully
`201`	Created	Resource created (invoices, sessions)
`400`	Bad Request	Invalid parameters or business logic error
`401`	Unauthorized	Missing or invalid Bearer token
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource does not exist
`422`	Validation Error	Request body failed validation
`500`	Server Error	Unexpected internal error

Error Response Format

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["The amount field is required."],
    "pay_method": ["The selected pay method is invalid."]
  }
}

Sandbox / Test Data

Use these credentials for testing in sandbox mode.

MasrefyPay Test Cards

Same bank: 1234567 (7 digits)
Cross-bank: 111234567 (prefix 11)

Jumhouria Bank · OTP: 111111

YousrPay Test Cards

Same bank: 1234567 (7 digits)
Cross-bank: 331234567 (prefix 33)

National Commercial Bank · OTP: 111111

SaharaPay Test Cards

Same bank: 1234567 (7 digits)
Cross-bank: 661234567 (prefix 66)

Sahara Bank · OTP: 111111

MobiCash Test

Test Card: 7279627 (7 digits)

OTP: 111111

Moamalat Test Cards

6395043835180860
6395043165725698

Expiry: 01/27 · OTP: 111111