AmwalPay supports Subscription and Recurring Payments for WooCommerce merchants using the WooCommerce Subscriptions plugin.
Customers can make an initial payment for a subscription and, after saving their card, subsequent subscription renewal payments can be processed automatically using the customer’s Customer ID and Customer Token ID through the Execute / PayByToken API.
Who Can Use Subscription / Recurring Payments? #
Any WooCommerce merchant can use AmwalPay Subscription / Recurring Payments if the following requirements are met:
- WordPress is installed and configured.
- WooCommerce is installed and active.
- The WooCommerce Subscriptions plugin is installed and active.
- The AmwalPay WooCommerce payment gateway is installed and configured.
- The merchant’s AmwalPay account has the Execute / PayByToken API enabled.
- The customer enables the Save Card option during the initial payment.
API Enablement Requirement #
Before using Subscription or Recurring Payments, the Execute / PayByToken API must be enabled for your merchant account.
Please contact the AmwalPay Support Team to request API enablement:
Email: support@amwal-pay.com
Important: Recurring payments cannot be processed until the Execute / PayByToken API is enabled for your merchant account.
How Subscription Payments Work #
AmwalPay Subscription / Recurring Payments use the customer’s saved card to process future renewal payments.
For recurring payments to work, the customer must enable the “Save Card” option during the initial payment.
When the initial payment is successfully completed with the Save Card option enabled, AmwalPay creates/saves the customer’s:
- Customer ID
- Customer Token ID
These values are then used for subsequent recurring payments.
The customer does not need to enter their card details again for each renewal payment.
Subscription Payment Flow #
The overall flow is:
- The customer selects a subscription product.
- The customer proceeds to the WooCommerce checkout.
- The customer enters their card details.
- The customer enables the Save Card option.
- AmwalPay processes the initial payment.
- After a successful payment, the customer’s Customer ID and Customer Token ID are obtained.
- The WooCommerce gateway stores/associates these values with the customer/subscription.
- WooCommerce Subscriptions creates the subscription and calculates the next renewal date.
- When the renewal payment becomes due, the saved Customer ID and Customer Token ID are used.
- AmwalPay processes the renewal through the Execute / PayByToken API.
- If the payment is successful, the subscription remains active and the next renewal date is scheduled.
- The process continues until the subscription is cancelled, expires, or reaches its configured billing-cycle limit.
Initial Payment Flow #
The initial payment is the payment where the customer enters their card details and saves the card for future recurring payments.
Customer selects Subscription Product
↓
WooCommerce Checkout
↓
Enter Card Details
↓
Enable "Save Card"
↓
Initial Payment
↓
AmwalPay Payment
↓
Payment Successful
↓
Customer ID Created
+
Customer Token ID Created
↓
IDs Associated with Customer
↓
Subscription Activated
Important: The customer must enable Save Card during the initial payment. If the customer does not save the card, the required Customer ID and Customer Token ID may not be available for future recurring payments.
Recurring Payment Flow #
When the subscription reaches its next renewal date, WooCommerce Subscriptions initiates the renewal payment.
The AmwalPay gateway retrieves the saved Customer ID and Customer Token ID and uses them to process the payment through the Execute / PayByToken API.
Subscription Renewal Due
↓
WooCommerce Subscriptions
↓
AmwalPay WooCommerce Gateway
↓
Saved Customer ID
+
Saved Customer Token ID
↓
Execute / PayByToken API
↓
AmwalPay Payment Processing
↓
┌────┴────┐
↓ ↓
Success Failure
↓ ↓
Renewal Renewal
Completed Failed
↓ ↓
Subscription WooCommerce
Continues Failure Handling
Customer ID and Customer Token ID #
The following values are required to process recurring payments:
| Value | Description |
|---|---|
| Customer ID | Identifies the customer stored in AmwalPay |
| Customer Token ID | Identifies the customer’s saved card/payment token |
| Execute / PayByToken API | API used to process the recurring payment using the saved customer/token information |
The values are obtained as part of the card-saving process during the customer’s initial payment.
For subsequent renewals, the gateway uses the saved values instead of asking the customer to enter their card details again.
Prerequisites #
Before creating subscription products, make sure the following requirements are available:
| Requirement | Description |
|---|---|
| WordPress | A working WordPress installation |
| WooCommerce | Installed and activated |
| WooCommerce Subscriptions | Installed and activated |
| AmwalPay Gateway | Installed and configured |
| AmwalPay Merchant Account | Active merchant account |
| Execute / PayByToken API | Enabled by AmwalPay Support |
| Save Card | Enabled by the customer during the initial payment |
How to Create Subscription Products on WooCommerce #
You can create Simple Subscription or Variable Subscription products using the WooCommerce product management interface.
1. Create a New Product #
From the WordPress admin panel, go to:
Products → Add New
Enter the product name, description, images, and other standard WooCommerce product information.
2. Select the Subscription Product Type #
In the Product data section, select the appropriate subscription product type:
- Simple Subscription
- Variable Subscription
The available options depend on your WooCommerce Subscriptions configuration.
Simple Subscription #
A Simple Subscription has one subscription price and one billing schedule.
The following fields are required:
Subscription Price #
Enter the amount that the customer will be charged for each billing period.
Example:
Subscription Price: 10 OMR
Billing Frequency #
Select how often the customer should be charged.
AmwalPay supports the following billing frequencies:
| Frequency | Billing Interval |
|---|---|
| Weekly | Every 1 week |
| Monthly | Every 1 month |
| Two Months | Every 2 months |
| Quarterly | Every 3 months |
| Half Annual | Every 6 months |
Select a WooCommerce billing interval that corresponds to one of the frequencies supported by the AmwalPay integration.
Optional Subscription Settings #
WooCommerce Subscriptions provides additional options for controlling the subscription lifecycle.
Stop Renewing After #
Use Stop Renewing After to specify the number of billing cycles after which the subscription should automatically stop renewing.
For example:
Subscription Price: 10 OMR
Frequency: Monthly
Stop Renewing After: 12
In this example, the subscription will renew monthly for a maximum of 12 billing cycles.
Free Trial Period #
A Free Trial Period allows a customer to start the subscription without an immediate subscription charge.
For example:
Subscription Price: 10 OMR
Frequency: Monthly
Free Trial: 14 days
The customer receives a 14-day free trial, and the first subscription payment is scheduled after the trial period ends.
The availability and behavior of trial periods are controlled by WooCommerce Subscriptions.
Upfront Amount / Sign-Up Fee #
An Upfront Amount / Sign-Up Fee is a one-time amount charged when the customer initially subscribes.
For example:
Subscription Price: 10 OMR
Frequency: Monthly
Sign-Up Fee: 5 OMR
The applicable initial amount is charged when the customer subscribes. Subsequent renewal payments use the configured subscription price.
Variable Subscription Products #
A Variable Subscription allows merchants to offer multiple subscription options within the same product.
For example:
| Variation | Price | Frequency |
|---|---|---|
| Basic | 5 OMR | Monthly |
| Standard | 10 OMR | Monthly |
| Premium | 25 OMR | Monthly |
Customers can select the subscription variation that best suits their requirements.
Each variation can have its own subscription price and billing configuration.
Customer Checkout #
When a customer purchases a subscription product, the checkout process is as follows.
Step 1 — Select Subscription #
The customer selects a subscription product and adds it to the cart.
Step 2 — Enter Payment Details #
At checkout, the customer selects AmwalPay and enters their card details.
Step 3 — Enable Save Card #
The customer must enable the Save Card option.
This step is required because the saved payment information is used to create the Customer ID and Customer Token ID required for future recurring payments.
Step 4 — Complete Initial Payment #
The customer completes the initial payment through AmwalPay.
Step 5 — Customer ID and Customer Token ID #
After a successful payment with Save Card enabled, the required customer/token information is obtained:
Customer ID
Customer Token ID
These values are associated with the WooCommerce customer/subscription for future renewal payments.
Step 6 — Subscription Activation #
WooCommerce Subscriptions creates the subscription and calculates the next renewal date according to the configured billing frequency.
Recurring Renewal #
When the next renewal date is reached, WooCommerce Subscriptions initiates the renewal process.
The AmwalPay gateway uses the previously saved:
- Customer ID
- Customer Token ID
The renewal payment is then processed using the Execute / PayByToken API.
The customer does not need to enter their card details again.
Successful Renewal #
If the recurring payment is successful:
- AmwalPay processes the payment using the saved Customer ID and Customer Token ID.
- AmwalPay returns a successful payment response.
- WooCommerce records the renewal payment.
- The subscription remains active.
- WooCommerce calculates the next renewal date.
Failed Renewal #
If the recurring payment fails:
- AmwalPay returns a failed payment response.
- WooCommerce records the renewal failure.
- WooCommerce Subscriptions handles the configured renewal failure/retry process.
- Depending on the subscription configuration, the subscription may be retried, suspended, or cancelled.
The exact behavior for failed renewal payments depends on the WooCommerce Subscriptions configuration.
Supported Billing Frequencies #
AmwalPay supports the following subscription billing frequencies:
- Weekly
- Monthly
- Two Months
- Quarterly
- Half Annual
Make sure that the billing interval selected for the WooCommerce subscription corresponds to a supported AmwalPay frequency.
Subscription Lifecycle #
A typical AmwalPay subscription lifecycle is:
Customer
│
▼
Select Subscription Product
│
▼
WooCommerce Checkout
│
▼
Enter Card Details
│
▼
Enable "Save Card"
│
▼
Initial Payment
│
▼
Payment Successful
│
▼
Customer ID + Customer Token ID
│
▼
Subscription Active
│
▼
Renewal Date
│
▼
Execute / PayByToken
│
├───────────────┐
│ │
Success Failure
│ │
▼ ▼
Renewal Renewal Failure
Completed │
│ ▼
▼ Retry / Suspend /
Next Renewal Cancel
Cancellation #
A subscription can be cancelled according to the WooCommerce Subscriptions configuration and the store’s subscription management process.
When a subscription is cancelled, future renewal payments should no longer be processed for that subscription.
The integration should ensure that the subscription status is correctly maintained so that no further renewal payment is initiated for a cancelled subscription.
