# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rapidbott.com/help-center/platform/introduction/integrations/amwalpay-payment-gateway-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.