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	❌		Callback URL for payment updates
`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.

{
  "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/webhook/payment-complete"
}

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"}