Modem Pay

https://docs.modempay.com/
Admin
Modem Pay is a payment platform for collecting payments, managing transactions, and handling payouts...
Tokens:64,457
Snippets:508
Trust Score:5.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Inline Payment Setup with ModemPayCheckout

Source: https://docs.modempay.com/documentation/payments/modem-inline

This HTML and JavaScript example demonstrates how to set up an inline payment modal using the ModemPayCheckout function. It includes basic HTML structure, CSS, and the necessary JavaScript to initiate a payment when a button is clicked. Ensure you include the Modem Pay API script.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Modem Pay</title>
    <link rel="stylesheet" href="https://api.modempay.com/dist/main.css" />
    <script src="https://api.modempay.com/js/v1.js"></script>
  </head>
  <body>
    <h1>Inline Payment Example</h1>
    <button type="button" onclick="makePayment()" id="start-payment-button">
      Pay Now
    </button>

    <script>
      function makePayment() {
        const modal = ModemPayCheckout({
          amount: 450,
          public_key:
            "pk_test_e073bbf9db47b09cebfdf2f7ec147d02116b69ea55135e1747a0bc8d47612f69",
          payment_methods: "wallet,card,bank",
          callback: (transaction) => {
            console.log("Payment completed:", transaction);
            // Handle post-payment actions
            modal.close();
          },
          onClose: (cancelled) => {
            if (cancelled) {
              console.log("Payment was cancelled.");
              // Handle payment cancellation
            }
          },
        });
      }
    </script>
  </body>
</html>
```

--------------------------------

### Install Modem Pay SDK

Source: https://docs.modempay.com/documentation/installation

Install the Modem Pay SDK using npm for Node.js, pip for Python, or Composer for PHP.

```bash
npm install modem-pay
```

```bash
pip install modempay
```

```bash
composer require modempay/modempay-php
```

--------------------------------

### Install Modem Pay CLI

Source: https://docs.modempay.com/documentation/core/webhook-cli

Install the Modem Pay CLI globally using npm. Ensure Node.js and npm are installed first.

```bash
npm install -g modem-pay-cli
```

--------------------------------

### Complete Payment Flow Example

Source: https://docs.modempay.com/laravel/usage

A comprehensive example demonstrating a typical checkout process, including payment creation and redirection.

```APIDOC
## Example: Complete Payment Flow

This example shows a full payment flow from checkout to redirection.

```php
public function checkout(Request $request)
{
    try {
        // Create payment
        $payment = ModemPay::paymentIntents()->create([
            'amount' => $request->total,
            'currency' => 'GMD',
            'title' => "Order #{$request->order_id}",
            'metadata' => [
                'order_id' => $request->order_id,
                'user_id' => auth()->id(),
            ]
        ]);

        // Redirect to payment page
        return redirect($payment->data->payment_link);

    } catch (ModemPayException $e) {
        return back()->with('error', 'Payment failed: ' . $e->getMessage());
    }
}
```
```

--------------------------------

### Verify ModemPay Setup in Tinker

Source: https://docs.modempay.com/laravel/configuration

Test your ModemPay configuration by running a command in Tinker to list payment intents. If this works, your setup is complete.

```bash
php artisan tinker
```

```php
ModemPay::paymentIntents()->list();
```

--------------------------------

### Install Modem Pay Button Script

Source: https://docs.modempay.com/documentation/payments/drop-in

Add this script tag to your HTML to make the `<modempay-button>` element available on your page. No further setup is required.

```html
<script src="https://api.modempay.com/js/modempay-button.js"></script>
```

--------------------------------

### Complete Payment Flow Example

Source: https://docs.modempay.com/laravel/usage

A comprehensive example demonstrating the creation of a payment intent, redirection to the payment page, and error handling within a Laravel controller method.

```php
public function checkout(Request $request)
{
    try {
        // Create payment
        $payment = ModemPay::paymentIntents()->create([
            'amount' => $request->total,
            'currency' => 'GMD',
            'title' => "Order #{$request->order_id}",
            'metadata' => [
                'order_id' => $request->order_id,
                'user_id' => auth()->id(),
            ]
        ]);

        // Redirect to payment page
        return redirect($payment->data->payment_link);

    } catch (ModemPayException $e) {
        return back()->with('error', 'Payment failed: ' . $e->getMessage());
    }
}
```

--------------------------------

### Create Payment Intent and Handle Webhooks

Source: https://docs.modempay.com/documentation/payments/custom

This Node.js example demonstrates creating a payment intent on the backend and setting up a webhook endpoint to verify payment events. Ensure your MODEM_WEBHOOK_SECRET environment variable is set.

```javascript
import express from "express";
import path from "path";
import bodyParser from "body-parser";
import ModemPay from "modem-pay";

const modem = new ModemPay(
  "sk_test_516aa853e1574295ed778eadc82b0a7128b18b628e4059f82e77041adf8692cb"
);

const app = express();
app.use(bodyParser.urlencoded({ extended: true }));
app.use(express.static(path.join(__dirname, "public")));

