# AmwalPay Payment Gateway Integration

### Overview

The AmwalPay integration allows businesses to securely collect payments directly from WhatsApp, Web Chat, or other chatbot channels built using Rapidbott.\
This integration supports **payment link generation**, **transaction verification**, and **real-time payment status handling**.

Using this integration, businesses can:

* Generate payment links dynamically
* Collect payments in supported currencies
* Verify payment status using reference IDs
* Automate post-payment actions inside chatbot flows

***

### Supported Use Cases

* Service payments
* Booking confirmations
* Order payments
* Subscription or one-time fee collection
* Invoice-based payments using reference IDs

***

### Prerequisites

Before enabling this integration, ensure the following:

1. An active AmwalPay merchant account
2. Access to AmwalPay UAT or Production credentials
3. Rapidbott Workspace with Mini App access
4. Approved payment features enabled on your AmwalPay account

***

### Installing the Integration

#### Step 1: Open Rapidbott App Store

1. Login to your Rapidbott Dashboard
2. Navigate to **Mini Apps / Integrations**
3. Search for **AmwalPay**
4. Click **Install**

#### Step 2: Configure Credentials

After installation, you will be prompted to enter:

* Merchant ID
* Terminal ID
* API Base URL (UAT or Production)
* Secret Key (Hex format)

Save the configuration once completed.

***

### Payment Flow Overview

1. User initiates a payment from chatbot
2. Rapidbott generates a unique **Bill Reference ID**
3. Payment link is created via AmwalPay
4. User completes payment on AmwalPay checkout page
5. Transaction status is verified using reference ID
6. Chatbot continues flow based on payment status

***

### Creating a Payment Link

#### Required Parameters

* Amount
* Currency
* Merchant Reference (Bill Reference ID)
* Customer details (optional but recommended)

#### Example Reference ID Format

```
rb_1734518923_X9A2
```

Reference IDs should be:

* Unique per transaction
* Passed consistently across payment creation and verification

***

### Payment Status Verification

Payment verification is done using the **Get Transactions** endpoint.

#### Endpoint

```
/Transaction/GetTransactionsWithStatistics
```

#### Key Fields to Check

* responseCodeName\
  Approved → Payment Successful\
  Declined / Failed → Payment Unsuccessful
* merchantReference\
  Used to match the transaction with your chatbot flow

#### Sample Success Response

```
responseCodeName: Approved
transactionTypeDisplayName: Purchase
amountFormatted: 1.000
currency: OMR
```

***

### Payment Success Trigger (Important)

A payment is considered **successful** when:

* responseCodeName equals `Approved`
* merchantReference matches the generated Bill Reference ID

Once confirmed, you can:

* Send confirmation message to user
* Unlock next chatbot step
* Generate invoice or receipt
* Notify admin or support team

***

### Handling Failed or Pending Payments

If payment is:

* Not found → Retry verification after a short delay
* Declined → Prompt user to retry payment
* Pending → Inform user and recheck after few minutes

***

### Supported Currencies

Common supported currencies include:

* OMR
* INR
* USD
* EUR

Currency availability depends on your AmwalPay merchant account configuration.

***

### Environment Modes

#### UAT (Testing)

* Used for development and testing
* Transactions are not real
* Provided by AmwalPay for sandbox testing

#### Production

* Used for live payments
* Requires feature approval from AmwalPay
* Real money transactions

***

### Common Errors & Notes

#### Payment Feature Not Enabled

If you encounter errors related to payment creation or missing transactions:

* Contact AmwalPay support
* Request enabling of required payment APIs for your merchant account

#### Reference ID Mismatch

Ensure the same reference ID is:

* Used while creating payment
* Used again while verifying payment

***

### Security Best Practices

* Never expose Secret Keys in frontend
* Always verify payment status from backend
* Use HTTPS endpoints only
* Store transaction logs securely

***

### Best Practices

* Always generate unique Bill Reference IDs
* Show clear payment instructions to users
* Handle retries gracefully
* Log all payment attempts for audit

***

### Support

If you face issues with:

* Integration setup
* Payment verification
* API errors

Contact:\
Rapidbott Support\
Email: <support@rapidbott.com>