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
`singleUse`	boolean	❌	`true`	If true, the link can only be used once
`selectedDate`	string	❌	-	Expiry date in ISO 8601 format
`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`	Send SMS notifications
`callback_url`	string	❌	-	Callback URL for payment updates
`metadata`	object	❌	-	Custom data for tracking

Request Example

{
  "amount": 299.99,
  "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": true,
  "callback_url": "https://mystore.com/webhook/payment-complete"
}

Response Example

Success Response (200):
{
  "payment_link_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://pay.sa.amwal.tech/payment-link/550e8400-e29b-41d4-a716-446655440000"
}

Error Response (400)
{
  "error": "Validation Error",
  "error_code": "INVALID_AMOUNT",
  "message": "Amount must be greater than zero",
  "details": {
    "amount": ["This field must be a positive number"]
  }
}

Best Practices

Set longer expiry times for customer convenience.
Provide detailed descriptions and customer information.
Enable email/SMS notifications.
Use single-use links for invoices and orders.
Collect customer addresses for shipping when necessary.