# Moolre Full Documentation (Sandbox environment)

This file combines Moolre implementation guides and the full API reference for LLM ingestion.

## Environments and authentication
- **Selected environment:** `https://sandbox.moolre.com`
- **Live environment:** `https://api.moolre.com`
- **Sandbox environment:** `https://sandbox.moolre.com`
- Sandbox does not require `X-API-KEY` or `X-API-PUBKEY` placeholders. SMS and WhatsApp use separate service-specific `X-API-VASKEY` credentials.

# Human documentation

# Documentation

Browse Moolre documentation, implementation workflows, API tools, and support resources.

For the full interactive guide, visit / in the Moolre documentation.

---

# Quickstart

Send your first authenticated Moolre API request using the sandbox environment.

For the full interactive guide, visit /get-started/quickstart in the Moolre documentation.

---

# Authentication

Learn which Moolre credentials apply to each service and how sandbox credentials differ from live credentials.

## Callback source IPs

> **Use allowlisting as an additional safeguard:** Use these addresses as one signal when verifying that a callback came from Moolre. Continue using HTTPS, validating callback payloads and transaction references, and handling callbacks idempotently.

### Wallet callbacks

- **IPv4:** `192.241.135.134`
- **IPv6:** `2604:a880:400:d1:0:3:4cf0:c001`

### POS payment-link callbacks

- **IPv4:** `174.138.44.22`
- **IPv6:** `2604:a880:400:d0::1a77:400`

---

# Account wallets

Create and manage Moolre accounts, check balances, and understand account wallet status.

For the full interactive guide, visit /guides/account-wallets in the Moolre documentation.

---

# Transfers

Validate recipients, initiate transfers, and follow the lifecycle of a transfer request.

For the full interactive guide, visit /guides/transfers in the Moolre documentation.

---

# Payments

Collect payments, create payment IDs and links, and monitor payment state.

For the full interactive guide, visit /guides/payments in the Moolre documentation.

---

# SMS messaging

Send messages, manage sender IDs, and understand SMS delivery workflows.

For the full interactive guide, visit /guides/sms in the Moolre documentation.

---

# SMS character counter

Calculate GSM-7 and Unicode SMS length, message parts, and remaining capacity before sending.

For the full interactive guide, visit /guides/sms/counter in the Moolre documentation.

---

# WhatsApp messaging

Retrieve templates, send WhatsApp messages, and check message status.

For the full interactive guide, visit /guides/whatsapp in the Moolre documentation.

---

# USSD integration

Build a callback-driven USSD experience with Moolre.

For the full interactive guide, visit /guides/ussd in the Moolre documentation.

---

# USSD simulator

Test USSD menu flows in the documentation simulator before deployment.

For the full interactive guide, visit /guides/ussd/simulator in the Moolre documentation.

---

# E-Commerce Checkout

Add payments to an online checkout experience.

For the full interactive guide, visit /use-cases/e-commerce in the Moolre documentation.

---

# Voting USSD

Build a USSD voting flow that records participant choices reliably.

For the full interactive guide, visit /use-cases/voting in the Moolre documentation.

---

# USSD applications

Design accessible, callback-driven USSD applications.

For the full interactive guide, visit /use-cases/ussd-applications in the Moolre documentation.

---

# Bulk payouts

Coordinate repeated payouts with clear references and reconciliation.

For the full interactive guide, visit /use-cases/bulk-payouts in the Moolre documentation.

---

# Agency banking

Support agent-assisted financial workflows.

For the full interactive guide, visit /use-cases/agency-banking in the Moolre documentation.

---

# SMS notifications

Deliver operational and customer notification messages.

For the full interactive guide, visit /use-cases/sms-notifications in the Moolre documentation.

---

# Plugins and SDKs

Browse Moolre integrations, plugins, SDKs, and implementation references.

For the full interactive guide, visit /plugins in the Moolre documentation.

---

# Moolre PHP SDK

Use the framework-agnostic `moolre/moolre-php` Composer package to create hosted Moolre payment sessions and verify transactions from a PHP backend.

## When to use it

Use this SDK when a PHP server creates orders, redirects customers to hosted checkout, and controls fulfilment. It is a good fit for stores, invoices, membership payments, and other server-owned payment flows.

It is not a browser or mobile-app SDK. Keep credentials on the PHP server and let browser or mobile apps call that backend for order creation and verification.

The recommended flow is:

1. Create and store a pending order with a unique reference.
2. Redirect the customer to the hosted Moolre checkout URL.
3. Verify the payment on your server, then fulfil the order exactly once.

## Installation

```bash
composer require moolre/moolre-php
```

The SDK requires PHP 7.4 or later and the JSON extension. cURL is recommended; PHP streams are used as a fallback.

## Configure the client

Keep credentials in server-side environment variables. Live payment initiation requires a public key and account number. Sandbox initiation requires an account number and API user; a public key is optional in sandbox. Verification always requires the API user.

