Create Installment Link

📌 Installment Link Integration

Easily generate an invoice link using the Create Installment Link endpoint. Share this link through SMS, email, or web redirects.

This approach is perfect for businesses without an online store that still want to offer payment or installment options.

Installment Link Flow: Create a payment link using the "Create Installment Link" endpoint. Distribute it to customers via SMS, email, messaging apps, or embed it on your website. After payment, your backend will receive a notification through a callback.
Custom Integration Flow: Utilize Amwal’s endpoints to integrate Amwal as a payment option within your platform. Customers are redirected to Amwal’s installment link and then returned to your portal for order confirmation or failure handling.

📘
API Reference
For detailed request/response schemas and interactive testing, visit Create Installment Link.

🔗 API Endpoint

POST /payment_links/{store_id}/create

Path Parameters

Parameter	Type	Required	Description
`store_id`	string	✅	Your unique store identifier from the Merchant Portal

Request Parameters

Parameter	Type	Required	Default	Description
`amount`	number	✅		Payment amount in your store's currency
`title`	string	❌		Title of the payment link visible to customers
`description`	string	❌		Detailed description of the payment
`order_id`	string	x		External identifier like the e-commerce order ID.
`selectedDate`	string	❌		Expiry date in ISO 8601 format (ex: 2027-12-27T07:09:00.000Z)
`singleUse`	boolean	❌	`true`	If true, the link can only be used once
`client_phone_number`	string	❌		Customer's phone number in international format
`client_email`	string	❌		Customer's email address
`client_first_name`	string	❌		Customer's first name
`client_last_name`	string	❌		Customer's last name
`address_required`	boolean	❌	`false`	Require customer address
`language`	string	❌	`"ar"`	Language of the payment page: "en" or "ar"
`send_sms`	boolean	❌	`true`	The default value is true. Keep the default for Offline integration and set it to false for Online integration.
`callback_url`	string	❌		URL where Amwal redirects the customer after the payment flow. The redirect includes the transaction ID and transaction status.
`metadata`	object	❌		Custom data for tracking

Request Example

🚧
Single Use
When singleUse is set to true, the payment link remains valid until it either expires or a payment attempt is completed (whether successful or failed).
When singleUse is false, the customer can attempt payment multiple times using the same link until a successful transaction occurs.

🚧
Send SMS
The default value is true.
Keep the default for Offline integration and set it to false for Online integration.

🚧
Callback URL
Set callback_url to a page or server endpoint in your system, such as https://mystore.com/amwal/callback. After the customer completes or exits the payment flow, Amwal redirects them to this URL and sends the transaction ID and transaction status.

{
  "amount": 299.99,
  "order_id": "ref #5643",
  "title": "Order #12345 - Premium Headphones",
  "description": "Wireless Noise-Cancelling Headphones - Black",
  "singleUse": true,
  "selectedDate": "2024-12-31T23:59:59Z",
  "client_phone_number": "+966501234567",
  "client_email": "[email protected]",
  "client_first_name": "Ahmed",
  "language": "en",
  "send_sms": false,
  "callback_url": "https://mystore.com/amwal/callback"
}

Success Response (200):

{
  "order_id": "ref #5643",
  "payment_link_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://pay.sa.amwal.tech/payment-link/550e8400-e29b-41d4-a716-446655440000",
  "environment": "SANDBOX" // or "PRODUCTION"
}

Error Response (400)

{"error":"error message string"}

Handle the callback redirect

Read the transaction ID and transaction status from the redirect.
Send the transaction ID to the Get Transaction Details API.
Use the returned transaction details to update the order status in your system.
Show the customer the appropriate confirmation or failure page.

📘
Validate the transaction before fulfillment
Treat the redirect as a customer return flow. Retrieve the full transaction details with the transaction ID before you fulfill the order or mark it as paid.

Handle missing or invalid callback data

If the transaction ID or transaction status is missing, do not update the order. Keep the order pending and direct the customer to retry or contact support.
If the Get Transaction Details API request fails, keep the order pending and retry the lookup from your server.
Do not expose your Amwal credentials in the callback page or browser code.