Getting Started

Overview

The Payment Sessions API allows you to create and manage payment sessions with role-based access control. A payment session represents a transaction that your customer can complete through various payment methods supported by Amwal.

Base URL

https://backend.sa.amwal.tech

Authentication

All requests require the secret API key in the Authorization header, this key can be found in the merchant dashboard under the integration tab :

Authorization: YOUR_API_KEY

Creating a Payment Session

Endpoint: POST /payment_links/{store_id}/create

Required Parameters:

• amount: Payment amount (numeric)
• phoneNumber: Customer phone number in international format

Optional Parameters:

• title: Payment title
• description: Payment description
• singleUse: Whether the link can be used once (default: true)
• selectedDate: Expiry date
• branch: Branch ID if applicable

Example Response:

{
  "payment_session_id": "274045cd-3604-4fcf-88b7-a22793c87506"
}

Listing Payment Sessions

Endpoint: POST /payment_links/{store_id}/

Use this endpoint to retrieve a paginated list of payment sessions. You can filter and sort the results using the following parameters:

• page: Page number (default: 1)
• page_size: Number of items per page (default: 10)
• search: Filter by title
• sort_by: Field to sort by (default: created_at)
• sort_order: Sort direction (asc/desc, default: desc)

Getting Payment Session Details

Endpoint: POST /payment_link/{payment_link_id}/details

Retrieve detailed information about a specific payment session using its ID.

Role-Based Access

The API implements role-based access control:

• ADMIN, OPERATION, OWNER, ACCOUNTING: View all links
• SUPERVISOR: View links for assigned branch
• CASHIER: View self-created links for their branch

Error Handling

The API returns standard HTTP status codes:

• 200: Success
• 400: Bad request (invalid input)
• 403: Forbidden (insufficient permissions)
• 404: Not found

Error responses include detailed information:

{
  "error": "Error message",
  "error_code": "INVALID_REQUEST",
  "details": {
    "field": "Error details for the specific field"
  }
}

What's Next

After integrating the Payment Sessions API:

1. Explore the full API reference
2. Test your integration thoroughly
3. Contact support at [email protected] if you need assistance