```php
use Moolre\Client;

$isProduction = getenv('MOOLRE_PRODUCTION') === 'true';

$client = new Client(
    $isProduction ? (getenv('MOOLRE_PUBLIC_KEY') ?: '') : '',
    getenv('MOOLRE_ACCOUNT_NUMBER') ?: '',
    null,
    $isProduction ? Client::DEFAULT_BASE_URL : Client::SANDBOX_BASE_URL,
    60,
    false,
    getenv('MOOLRE_API_USER') ?: '',
    $isProduction ? Client::DEFAULT_VERIFICATION_URL : Client::SANDBOX_VERIFICATION_URL,
);
```

## Initiate a payment

Create a unique reference in your application, store the pending order, then redirect the customer to the returned hosted authorization URL.

```php
$payment = $client->initiatePayment([
    'reference' => Client::generateReference('order_1001'),
    'email' => 'customer@example.com',
    'amount' => '120.00',
    'currency' => 'GHS',
    'callback' => 'https://example.com/moolre/webhook',
    'redirect' => 'https://example.com/moolre/receipt',
    'expiration_time' => 10,
]);

header('Location: ' . $payment->authorizationUrl(), true, 302);
exit;
```

## Verify before fulfilment

Treat the callback and customer redirect as notifications, not proof of payment. Load the pending order by reference and verify it server-side before fulfilling it.

```php
$transaction = $client->verifyPayment($reference);

if (!$transaction->matchesAmountAndAccountNumber(
    $order['amount'],
    $order['account_number'],
)) {
    throw new RuntimeException('Payment could not be verified for this order.');
}

// Mark this order as paid exactly once, then fulfil it.
```

## Resources