const YOUR_DOMAIN = "http://localhost:7024";

app.post("/create-checkout-session", async (req, res) => {
  const intent = await modempay.paymentIntents.create({
    ...req.body,
    return_url: `${YOUR_DOMAIN}/success.html`,
    cancel_url: `${YOUR_DOMAIN}/cancel.html`,
  });

  res.redirect(303, intent.link);
});


app.post('/verify', async (req, res) => {
  const payload = req.body;
  const signature = req.headers["x-modem-signature"];
  const secret = process.env.MODEM_WEBHOOK_SECRET;

  try {
    const event = modempay.webhooks.composeEventDetails(payload, signature, secret);
    // Process the event
    
    res.status(200).send("Webhook processed!");
  } catch (error) {
    res.status(400).send("Invalid signature!");
  }
})

app.listen(7024, () => console.log("Running on port 7024"));

```

--------------------------------

### Install ModemPay Laravel Package

Source: https://docs.modempay.com/laravel/quickstart

Use Composer to install the ModemPay PHP package for Laravel. The package registers itself automatically.

```bash
composer require modempay/modempay-php
```

--------------------------------

### Create Invoice (cURL)

Source: https://docs.modempay.com/billing/invoices/api-reference

Creates and publishes an invoice immediately using cURL. This is a basic example showing essential fields for invoice creation.

```bash
curl -X POST https://api.modempay.com/v1/invoices \
    -H "Authorization: Bearer sk_test..." \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "amount": 5000,
        "customer_email": "customer@example.com",
        "customer_name": "John Doe",
        "due_date": "2025-12-31"
      }
    }'
```

--------------------------------

### Create a Customer

Source: https://docs.modempay.com/documentation/core/customers

Use the `modempay.customers.create()` method to add new customers. You can include their name, email, phone number, and an optional starting balance. The `distinct` option helps prevent duplicate entries.

```APIDOC
## Create a Customer

### Description
Creates a new customer profile with the provided details. Supports checking for existing customers to avoid duplicates.

### Method
`modempay.customers.create(params, options)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the customer.
- **email** (string) - Required - The email address of the customer.
- **phone** (string) - Optional - The phone number of the customer.
- **config** (object) - Optional - Configuration options.
  - **distinct** (boolean) - Optional - If true, checks for existing customers with matching fields to avoid duplicates. Defaults to false.

### Request Example
```typescript nodejs
const customer = await modempay.customers.create(
    { name: "Zypheron Kade", email: "zypheron.kade42@protonmail.com", phone: "7000001" },
    { distinct: true }
);
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the customer.
- **balance** (number) - The current balance of the customer.
- **name** (string) - The name of the customer.
- **email** (string) - The email address of the customer.
- **phone** (string) - The phone number of the customer.
- **business_id** (string) - The ID of the associated business.
- **account_id** (string) - The ID of the associated account.
- **test_mode** (boolean) - Indicates if the customer was created in test mode.
- **updatedAt** (string) - The timestamp when the customer was last updated.
- **createdAt** (string) - The timestamp when the customer was created.

#### Response Example
```json
{
  "id": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
  "balance": 0,
  "name": "Zypheron Kade",
  "email": "zypheron.kade42@protonmail.com",
  "phone": "7000001",
  "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
  "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
  "test_mode": true,
  "updatedAt": "2024-11-11T13:54:10.104Z",
  "createdAt": "2024-11-11T13:54:10.104Z"
}
```
```

--------------------------------

### Implement Webhook Event Listener

Source: https://docs.modempay.com/laravel/webhooks

Write the logic within the listener to process specific ModemPay events. This example shows handling `CHARGE_SUCCEEDED` and `CHARGE_FAILED` events.

```php
<?php

namespace App\Listeners;

use ModemPay\Laravel\Events\WebhookReceived;
use ModemPay\Types\EventType;

class HandleModemPayWebhook
{
    public function handle(WebhookReceived $event)
    {
        match($event->event->event) {
            EventType::CHARGE_SUCCEEDED => $this->handleSuccess($event),
            EventType::CHARGE_FAILED => $this->handleFailure($event),
            default => null,
        };
    }

    private function handleSuccess($event)
    {
        // Mark order as paid
    }

    private function handleFailure($event)
    {
        // Handle failed payment
    }
}