- [GitHub repository](https://github.com/moolrehq/moolre-php)
- [Packagist package](https://packagist.org/packages/moolre/moolre-php)

---

# Frequently asked questions

Find answers to common integration, pricing, and support questions.

For the full interactive guide, visit /support/faq in the Moolre documentation.

---

# SMS Sender ID Guidelines

Choose a clear, recognizable Sender ID that meets Moolre requirements and helps recipients identify who sent an SMS.

## About Sender IDs

Sender IDs are the names displayed on recipients’ phones when they receive SMS messages. They help build trust, make messages recognizable, and protect customers from fraud or confusion.

## Sender ID requirements

A Sender ID must meet all of the following requirements:

- Must not exceed 11 characters.
- May contain letters A–Z and numbers 0–9, where supported.
- Avoid special characters and emojis unless they are supported.
- Must be clear, meaningful, and recognizable.
- Must not contain numbers only.

## Best practices

Use a Sender ID that clearly represents your organization or service.

- Use your company or brand name, such as Moolre, AcmePay, or ShopHub.
- Choose a name your customers will recognize.
- Keep it short and consistent across communications.
- Make sure it accurately represents your organization or service.
- Use different Sender IDs for different brands or services where appropriate.

## Prohibited Sender IDs

Do not use a Sender ID that:

- Impersonates a government agency, financial institution, telecom operator, or another known organization.
- Is misleading or deceptive.
- Contains offensive, abusive, or inappropriate language.
- Infringes on trademarks or brand names.
- Uses random or meaningless character combinations.

## Reseller responsibilities

Moolre is responsible for Sender ID approval. Privileged resellers with approval capabilities must enforce these guidelines before approving a Sender ID for their customers.

Moolre retains oversight and may reject a Sender ID even if it has been approved by a reseller. Repeated breaches may result in revoked approval privileges and require direct Moolre approval.

- Validate that the Sender ID meets the listed requirements.
- Confirm that it does not impersonate another organization.
- Ensure that it is meaningful and represents the customer appropriately.

## Examples

Use these examples as a quick reference when choosing a Sender ID.

| Acceptable | Not acceptable |
| --- | --- |
| Moolre | 12345678901 |
| AcmePay | MTN Ghana |
| ShopHub | BankOfGH |
| Innville | $$$Promo |
| DigiMart | ABC123456789 (exceeds 11 characters) |

> **Review and approval:** Sender IDs are subject to review. Moolre may reject any Sender ID that violates these guidelines or applicable regulatory requirements.


---

# Errors and status codes

Read Moolre response envelopes, distinguish transport errors from API errors, and surface actionable failures to users.

## Read the response envelope first

Moolre responses include a status value, a code, a message, data, and an optional go value. Use the HTTP status for transport-level handling, then use the response code and message to decide what the application should do next.

Treat successful HTTP responses with an application error payload as an API-level failure. Keep the code and a correlation value in your logs so support can trace the request quickly.

## Handle failures deliberately

Show people a clear next step instead of exposing raw API messages. Validation failures normally need corrected input, while timeouts and 5xx responses may be retried safely when an idempotency reference is present.

- 400-range errors: correct the request, credentials, or referenced resource before retrying.
- 401 and 403 errors: verify the environment, API user, and the credential expected by that endpoint.
- 429 and 5xx errors: wait, back off, and retry only with the same external reference.


---

# Idempotency and external references

Prevent duplicate payment and transfer attempts by designing stable external references and storing request outcomes.

## Use one durable reference per business action

Create an external reference before you make a payment or transfer request. Store it alongside the business record and reuse it when you retry the same action after a timeout or uncertain response.

Do not generate a new reference after a network failure. A new reference can turn a retry into a second financial instruction.

## Reconcile uncertain outcomes

When a request times out, keep the operation pending and check its status or wait for the related callback. Mark it complete only when the final state is confirmed.

> **Keep references unique:** External references should be unique within your integration and meaningful enough to trace back to your own order, invoice, or transfer record.


---

# Webhooks and callbacks

Receive asynchronous status updates safely and make callback processing reliable, secure, and observable.

## Design a reliable callback endpoint

Expose a stable HTTPS endpoint that accepts the callback payload, validates it, records the event, and returns a quick success response. Slow work should happen after the event has been persisted.

- Use HTTPS and restrict access where your infrastructure supports it.
- Persist the raw payload, timestamp, and the reference before updating your business record.
- Make processing idempotent because the same callback may be delivered more than once.

## Verify the final state

A callback should be matched to an existing business record using its reference. For high-value actions or an unexpected payload, verify the state with the relevant status endpoint before completing the customer-facing workflow.


---

# Safe retries

Retry temporary failures without creating duplicate financial or messaging operations.

## Retry only transient failures

Network failures, gateway timeouts, 429 responses, and selected 5xx responses are candidates for a retry. Validation, authentication, and duplicate-reference errors need a change before another request is made.

## Back off and preserve context

Use bounded exponential backoff with jitter. Keep the same external reference, request data, and environment for every retry so reconciliation remains unambiguous.

> **Do not retry blindly:** If the outcome is uncertain after a timeout, check status or await the callback before retrying a financial operation.


---

# Sandbox testing

Use the sandbox environment to validate request construction, user journeys, callbacks, and operational handling before going live.

## Use the correct environment

Sandbox requests use https://sandbox.moolre.com. SMS and WhatsApp each use a separate service-specific X-API-VASKEY, so enter the key created for the service you are calling.

## Test real integration paths

Cover success, validation failure, duplicate reference, callback delivery, and uncertain network outcomes. Record the request reference in your test notes so every case can be investigated.


---

# Go-live checklist

Prepare credentials, callback handling, monitoring, support processes, and safe rollout controls for production.

## Before switching to live

Confirm that production credentials are stored in a secret manager, callbacks are reachable over HTTPS, alerting is configured, and your team can reconcile a request by its external reference.

- Swap the sandbox base URL for https://api.moolre.com.
- Use production-only credentials and keep them out of client-side code.
- Validate status checks, callbacks, retries, and support escalation paths.
- Roll out gradually and monitor the first live requests closely.


---

# Supported channels and services

Choose the Moolre API surface that fits your payment, transfer, account, SMS, WhatsApp, or USSD workflow.

## Choose the right API surface

Use Account APIs for wallet lifecycle and balances, Transfer APIs for movement between accounts and recipients, Payment APIs for collections and payment links, and Messaging APIs for SMS and WhatsApp. USSD guides explain the callback-driven integration experience.

## Confirm availability for your rollout

Service coverage, commercial eligibility, and operational limits can differ by product and account. Validate requirements with your Moolre contact before committing a production rollout plan.


---

# API reference

# Moolre API Reference

The API Reference is the technical contract for the Moolre API. Each endpoint page documents its path, method, required credentials, request parameters, request body, and response examples.

Use the Moolre Documentation for product guidance and end-to-end workflows. Use Authentication to learn which credential applies to each service, and Errors and status codes for the shared response envelope and failure handling.

## Start here

- [Documentation](https://docs.moolre.com/)
- [Authentication](https://docs.moolre.com/authentication)
- [Errors and status codes](https://docs.moolre.com/guides/errors-and-status-codes)
- [Create account](https://docs.moolre.com/api/accounts/create)

---

# Send SMS API

The Send SMS (POST) API allows you to send bulk or single SMS messages to recipients across any network. Note: This API requires X-API-VASKEY in the header for authentication.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/sms/send

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your SMS API VAS key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | ID of the sms sending function. Must be 1. |
| senderid | string | Yes | Your registered and approved Sender ID (max 11 chars). |
| messages | array | Yes | An array of message objects containing recipient, message, and optional ref. |

## Response (200 Success)
SMS message(s) sent successfully.

```json
{
  "status": 1,
  "code": "SMS01",
  "message": "Success",
  "data": null,
  "go": null
}
```

## Response (400 Unapproved Sender ID)
The Sender ID provided is not yet approved or registered.

```json
{
  "status": 0,
  "code": "ASMS07",
  "message": "Sender ID is not approved, Please login on app.moolre.com and setup your Sender ID.",
  "data": "senderid",
  "go": null
}
```

## Response (401 Authentication Error)
The VAS Key provided is invalid or unauthorized.

```json
{
  "status": 0,
  "code": "AIN01",
  "message": "Authentication Error",
  "data": null,
  "go": null
}
```


---

# Send SMS (GET) API

The Send SMS (GET) API allows you to send SMS instantly using query parameters.

## Endpoint
- **Method**: GET
- **URL**: https://sandbox.moolre.com/open/sms/send

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your SMS API VAS key. |

## Query Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| senderid | string | Yes | Registered and approved Sender ID. |
| recipient | string | Yes | Recipient phone number. |
| message | string | Yes | Message content (max 160 characters). |

## Response (200 Success)
SMS sent successfully.

```json
{
  "status": 1,
  "code": "SMS01",
  "message": "Success",
  "data": null,
  "go": null
}
```

## Response (401 Authentication Error)
The VAS Key provided is invalid or unauthorized.

```json
{
  "status": 0,
  "code": "AIN01",
  "message": "Authentication Error",
  "data": null,
  "go": null
}
```


---

# SMS Status API

Check the delivery status of sent SMS messages. Note: This API requires X-API-VASKEY in the header for authentication.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/sms/status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your SMS API VAS key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 5. |
| ref | array | Yes | Array of message references to check. |

## Response (200 Success)
Status details returned.

```json
{
  "status": 1,
  "code": "ASMQ10",
  "message": "SMS Status",
  "data": [
    {
      "ref": "0338954001737166274",
      "status": 3
    },
    {
      "ref": "uuid--001",
      "status": 2
    }
  ],
  "go": null
}
```


---

# Create Sender ID API

Request a new Sender ID for your SMS campaigns. Note: This API requires X-API-VASKEY in the header for authentication.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/sms/query

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your SMS API VAS key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | ID of the sender ID creation function. Must be 3. |
| senderids | array | Yes | An array of sender ID objects containing senderid (max 11 chars) and optional approve boolean. |

## Response (200 Success)
Registration request submitted.

```json
{
  "status": 1,
  "code": "ASMQ12",
  "message": "Sender IDs Created Successfully.",
  "data": null,
  "go": null
}
```

## Response (400 Permission Denied)
You do not have permission to approve Sender IDs.

```json
{
  "status": 0,
  "code": "ASMQ09",
  "message": "You do not have permission to approve Sender IDs. Contact Customer Support.",
  "data": "senderid",
  "go": null
}
```


---

# Sender ID Status API

Check the approval status of a Sender ID. Note: This API requires X-API-VASKEY in the header for authentication.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/sms/status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your SMS API VAS key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | ID of the sender ID status function. Must be 1. |
| senderid | string | Yes | Sender ID to check. |

## Response (200 (Success) Success)
Sender ID is Approved.

```json
{
  "status": 1,
  "code": "ASMQ01",
  "message": "Sender ID Status",
  "data": {
    "senderid": "SmartSMS",
    "approval": "Approved",
    "whitelisted": false
  },
  "go": null
}
```

## Response (200 (Pending) Pending)
Sender ID is Pending approval.

```json
{
  "status": 1,
  "code": "ASMQ01",
  "message": "Sender ID Status",
  "data": {
    "senderid": "Dummy",
    "approval": "Pending",
    "whitelisted": false
  },
  "go": null
}
```

## Response (200 (Rejected) Rejected)
Sender ID is Rejected.

```json
{
  "status": 1,
  "code": "ASMQ01",
  "message": "Sender ID Status",
  "data": {
    "senderid": "Momo",
    "approval": "Rejected",
    "whitelisted": false
  },
  "go": null
}
```


---

# List Sender IDs API

Retrieve a list of all your registered Sender IDs along with their status. Note: This API requires X-API-VASKEY in the header for authentication.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/sms/status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your SMS API VAS key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | ID of the list sender IDs function. Must be 7. |

## Response (200 Success)
List of Sender IDs returned.

```json
{
  "status": 1,
  "code": "ASMQ08",
  "message": "List of Your Sender IDs.",
  "data": [
    {
      "id": 13,
      "senderid": "SmartSMS",
      "approval": "Approved",
      "whitelisted": false
    },
    {
      "id": 14,
      "senderid": "Dummy",
      "approval": "Pending",
      "whitelisted": false
    },
    {
      "id": 15,
      "senderid": "Dymmy ID",
      "approval": "Pending",
      "whitelisted": false
    },
    {
      "id": 4010,
      "senderid": "Momo",
      "approval": "Rejected",
      "whitelisted": false
    }
  ],
  "go": null
}
```


---

# Approve Sender ID API

Approve or reject registered Sender IDs. Note: This API requires X-API-VASKEY in the header for authentication and specific administrative permissions.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/sms/status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your SMS API VAS key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | ID of the approve sender ID function. Must be 6. |
| senderids | array | Yes | An array of sender ID objects containing senderid and approve (0 = Pending, 1 = Approved, 2 = Rejected). |

## Response (200 Success)
Sender IDs updated successfully.

```json
{
  "status": 1,
  "code": "ASMQ07",
  "message": "Sender IDs updated successfully.",
  "data": [
    {
      "id": "14",
      "senderid": "Dummy",
      "approval": "Approved",
      "whitelisted": false
    },
    {
      "id": "13",
      "senderid": "SmartSMS",
      "approval": "Rejected",
      "whitelisted": false
    }
  ],
  "go": null
}
```

## Response (400 Permission Denied)
You do not have permission to update Sender IDs.

```json
{
  "status": 0,
  "code": "ASMQ09",
  "message": "You do not have permission to update Sender IDs. Contact Customer Support.",
  "data": "senderid",
  "go": null
}
```


---

# SMS Account Status API

Check your SMS credit balance. Note: This API requires X-API-VASKEY in the header for authentication.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/sms/status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your SMS API VAS key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 2. |

## Response (200 Success)
Balance returned.

```json
{
  "status": 1,
  "code": "ASMQ03",
  "message": "Account Status",
  "data": {
    "balance": 857
  },
  "go": null
}
```


---

# Get Templates API

Fetch your approved WhatsApp message templates. Note: This API requires X-API-VASKEY in the header for authentication.

## Endpoint
- **Method**: GET
- **URL**: https://sandbox.moolre.com/open/whatsapp/template

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your WhatsApp API VAS key. |

## Query Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| next | string | No | Opaque cursor returned in the previous response. Omit it to request the first page; the documentation Next button manages this automatically. |

## Response (200 (Approved) Success)
Returns a list containing approved templates.

```json
{
  "status": 1,
  "code": "WAS200",
  "message": "Templates retrieved successfully",
  "data": [
    {
      "id": "1218877297066056",
      "name": "promotion",
      "language": "en",
      "status": "APPROVED",
      "message": "Hello {{1}},\n\nMelchizedek Technologies would like to share information about our {{2}} designed to support businesses like {{3}}.\n\nIf you would like to learn more or speak with our team, please reply to this message and we will be happy to assist.\n",
      "placeholders": [
        "1",
        "2",
        "3"
      ]
    }
  ],
  "next": "opaque-cursor-for-the-next-page"
}
```

## Response (200 (Rejected) Success)
Returns a list containing rejected templates.

```json
{
  "status": 1,
  "code": "WAS200",
  "message": "Templates retrieved successfully",
  "data": [
    {
      "id": "1470051854524583",
      "name": "whatsapp_test",
      "language": "en",
      "status": "REJECTED",
      "message": "Hello {{1}},\n\nYou are receiving this message from Melchizedek Technologies in response to your request with {{2}}.\n\nIf you need any assistance, please reply to this message and our support team will assist you.\n",
      "placeholders": [
        "1",
        "2"
      ]
    }
  ],
  "next": null
}
```

## Response (200 (Pending) Success)
Returns a list containing pending templates.

```json
{
  "status": 1,
  "code": "WAS200",
  "message": "Templates retrieved successfully",
  "data": [
    {
      "id": "1709192906730643",
      "name": "update",
      "language": "en",
      "status": "PENDING",
      "message": "Hello {{1}},\n\nThank you for contacting Melchizedek Technologies.\nYour request regarding {{2}} has been received and our team will assist you shortly.\n",
      "placeholders": [
        "1",
        "2"
      ]
    }
  ],
  "next": null
}
```


---

# Send Message API

Send batch WhatsApp messages using an approved template name. The unique reference (ref) is optional; however, without it, the message status cannot be tracked.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/whatsapp/send

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your WhatsApp API VAS key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| template_name | string | Yes | The name of the approved WhatsApp template. |
| language | string | Yes | The language code for the template (English only). |
| messages | array | Yes | An array of message objects containing recipient, optional ref, and placeholders. Note: If ref is omitted, the status cannot be checked later. |

## Response (200 (Success) Success)
All messages were sent successfully.

```json
{
  "status": 1,
  "code": "WAS200",
  "message": "suceess",
  "error": [],
  "data": []
}
```

## Response (200 (Duplicate Refs) Warning)
Some messages were not sent due to non-unique references.

```json
{
  "status": 1,
  "code": "WAS200",
  "error": "Some ref are not unique, corresponding messages will not be sent",
  "message": "",
  "data": [
    {
      "recipient": "233531419000",
      "ref": "879883HGU334553GF887799HF20004"
    },
    {
      "recipient": "233531419011",
      "ref": "879883HGU334553GF887799HF20006"
    }
  ]
}
```

## Response (401 (Insufficient Balance) Insufficient Balance)
The account has insufficient balance to send WhatsApp messages.

```json
{
  "status": 0,
  "code": "WAS401",
  "message": "Insufficient balance to send messages. Please top up your WhatsApp bundle."
}
```


---

# Message Status API

Track the delivery status of your WhatsApp messages using their unique references. Supports batch status checks.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/whatsapp/status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-VASKEY | string | Yes | Your WhatsApp API VAS key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| ref | array | Yes | An array of unique message references to check. |

## Response (200 (Success) Success)
Status details for all requested references returned.

```json
{
  "status": 1,
  "code": "WAS200",
  "message": "success",
  "data": [
    {
      "ref": "879883HGUGF45583499HF2089001",
      "status": "read"
    },
    {
      "ref": "879883HGUGF45583499HF2089005",
      "status": "accepted"
    }
  ]
}
```


---

# Create Account API

Create a new business wallet/account.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/account/create

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your Private API Key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| accountname | string | Yes | Registered name of the business. |
| currency | string | Yes | Currency code: GHS (Ghana Cedis). |
| api | boolean | No | Set to true to enable API transactions for the new account. |
| callback | string | Yes | Webhook URL for processing real-time transaction callbacks. |
| settlement | object | Yes | Required settlement object. Leave frequency, channel, recipient, and sublist empty when automatic settlement is not configured. |

## Response (200 Success)
Account created successfully.

```json
{
  "status": "1",
  "code": "WC02",
  "message": [
    "Wallet Created Successfully",
    "Your wallet will be reloaded shortly or Click close to refresh now."
  ],
  "data": {
    "status": 1,
    "accountnumber": "100000157291",
    "accountname": "My Business LTD",
    "paymentid": "0757291",
    "api": 0,
    "callback": "",
    "settlement": {},
    "secret": "cf2a797f-c8d8-470c-a736-6f5f78ae1d86"
  },
  "go": [
    "wallets",
    "1.57291"
  ]
}
```


---

# Update Account API

Update business wallet/account details and settlement settings.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/account/update

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your Private API Key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| accountnumber | string | Yes | The account number you want to update. |
| accountname | string | No | Updated business name. |
| currency | string | Yes | Account currency. This endpoint always requires GHS. |
| api | boolean | No | Only send this when you intend to change the account API access setting. |
| callback | string | No | Webhook URL for callbacks. |
| settlement | object | No | Settlement details object (currency, frequency, channel, recipient, sublist). |

## Response (200 Success)
Account updated successfully.

```json
{
  "status": "1",
  "code": "WCU02",
  "message": "Account Updated Successfully",
  "data": {
    "status": 1,
    "accountnumber": "100000157257",
    "accountname": "My Business PLC",
    "paymentid": "0757257",
    "api": 0,
    "callback": "https://nocall.com/noend",
    "settlement": {
      "currency": "GHS",
      "frequency": "1",
      "channel": "1",
      "recipient": "0246798090",
      "sublist": "300303"
    },
    "secret": "bcec3865-bea1-4a99-8e70-c6a434cac757"
  },
  "go": null
}
```


---

# Account Status API

Check wallet balance and status.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/account/status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your Private API Key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| accountnumber | string | Yes | Account number to check. |

## Response (200 Success)
Balance and status returned.

```json
{
  "status": 1,
  "code": "SW01",
  "message": "Wallet Found",
  "data": {
    "balance": 10.67,
    "accountname": "Zagey",
    "callback": "https://moolre.requestcatcher.com/test"
  },
  "go": null
}
```

## Response (200 (No transactions) No Transactions Found)
Known response returned when the account has no transaction history available to the status query.

```json
{
  "status": 1,
  "code": "ST09",
  "message": "Transactions not Found",
  "data": {
    "txcount": "0",
    "transactions": []
  },
  "go": null
}
```

## Response (401 Authentication Error)
API Access not activated.

```json
{
  "status": 0,
  "code": "AIN04",
  "message": "Authentication Error, API Access not activated.",
  "data": "all",
  "go": null
}
```


---

# List Transactions API

Fetch a list of transactions linked with a specific account.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/account/status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your Private API Key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 2. |
| accountnumber | string | Yes | Your Account Number. |
| startdate | string | No | Start date (YYYY-MM-DD HH:MM:SS). |
| enddate | string | No | End date (YYYY-MM-DD HH:MM:SS). Defaults to the last second of the current year. |
| limit | string | No | Max transactions per page. |
| status | integer | No | Optional status filter: 0=Pending, 1=Successful, 2=Failed. |

## Response (200 Success)
List of transactions returned.

```json
{
  "status": 1,
  "code": "ST08",
  "message": "Transactions Found",
  "data": {
    "txcount": "1",
    "transactions": [
      {
        "txstatus": 1,
        "txtype": 1,
        "accountnumber": "100000100002",
        "payer": "233551300186",
        "payee": "Zagey",
        "amount": "1.00",
        "value": "1",
        "transactionid": "34008096",
        "externalref": "0",
        "thirdpartyref": "55730796319",
        "ts": "2025-04-15 12:36:28"
      }
    ]
  },
  "go": null
}
```


---

# Validate Name API

Confirm the name of a Mobile Money or Bank Account holder before initiating a transfer.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/transact/validate

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your API Key (accepts both Public Key and Private Key). |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| receiver | string | Yes | Phone number or bank account number. |
| channel | string | Yes | 1=MTN, 6=Telecel, 7=AT, 2=Instant Bank Transfer. |
| sublistid | string | No | Required when channel is 2 (Instant Bank Transfer). Use the bank code returned by Get banks. |
| currency | string | Yes | Currency code: GHS (Ghana Cedis) or NGN (Nigerian Naira). |
| accountnumber | string | Yes | Your Moolre Account Number. |

## Response (200 Success)
Name validated successfully.

```json
{
  "status": 1,
  "code": "AVD01",
  "message": "Successful",
  "data": "BRIGHT BUAME",
  "go": null
}
```

## Response (400 Not Found)
The phone number or account was not found.

```json
{
  "status": 0,
  "code": "AVD02",
  "message": "Phone No. not found",
  "data": "Phone No. not found",
  "go": null
}
```


---

# Initiate Transfer API

Send money to a Mobile Money or Bank Account instantly.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/transact/transfer

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your API Key (Private Key only). |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| channel | string | Yes | 1=MTN, 6=Telecel, 7=AT, 2=Instant Bank Transfer. |
| currency | string | Yes | Currency code: GHS (Ghana Cedis) or NGN (Nigerian Naira). |
| amount | string | Yes | Amount to transfer. Must be greater than 0. |
| receiver | string | Yes | Recipient mobile number (begin with 0) or bank account number. |
| sublistid | string | No | Required when channel is 2 (Instant Bank Transfer). Use the bank code returned by Get banks. |
| externalref | string | Yes | Unique reference for the transfer. |
| reference | string | No | Optional message/reference. |
| accountnumber | string | Yes | Your Moolre Account Number. |

## Response (200 Success)
Transfer request received.

```json
{
  "status": "1",
  "code": "OBGH01",
  "message": [
    "Pay out Successful",
    "Click close to view transactions."
  ],
  "data": {
    "txstatus": 1,
    "receiver": "0246798993",
    "transactionid": "32759150",
    "externalref": "28171451",
    "thirdpartyref": "901733241086",
    "receivername": "YUSIF YA-ADZAGEY",
    "amount": "1",
    "amountfee": "1.01",
    "networkfee": "0.00",
    "fee": "0.01"
  },
  "go": null
}
```


---

# Transfer Status API

Check the final status of a previously initiated transfer.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/transact/status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your API Key (accepts both Public Key and Private Key). |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| idtype | integer | Yes | 1 = Unique externalref, 2 = Moolre Generated ID. |
| id | string | Yes | The reference ID to check. |
| accountnumber | string | Yes | Your Moolre Account Number. |

## Response (200 Success)
Transfer status details.

```json
{
  "status": 1,
  "code": "SS01",
  "message": "Transaction Successful",
  "data": {
    "txstatus": 1,
    "txtype": 2,
    "accountnumber": "100000100002",
    "payer": "",
    "payee": "0246798993",
    "amount": "5",
    "value": "5",
    "transactionid": "31830714",
    "externalref": "1231231-12985",
    "thirdpartyref": "141704447750",
    "ts": "2024-01-05 09:42:33"
  },
  "go": null
}
```


---

# Mobile Money Collection API

Send a USSD payment request to a payer's phone number for approval.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/transact/payment

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-PUBKEY | string | Yes | Your Public API Key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| channel | string | Yes | 13=MTN, 6=Telecel, 7=AT. |
| currency | string | Yes | Currency code: GHS (Ghana Cedis) or NGN (Nigerian Naira). |
| payer | string | Yes | Customer's phone number. Use the local 0-prefixed format. |
| amount | string | Yes | Amount to collect. Must be greater than 0. |
| externalref | string | Yes | Unique reference for the payment. |
| otpcode | string | No | OTP code if required by the flow. |
| reference | string | No | Optional payment reference. |
| sessionid | string | No | USSD session ID if applicable. |
| accountnumber | string | Yes | Your Moolre Account Number. |
| skipotp | boolean | No | Sandbox only. Set true to skip OTP simulation; defaults to false. |

## Response (200 (OTP Required) OTP Required)
Payment requires phone number verification.

```json
{
  "status": 1,
  "code": "TP14",
  "message": "Please complete the verification process sent to you via SMS and try again.",
  "data": "all",
  "go": null
}
```

## Response (200 (Payment Request) Success)
Payment request initiated successfully.

```json
{
  "status": 1,
  "code": "TR099",
  "message": null,
  "data": "f25fc80e-791b-495b-8799-dcf87660457d",
  "go": null
}
```

## Response (400 Duplicate Reference)
The external reference must be unique.

```json
{
  "status": "0",
  "code": "TP13",
  "message": "External Reference is required and must be unique.",
  "data": "externalref",
  "go": null
}
```


---

# Internal Transfer API

Initiate an internal transfer using your Moolre account.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/transact/internal

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your Private API Key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| currency | string | Yes | Currency code: GHS (Ghana Cedis) or NGN (Nigerian Naira). |
| amount | string | Yes | Amount to transfer. Must be greater than 0. |
| receiver | string | Yes | Destination Moolre account number. This must not be a mobile phone number. |
| externalref | string | Yes | Unique reference for the transfer. |
| reference | string | No | Optional narration or reference text. |
| accountnumber | string | Yes | Your Moolre Account Number. |

## Response (200 Success)
The internal transfer request was accepted. Confirm the final outcome through the transfer status workflow when your integration needs a terminal state.

```json
{
  "status": 1,
  "code": "TR099",
  "message": "Internal transfer initiated successfully",
  "data": "f25fc80e-791b-495b-8799-dcf87660457d",
  "go": null
}
```

## Response (400 Duplicate Reference)
The external reference must be unique for the transfer request.

```json
{
  "status": "0",
  "code": "TR013",
  "message": "External Reference is required and must be unique.",
  "data": "externalref",
  "go": null
}
```


---

# Create Payment ID API

Generate a unique permanent payment ID for use in making payments. In Live mode, customers dial *203*paymentid#; in Sandbox mode, they dial *203*6000*paymentid#.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/account/create

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-PUBKEY | string | Yes | Your Public API Key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | ID of the function. Must be 2. |
| phone | string | Yes | Phone number of the customer in +233 format (e.g., +233267606822). |
| name | string | Yes | Name of the Customer or a Unique ID. |
| currency | string | Yes | Currency of your account/wallet: GHS (Ghana Cedis) or NGN (Nigerian Naira). |
| amount | string | No | Optional preset payment amount. Omit it to create a Payment ID without a preset limit; when provided, it must be greater than 0. |
| externalref | string | No | Unique ID to identify the request. |
| accountnumber | string | Yes | Your Moolre Account Number. |

## Response (200 Success)
Payment ID generated.

```json
{
  "status": 1,
  "code": "AD14",
  "message": "Terminal Creation Successful",
  "data": {
    "paymentid": "08160984",
    "name": "Kofi Adeniyi",
    "qrcode": null
  },
  "go": null
}
```


---

# Bank Collections API

Generate a permanent virtual bank account number linked to your wallet/account for secure payments.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/account/create

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-PUBKEY | string | Yes | Your Public API Key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 9. |
| currency | string | Yes | Currency code: GHS (Ghana Cedis) or NGN (Nigerian Naira). |
| amount | number | No | Optional initial amount. When provided, it must be greater than 0. |
| firstname | string | Yes | First name of the account holder. |
| lastname | string | Yes | Last name of the account holder. |
| phone | string | Yes | Phone number of the account holder. |
| email | string | Yes | Email address of the account holder. |
| uref | string | Yes | Unique request reference. |
| accountnumber | string | Yes | Your Moolre Account Number. |

## Response (200 Success)
Bank account number created successfully.

```json
{
  "status": 1,
  "code": "AD19",
  "message": "Account No. Creation Successful",
  "data": {
    "accountno": "0014730001001",
    "accountname": "Kofi Adeniyi3 MoolrePay",
    "bankname": "First Atlantic Bank",
    "uref": "uref001"
  },
  "go": null
}
```

## Response (400 (Duplicate Name) Failed)
Bank account creation failed because the name is already in use.

```json
{
  "status": 0,
  "code": "AD32",
  "message": "Account No. Creation Failed",
  "data": "all",
  "go": null
}
```


---

# Generate Payment Link API

Create a hosted payment page URL. The Payment link system is used to generate a URL that opens a Moolre Web POS page for collecting payments.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/embed/link

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-PUBKEY | string | Yes | Your Public API Key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| amount | string | Yes | Amount to be paid. Must be greater than 0. |
| email | string | Yes | Email of the business. |
| externalref | string | Yes | Unique ID to identify the payment. |
| callback | string | No | Callback URL for payment notifications. |
| redirect | string | No | Redirect URL after successful payment. |
| reusable | string | Yes | Determines if the link can be used for repeat payments. 0=No, 1=Yes. |
| expiration_time | integer | No | Link expiry time in minutes. Minimum 1 minute. |
| currency | string | Yes | Currency of your account/wallet: GHS (Ghana Cedis) or NGN (Nigerian Naira). |
| accountnumber | string | Yes | Your Moolre Account Number. |
| metadata | object | No | Optional metadata to be returned in callbacks. |

## Response (200 Success)
Link generated successfully.

```json
{
  "status": 1,
  "code": "POS09",
  "message": "POS payment link successfully generated.",
  "data": {
    "authorization_url": "https://pos.moolre.com/RZWs1yB6amGjNoiEQvlHPS5uqgp3Jc",
    "reference": "uuid-1234as2"
  }
}
```

## Response (400 Duplicate Transaction)
Transaction already exists with this reference.

```json
{
  "status": 0,
  "code": "INP02",
  "message": "Transaction already exits!",
  "data": []
}
```


---

# Payment Status API

Check the final status of a previously initiated payment collection.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/transact/status

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-PUBKEY | string | Yes | Your Public API Key. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| idtype | integer | Yes | 1 = Unique externalref, 2 = Moolre Generated ID. |
| id | string | Yes | The reference ID to check. |
| accountnumber | string | Yes | Your Moolre Account Number. |

## Response (200 Success)
Payment status details.

```json
{
  "status": 1,
  "code": "SS01",
  "message": "Transaction Successful",
  "data": {
    "txstatus": 1,
    "txtype": 2,
    "accountnumber": "100000100002",
    "payer": "",
    "payee": "0209151872",
    "amount": "1",
    "value": "1",
    "transactionid": "31772290",
    "externalref": "1231231-128",
    "thirdpartyref": "471700539041",
    "ts": "2023-11-21 03:57:25"
  },
  "go": null
}
```


---

# Miscellaneous Data API

Fetch real-time system data such as supported banks, mobile money channels, and other configuration data.

## Endpoint
- **Method**: GET
- **URL**: https://sandbox.moolre.com/open/transact/data

## Query Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| country | string | Yes | Country code (e.g., gha). |
| data | string | Yes | Type of data to fetch (e.g., banks). |

## Response (200 Success)
Data list returned.

```json
{
  "status": 1,
  "code": "SD01",
  "message": "Banks Found",
  "data": [
    {
      "name": "ABSA BANK GHANA LTD",
      "code": "030100"
    },
    {
      "name": "ACCESS BANK GHANA LTD",
      "code": "030402"
    },
    {
      "name": "ADB BANK GHANA LTD",
      "code": "030301"
    }
  ],
  "go": null
}
```


---

# Payment Webhook API

Moolre sends real-time HTTP POST notifications (callbacks) to your server when a payment is received or its status changes.

## Endpoint
- **Method**: POST
- **URL**: {{YOUR_CALLBACK_URL}}

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| status | integer | Yes | 1 for success |
| code | string | Yes | P01 |
| message | string | Yes | Transaction Successful |
| data | object | Yes | The transaction details |


---