```

--------------------------------

### Create Payment Intent with Amount Only

Source: https://docs.modempay.com/documentation/payment-intents/create

Use this when you need to create a payment intent with only the amount specified. This is the most basic setup for a payment.

```javascript
const paymentIntent = await modempay.paymentIntents.create({ amount: 450 });
```

```python
payment_intent = modem_pay.payment_intents.create(params={\"amount\": 450})
```

```php
$payment_intent = $modemPay->paymentIntents()->create(['amount' => 450]);
```

```cURL
cURL -X POST "https://api.modempay.com/v1/payments" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <your_api_key>" \
    -d '{ \
      "data": { \
        "amount": 450, \
        "from_sdk": false \
      } \
    }'
```

--------------------------------

### Listen for Webhooks with Modem Pay CLI

Source: https://docs.modempay.com/documentation/core/webhook-cli

Create a secure public tunnel to forward webhook events to a local endpoint. This is intended for test environments only. The webhook signing secret will be displayed upon successful setup.

```bash
$ modempay listen --forward-url=http://localhost:3000/webhook  

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
```

--------------------------------

### Handle Webhooks in Flask (Python)

Source: https://docs.modempay.com/documentation/core/webhooks

This Python Flask example demonstrates how to validate and process ModemPay webhook events. It requires setting the MODEM_WEBHOOK_SECRET environment variable and initializing ModemPay with your API key.

```python
import os
from modempay import ModemPay
from flask import Flask, request, jsonify

modem_pay = ModemPay(api_key="YOUR_MODEM_PAY_API_KEY", config={"timeout": 20})

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    payload = request.get_json()
    signature = request.headers.get("x-modem-signature")
    secret = os.environ.get("MODEM_WEBHOOK_SECRET")

    try:
        event = modem_pay.webhooks.compose_event_details(payload, signature, secret)
        # Process the event
        if event["event"] == "customer.created":
            # Handle new customer logic
            pass
        elif event["event"] == "charge.succeeded":
            # Process successful payment
            pass
        # Add other cases as needed

        return "Webhook processed!", 200
    except Exception:
        return "Invalid signature!", 400


if __name__ == "__main__":
    app.run(port=3000, debug=True)

```

--------------------------------

### Integrating Modem Pay Button in React (Event Handling)

Source: https://docs.modempay.com/documentation/payments/drop-in

Attach event listeners to the `<modempay-button>` element in React using a `ref`. This example demonstrates listening for the `modempay:success` event and logging transaction details.

```jsx
import { useEffect, useRef } from "react";

export default function CheckoutButton() {
  const containerRef = useRef(null);

  useEffect(() => {
    const el = containerRef.current?.querySelector("modempay-button");
    if (!el) return;

    const onSuccess = (e) => {
      console.log("Transaction:", e.detail.transaction);
    };

    el.addEventListener("modempay:success", onSuccess);
    return () => el.removeEventListener("modempay:success", onSuccess);
  }, []);

  return (
    <div
      ref={containerRef}
      dangerouslySetInnerHTML={{
        __html: `<modempay-button
          merchant="pk_test_xxxx"
          amount="10"
        />`,
      }}
    />
  );
}
```

--------------------------------

### Using the Facade

Source: https://docs.modempay.com/laravel/usage

Demonstrates the basic usage of the Modem Pay facade for creating, listing, and retrieving payment intents.

```APIDOC
## Using the Facade

This section shows how to use the Modem Pay facade to interact with the API.

### Create Payment Intent
```php
use ModemPay\Laravel\Facades\ModemPay;

$payment = ModemPay::paymentIntents()->create([
    'amount' => 5000,
    'currency' => 'GMD',
]);
```

### List Payment Intents
```php
use ModemPay\Laravel\Facades\ModemPay;

$payments = ModemPay::paymentIntents()->list(['limit' => 10]);
```

### Retrieve Payment Intent
```php
use ModemPay\Laravel\Facades\ModemPay;

$payment = ModemPay::paymentIntents()->retrieve('hash');
```
```

--------------------------------

### Initialize Modem Pay SDK

Source: https://docs.modempay.com/documentation/installation

Instantiate the SDK with your secret API key to authenticate requests. Ensure your API key is kept secure and not exposed publicly.

```typescript
import ModemPay from "modem-pay";

const modempay = new ModemPay("YOUR_MODEM_PAY_API_KEY");

const intent = await modempay.paymentIntents.create({ amount: 450 });

console.log(intent.data.payment_link);
```

```python
from modempay import ModemPay

modem_pay = ModemPay(api_key="YOUR_MODEM_PAY_API_KEY")

intent = modem_pay.payment_intents.create(params={"amount": 450})

print(intent["data"]["payment_link"])
```

```php
use ModemPay\ModemPay;

$modemPay = new ModemPay('YOUR_MODEM_PAY_API_KEY');

$payment = $modemPay->paymentIntents()->create(['amount' => 450]);

echo $payment->data->payment_link;
```

--------------------------------

### Creating a Coupon

Source: https://docs.modempay.com/documentation/core/coupons

Use `modempay.coupons.create()` to create a coupon. Coupons can offer a fixed amount or percentage discount and support options like duration, redemption limits, and restrictions.

```APIDOC
## Creating a Coupon

Use `modempay.coupons.create()` to create a coupon. Coupons can offer a fixed amount or percentage discount and support options like duration, redemption limits, and restrictions.

**Example: Creating a 15% Off Coupon for a Market Promotion**

```typescript nodejs
async function createCoupon() {
  try {
    const coupon = await modempay.coupons.create({
      name: 'Market Fest 15% Off',
      percent_off: 15,
      duration: 'once',
      redeem_by: new Date('2025-06-30'),
      currency: 'GMD',
      restrictions: {
        first_time_transaction: false,
        minimum_amount: 100,
        minimum_amount_currency: 'GMD'
      }
    });
    console.log('Coupon created:', coupon);
  } catch (error) {
    console.error('Error creating coupon:', error);
  }
}
```

This creates a coupon offering 15% off for purchases of at least 100 GMD, valid until June 30, 2025, and redeemable once.

**Example: Creating a 50 GMD Off Coupon for Mobile Data**

```typescript nodejs
async function createDataCoupon() {
  try {
    const coupon = await modempay.coupons.create({
      name: 'MobileDataDiscount',
      amount_off: 50, 
      duration: 'forever',
      currency: 'GMD',
      restrictions: {
        first_time_transaction: true,
        minimum_amount: 200, 
        minimum_amount_currency: 'GMD'
      },
    });
    console.log('Coupon created:', coupon);
  } catch (error) {
    console.error('Error creating coupon:', error);
  }
}
```

This coupon gives 50 GMD off for first-time data bundle purchases of 200 GMD or more, with no expiry or redemption limit.

**Key Parameters**

* `name` : Descriptive name (e.g., "MarketFest").
* `percent_off` : Percentage discount (e.g., 15 for 15%). Use amount_off for fixed amounts.
* `currency` : Set to "GMD" for all amounts.
* `duration` : "once", "repeating", or "forever".
* `duration_in_months` : Required if duration is "repeating".
* `max_redemptions` : Maximum uses of the coupon.
* `redeem_by` : Expiry date.
* `restrictions` : Conditions like minimum_amount or first_time_transaction.
```

--------------------------------

### List All Sub-Accounts

Source: https://docs.modempay.com/documentation/split-payments/sub-accounts

Get a list of all sub-accounts associated with your business. Supports pagination and filtering by search term.

```typescript
const allSubAccounts = await modempay.subAccounts.list();
  console.log(allSubAccounts);
```

```python
all_sub_accounts = mp.sub_accounts.list()
  print(all_sub_accounts)
```

```cURL
curl -X GET https://api.modempay.com/v1/sub-accounts?term=""&limit=15&offset=0 \
    -H "Authorization: Bearer sk_test_..." \
    -H "Content-Type: application/json"
```

--------------------------------

### List Payment Intents

Source: https://docs.modempay.com/documentation/payment-intents/management

View a collection of recent Payment Intents to track activity or get an overview.

```APIDOC
## List Payment Intents

### Description
To view a collection of recent Payment Intents, use the `list` method. This is ideal for tracking activity, viewing recent payment attempts, or obtaining an overview of intents by status.

### Parameters
#### Query Parameters
- **limit** (number, optional) - The number of Payment Intents to retrieve (default is typically 10).

### Request Example
```bash
cURL -X GET "https://api.modempay.com/v1/payments?offset=0&limit=10"
  -H "Authorization: Bearer <your_api_key>"
```

### Response
#### Success Response (200)
- **data** (array) - An array of Payment Intent objects.
- **meta** (object) - Metadata about the list, including total count.

### Response Example
```json
{
  "data": [
    {
      "id": "pi_abc123",
      "status": "successful",
      "amount": 1000,
      "currency": "USD"
    }
  ],
  "meta": {
    "total": 31
  }
}
```
```

--------------------------------

### Initialize ModemPay Client

Source: https://docs.modempay.com/documentation/authentication

Instantiate the ModemPay client with your secret API key. This is typically done on the server side.

```javascript
import ModemPay from "modem-pay";

const modempay = new ModemPay("sk_test_b9596....4865");
```

```python
from modempay import ModemPay

modem_pay = ModemPay(api_key="sk_test_b9596....4865")
```

```php
use ModemPay\ModemPay;

$modemPay = new ModemPay('YOUR_MODEM_PAY_API_KEY');
```

--------------------------------

### List All Sub-Accounts

Source: https://docs.modempay.com/documentation/split-payments/sub-accounts

Get a list of all sub-accounts associated with your business. This is helpful for dashboards or automated scripts. Supports filtering and pagination.

```APIDOC
## List All Sub-Accounts

### Description
Get a list of all sub-accounts associated with your business. Supports filtering and pagination.

### Method
GET

### Endpoint
/v1/sub-accounts

### Parameters
#### Query Parameters
- **term** (string) - Optional - A search term to filter sub-accounts.
- **limit** (integer) - Optional - The maximum number of sub-accounts to return (default: 15).
- **offset** (integer) - Optional - The number of sub-accounts to skip (for pagination).

### Response
#### Success Response (200)
- **data** (array) - An array of sub-account objects.
  - Each object contains: **id**, **business_name**, **percentage**, **settlement_code**, **account_number**, **created_at**, **updated_at**.
- **has_more** (boolean) - Indicates if there are more results available.
- **total** (integer) - The total number of sub-accounts.
```

--------------------------------

### Error Response Example

Source: https://docs.modempay.com/billing/invoices/api-reference

This JSON structure illustrates a typical error response from the API, including a descriptive message and an error code.

```json
{
  "error": {
    "message": "Invalid email address",
    "code": "validation_error"
  }
}
```

--------------------------------

### Using Dependency Injection

Source: https://docs.modempay.com/laravel/usage

Illustrates how to inject the ModemPay service into your Laravel controllers for managing payments.

```APIDOC
## Using Dependency Injection

Inject Modem Pay into your controllers for easier access.

### Controller Example
```php
use ModemPay\ModemPay;
use Illuminate\Http\Request;

class PaymentController extends Controller
{
    public function __construct(private ModemPay $modemPay) {}

    public function create(Request $request)
    {
        $payment = $this->modemPay->paymentIntents()->create([
            'amount' => $request->amount,
            'currency' => 'GMD',
        ]);

        return redirect($payment->data->payment_link);
    }
}
```
```

--------------------------------

### Retrieve a Transaction by ID

Source: https://docs.modempay.com/api-reference/retrieve-a-transaction

Use this endpoint to get the details of a specific transaction. You need to provide the transaction ID in the URL path.

```APIDOC
## GET /v1/transactions/{transaction_id}

### Description
Retrieves the details of a specific transaction.

### Method
GET

### Endpoint
/v1/transactions/{transaction_id}

### Parameters
#### Path Parameters
- **transaction_id** (string) - Required - The unique identifier of the transaction (UUID format).

#### Header Parameters
- **X-No-Effect** (boolean) - Optional - Description not provided in source.

### Responses
#### Success Response (200)
- **Transaction** (object) - Description not provided in source.
  - **id** (string) - UUID format.
  - **amount** (number)
  - **currency** (string)
  - **status** (string)
  - **createdAt** (string) - Date-time format.
```

--------------------------------

### Create Simple Invoice with Percentage Discount

Source: https://docs.modempay.com/billing/invoices/types

Create a simple invoice with a percentage-based discount applied. The discount is calculated from the provided amount.

```typescript
const invoice = await modempay.invoices.create({
    amount: 5000,
    customer: "b7ca54db-a2ad-4153-8603-d8873dbffc2d",
    discount: {
      type: "percentage",
      amount: 20 // 20% discount
    }
  });

  // Calculation:
  // Subtotal: 5000
  // Discount: 1000 (20% of 5000) 
  // Total: 4000
```

--------------------------------

### List All Invoices with Pagination

Source: https://docs.modempay.com/billing/invoices/quickstart

Retrieve a paginated list of all invoices. Use `limit` and `offset` to control the number of results and starting point.

```typescript
const invoices = await modempay.invoices.list({
    limit: 20,
    offset: 0
  });

  console.log('Total invoices:', invoices.meta.total);
  console.log('Invoices:', invoices.data);
```

--------------------------------

### Check Payout Fees

Source: https://docs.modempay.com/documentation/payouts/fees

Use the `/v1/transfers/fees` endpoint to get an estimate of the transfer fee. Provide the amount, currency, and network to calculate the fee.

```APIDOC
## Check Payout Fees

### Description
This endpoint allows you to estimate the fee for a transfer before it is initiated. It helps in understanding the total cost associated with a payout.

### Method
POST

### Endpoint
/v1/transfers/fees

### Parameters
#### Request Body
- **amount** (number) - Required - The amount to be transferred.
- **currency** (string) - Required - The currency code (e.g., "GMD", "USD").
- **network** (string) - Required - The payment network used (e.g., "afrimoney", "wave").

### Request Example
```json
{
  "amount": 1000,
  "currency": "GMD",
  "network": "afrimoney"
}
```

### Response
#### Success Response (200)
- **fee** (number) - The fee for the transfer.
- **currency** (string) - The currency code of the fee (e.g., "GMD", "USD").
- **network** (string) - The payment network used for the transfer (e.g., "afrimoney", "wave").
- **amount** (number) - The total amount to be transferred.

### Response Example
```json
{
  "fee": 5,
  "currency": "GMD",
  "network": "afrimoney",
  "amount": 1000
}
```
```

--------------------------------

### Create a Simple Invoice

Source: https://docs.modempay.com/billing/invoices/quickstart

Create a basic invoice for a monthly subscription with essential details.

```APIDOC
## Create a Simple Invoice

### Description
Create a basic invoice for a monthly subscription with essential details.

### Method
```typescript
await modempay.invoices.create({
  amount: 250,
  customer_name: "John Doe",
  customer_email: "john@example.com",
  customer_phone: "+2203334444",
  due_date: "2025-12-31",
  notes: "Monthly Pro Plan Subscription - December 2025"
});
```
```

--------------------------------

### Create a Virtual Terminal

Source: https://docs.modempay.com/documentation/virtual-terminal

Use this to create a new virtual terminal. Provide a name and at least one WhatsApp number for notifications.

```shell
curl -X POST "https://api.modempay.com/v1/virtual-terminals" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <your_api_key>" \
    -d '{
      "name": "Counter 1",
      "whatsapp_numbers": ["+2207012345"]
    }'
```

```nodejs
import ModemPay from "modem-pay";

const modempay = new ModemPay("YOUR_SECRET_KEY");

const terminal = await modempay.virtualTerminals.create({
    name: "Counter 1",
    whatsapp_numbers: ["+2207012345"],
  });

console.log(terminal);
```

--------------------------------

### Create a Draft Invoice

Source: https://docs.modempay.com/billing/invoices/lifecycle

Create an invoice that starts in a draft state. The customer will not receive an email until the draft is published. This allows for review before sending.

```typescript
// Starts in draft state
const draft = await modempay.invoices.draft({
  amount: 2500,
  customer_email: "customer@example.com",
  customer_name: "Adama Jobe"
});
// State: draft, customer does NOT receive email
```

--------------------------------

### Check Payout Fee in Node.js

Source: https://docs.modempay.com/documentation/payouts/fees

Use the `transfers.fee` method to estimate the fee for a transfer. Provide the amount, currency, and network to get a fee estimate.

```typescript
import ModemPay from "modem-pay";

const modemPay = new ModemPay("sk_test_...");

const feeResponse = await modemPay.transfers.fee({
  amount: 1000,
  currency: "GMD",
  network: "afrimoney"
});

console.log(`Payout fee: ${feeResponse.fee} ${feeResponse.currency}`);
console.log(`Total amount: ${feeResponse.amount} ${feeResponse.currency}`);
```

--------------------------------

### Trigger Webhook Event with Modem Pay CLI

Source: https://docs.modempay.com/documentation/core/webhook-cli

Simulate a specific webhook event for testing purposes. Ensure the `listen` command is active to capture triggered events.

```bash
$ modempay trigger charge.succeeded 

🔧 Executing event: "charge.succeeded"
✅ Event "charge.succeeded" triggered successfully.
```

--------------------------------

### Create Payment Intent using Facade

Source: https://docs.modempay.com/laravel/usage

Use the ModemPay facade to create a new payment intent with specified amount and currency.

```php
use ModemPay\Laravel\Facades\ModemPay;

// Create payment
$payment = ModemPay::paymentIntents()->create([
    'amount' => 5000,
    'currency' => 'GMD',
]);
```

--------------------------------

### Publish ModemPay Configuration File

Source: https://docs.modempay.com/laravel/configuration

If you need to customize ModemPay settings, publish the configuration file using the Artisan command. This creates a config/modempay.php file.

```bash
php artisan vendor:publish --tag=modempay-config
```

```php
return [
    'api_key' => env('MODEMPAY_API_KEY'),
    'webhook_secret' => env('MODEMPAY_WEBHOOK_SECRET'),
];
```

--------------------------------

### Check Payout Fee in PHP

Source: https://docs.modempay.com/documentation/payouts/fees

Call the `transfers()->fee` method to get an estimate of the transfer fee. Ensure to include the amount, currency, and network in the request.

```php
use ModemPay\ModemPay;

$modemPay = new ModemPay('sk_test_...');

$fee_response = $modemPay->transfers()->fee([
    'amount' => 1000,
    'currency' => 'GMD',
    'network' => 'afrimoney',
]);

print_r($fee_response);
```

--------------------------------

### Example Payout Fee Response

Source: https://docs.modempay.com/documentation/payouts/fees

This JSON object represents a typical response from the transfer fee endpoint, detailing the calculated fee, its currency, the network used, and the total amount.

```json
{
  "fee": 5,
  "currency": "GMD",
  "network": "afrimoney",
  "amount": 1000
}
```

--------------------------------

### OpenAPI Specification for Retrieving a Transaction

Source: https://docs.modempay.com/api-reference/retrieve-a-transaction

This OpenAPI specification defines the GET /v1/transactions/{transaction_id} endpoint for retrieving transaction details. It includes request parameters, response schemas, and authentication requirements.

```yaml
openapi: 3.0.3
info:
  title: Modem Pay API
  description: Modem Pay public API for payments, transfers, customers, and transactions.
  version: 1.0.0
servers:
  - url: https://api.modempay.com
security:
  - BearerAuth: []
paths:
  /v1/transactions/{transaction_id}:
    get:
      summary: Retrieve a transaction
      operationId: getTransaction
      parameters:
        - name: transaction_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: X-No-Effect
          in: header
          schema:
            type: boolean
      responses:
        '200':
          description: Transaction retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
components:
  schemas:
    Transaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: number
        currency:
          type: string
        status:
          type: string
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Use your Modem Pay secret key.

        - **Test environment:** Use your `sk_test_...` key.

        - **Production environment:** Only use `sk_live_...` on your personal,
        secure machine. Do NOT share or commit your production keys.

```

--------------------------------

### Create Simple Invoice for SaaS Subscription

Source: https://docs.modempay.com/billing/invoices/types

Use this to create a simple invoice for a fixed monthly subscription. Ensure no line items are included.

```typescript
const invoice = await modempay.invoices.create({
    amount: 2500,
    customer_email: "user@modempay.com",
    customer_name: "Modem Pay Inc", 
    due_date: "2025-12-31",
    notes: "Pro Plan - December 2025"
  });
```

--------------------------------

### Create a 15% Off Coupon

Source: https://docs.modempay.com/documentation/core/coupons

Creates a coupon for a market promotion offering a percentage discount. This coupon has restrictions on minimum purchase amount and a specific expiry date.

```typescript
async function createCoupon() {
    try {
      const coupon = await modempay.coupons.create({
        name: 'Market Fest 15% Off',
        percent_off: 15,
        duration: 'once',
        redeem_by: new Date('2025-06-30'),
        currency: 'GMD',
        restrictions: {
          first_time_transaction: false,
          minimum_amount: 100,
          minimum_amount_currency: 'GMD'
        }
      });
      console.log('Coupon created:', coupon);
    } catch (error) {
      console.error('Error creating coupon:', error);
    }
  }
```

--------------------------------

### Handle Payment Success Webhook Event

Source: https://docs.modempay.com/billing/invoices/lifecycle

This example illustrates how to process the `paymentrequest.success` webhook event in your endpoint. Upon receiving this event, you can activate subscriptions, send receipts, and update internal records.

```typescript
// In your webhook endpoint
if (event.event === 'paymentrequest.success') {
  const invoice = event.payload;
  
  // Grant subscription access
  await activateSubscription(invoice.customer);
  
  // Send receipt
  await sendReceiptEmail(invoice);
  
  // Update internal records
  await recordPayment(invoice);
}
```

--------------------------------

### Integrating Modem Pay Button in React (Basic)

Source: https://docs.modempay.com/documentation/payments/drop-in

Use `dangerouslySetInnerHTML` to render the `<modempay-button>` Web Component within a React application. Ensure the Modem Pay script is loaded once, for example, in your `public/index.html`.

```jsx
export default function CheckoutButton() {
  return (
    <div
      dangerouslySetInnerHTML={{
        __html: `<modempay-button
          merchant="pk_test_xxxx"
          amount="10"
          currency="GMD"
          description="Order #1042"
        />`,
      }}
    />
  );
}
```

--------------------------------

### Initialize Payment Intent with Sub-account (cURL)

Source: https://docs.modempay.com/documentation/split-payments/initialize-payment

This cURL command demonstrates how to initialize a Payment Intent with a sub-account using the ModemPay API. Replace <your_api_key> with your actual API key.

```bash
cURL -X POST "https://api.modempay.com/v1/payments" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <your_api_key>" \
    -d '{ "data": { "amount": 450, "sub_account": "5bfcc08....810b", "from_sdk": false } }'
```

--------------------------------

### Create Webhook Controller

Source: https://docs.modempay.com/laravel/webhooks

Generate a controller to handle incoming webhook requests from ModemPay. This controller will validate and parse the event data.

```bash
php artisan make:controller WebhookController
```

--------------------------------

### Creating a Payment Intent with Amount and Customer

Source: https://docs.modempay.com/documentation/payment-intents/create

This scenario demonstrates creating a payment intent by specifying both the amount and the customer associated with the payment.

```APIDOC
## Create Payment Intent with Amount and Customer

### Description
Creates a payment intent with the specified amount and associates it with a given customer.

### Method
POST

### Endpoint
/v1/payments

### Parameters
#### Request Body
- **data** (object) - Required - The payload for creating the payment intent.
  - **amount** (number) - Required - The amount to be paid.
  - **customer** (string) - Required - The unique identifier of the customer.
  - **from_sdk** (boolean) - Optional - Indicates if the request is from an SDK.

### Request Example
```json
{
  "data": {
    "amount": 450,
    "customer": "d9bf8831-4db5-4a1c-8aa0-3de72492f330",
    "from_sdk": false
  }
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the operation was successful.
- **message** (string) - A message describing the result of the operation.
- **data** (object) - Contains details about the created payment intent.
  - **intent_secret** (string) - A secret identifier for the payment intent.
  - **payment_link** (string) - A URL where the customer can complete the payment.
  - **amount** (number) - The amount of the payment intent.
  - **currency** (string) - The currency of the payment intent.
  - **expires_at** (string) - The expiration date and time of the payment intent.
  - **status** (string) - The current status of the payment intent.

#### Response Example
```json
{
  "status": true,
  "message": "Payment intent created successfully. Please proceed to complete the payment.",
  "data": {
    "intent_secret": "8816a8e679d9df252fa80d09ebe21efaa3a8980cb053cb64afeed44c5df696f4",
    "payment_link": "https://test.checkout.modempay.com/6b63ccef-0232-4be1-b53d-be6823767874",
    "amount": 450,
    "currency": "GMD",
    "expires_at": "2025-02-13T12:31:15.601Z",
    "status": "requires_payment_method"
  }
}
```
```

--------------------------------

### Implement State-Based Invoice Logic

Source: https://docs.modempay.com/billing/invoices/lifecycle

Use a switch statement to execute different business logic based on the invoice's current status. This example shows handling 'not-paid', 'paid', and 'overdue' states.

```typescript
async function handleInvoiceStatus(invoice: Invoice) {
  switch (invoice.status) {
    case "not-paid":
      // Check if reminder needed
      if (shouldSendReminder(invoice)) {
        await modempay.invoices.sendReminder(invoice.id);
      }
      break;
      
    case "paid":
      // Grant access
      await activateSubscription(invoice.customer);
      break;
      
    case "overdue":
      // Suspend service
      await suspendSubscription(invoice.customer);
      
      // Start dunning process
      await startDunningCampaign(invoice);
      break;
  }
}
```

--------------------------------

### Login to Modem Pay CLI

Source: https://docs.modempay.com/documentation/core/webhook-cli

Authenticate with your Modem Pay account to obtain credentials for other CLI features. You will be prompted for your Merchant ID, email, and password.

```bash
$ modempay login 

✔ Please enter your Merchant ID (you can find this in your dashboard): › 2523017877
✔ Enter your Modem Pay email: › mercury@modempay.com
✔ Enter your password: › *******
✅ Login successful! Credentials saved.
```

--------------------------------

### Create Customer

Source: https://docs.modempay.com/api-reference/create-a-customer

This endpoint allows you to create a new customer in the Modem Pay system. You must provide at least the customer's name.

```APIDOC
## POST /v1/customers

### Description
Creates a new customer.

### Method
POST

### Endpoint
/v1/customers

### Headers
- **X-No-Effect** (boolean) - Optional

### Request Body
- **name** (string) - Required - The name of the customer.
- **email** (string) - Optional - The email address of the customer.
- **phone** (string) - Optional - The phone number of the customer.

### Request Example
```json
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "7000001"
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the created customer.
- **name** (string) - The name of the customer.
- **email** (string) - The email address of the customer.
- **phone** (string) - The phone number of the customer.

#### Response Example
```json
{
  "id": "cust_12345",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "7000001"
}
```
```

--------------------------------

### List Payment Intents using Facade

Source: https://docs.modempay.com/laravel/usage

Retrieve a list of payment intents using the ModemPay facade, with options for limiting results.

```php
use ModemPay\Laravel\Facades\ModemPay;

// List payments
$payments = ModemPay::paymentIntents()->list(['limit' => 10]);
```

--------------------------------

### Creating a Payment Intent with Amount, Customer, and Payment Methods

Source: https://docs.modempay.com/documentation/payment-intents/create

This snippet demonstrates how to create a payment intent by specifying the amount, associating it with a customer, and predefining the payment methods to be used.

```APIDOC
## Creating a Payment Intent with Amount, Customer, and Payment Methods

### Description
This scenario involves a more specific setup where you specify the amount, associate the intent with a customer, and predefine the payment methods the customer will use. This is useful when you want to guarantee specific methods of payment.

### Method
POST

### Endpoint
/v1/payments

### Request Body
- **amount** (integer) - Required - The amount for the payment.
- **customer** (string) - Required - The ID of the customer.
- **payment_methods** (array of strings) - Required - A list of accepted payment methods.

### Request Example (cURL)
```bash
cURL -X POST "https://api.modempay.com/v1/payments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_key>" \
  -d 
    {
      "data": {
        "amount": 450,
        "customer": "d9bf8831-4db5-4a1c-8aa0-3de72492f330",
        "payment_methods": ["card"],
        "from_sdk": false
      }
    }
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the payment intent.
- **amount** (integer) - The amount of the payment.
- **currency** (string) - The currency of the payment.
- **status** (string) - The current status of the payment intent.
```

--------------------------------

### Create a Virtual Terminal

Source: https://docs.modempay.com/documentation/virtual-terminal

Creates a new Virtual Terminal. You can specify a display name and a list of WhatsApp numbers to receive payment notifications.

```APIDOC
## Create a Virtual Terminal

### Description
Creates a new Virtual Terminal. You can specify a display name and a list of WhatsApp numbers to receive payment notifications.

### Method
POST

### Endpoint
/v1/virtual-terminals

### Parameters
#### Request Body
- **name** (string) - Required - Display name for the terminal
- **whatsapp_numbers** (string[]) - Required - Numbers that receive payment notifications

### Request Example
```json
{
  "name": "Counter 1",
  "whatsapp_numbers": ["+2207012345"]
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the terminal
- **name** (string) - Display name for the terminal
- **whatsapp_numbers** (string[]) - Numbers that receive payment notifications
- **active** (boolean) - Whether the terminal is active
- **created_at** (string) - Timestamp of creation

### Response Example
```json
{
  "id": "vt_abc123",
  "name": "Counter 1",
  "whatsapp_numbers": ["+2207012345"],
  "active": true,
  "created_at": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Create a Simple Invoice

Source: https://docs.modempay.com/billing/invoices/quickstart

Use this to create a basic invoice for a recurring subscription. The customer will automatically receive an email with a payment link.

```typescript
const invoice = await modempay.invoices.create({
    amount: 250,
    customer_name: "John Doe",
    customer_email: "john@example.com",
    customer_phone: "+2203334444",
    due_date: "2025-12-31",
    notes: "Monthly Pro Plan Subscription - December 2025"
  });

  console.log('Invoice created:', invoice.reference);
  console.log('Payment link:', invoice.payment_link);
```
Tokens:
Raw