SMOO Pay API

https://smoopay.app/docs
Admin
SMOO Pay API allows programmatic acceptance of M-Pesa and e-Mola payments in Mozambique, enabling...
Tokens:4,957
Snippets:43
Trust Score:2.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### List Charges Request

Source: https://smoopay.app/docs

Example of a basic GET request to list charges.

```bash
curl https://smoopay.app/api/v1/charges \
  -H "Authorization: Bearer sk_live_your_api_key_here"
```

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

### Ad platform destination URL examples

Source: https://smoopay.app/docs

Standard URL structures for tracking campaigns across different advertising platforms.

```text
Facebook / Instagram:
https://smoopay.app/pay/SEVEN?utm_source=facebook&utm_medium=paid&utm_campaign=summer-2026

Google Ads:
https://smoopay.app/pay/SEVEN?utm_source=google&utm_medium=cpc&utm_campaign=brand

Email / WhatsApp:
https://smoopay.app/pay/SEVEN?utm_source=email&utm_medium=newsletter&utm_campaign=launch
```

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

### Get Charge Details with cURL

Source: https://smoopay.app/docs

Fetches full details for a specific charge using its unique ID.

```bash
curl https://smoopay.app/api/v1/charges/cLr8x3kWpN2mYvBq \
  -H "Authorization: Bearer sk_live_your_api_key"
```

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

### Verify Webhook Signatures in Node.js

Source: https://smoopay.app/docs

Implementation for verifying the X-Smoo-Signature header using HMAC-SHA256 and an Express middleware example.

```javascript
const crypto = require("crypto");

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express example
app.post("/webhooks/smoo", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-smoo-signature"];
  if (!verifyWebhook(req.body, signature, process.env.SMOO_WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const { event, data } = JSON.parse(req.body);

  switch (event) {
    case "charge.completed":
      // Fulfil the order
      console.log("Payment completed:", data.id);
      break;
    case "charge.failed":
      // Notify your customer
      console.log("Payment failed:", data.id, data.failure_reason);
      break;
  }

  res.status(200).send("OK");
});
```

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

### GET /api/v1/charges

Source: https://smoopay.app/docs

Retrieve a paginated list of charges.

```APIDOC
## GET /api/v1/charges

### Description
Returns a paginated list of your charges, sorted by creation date (newest first).

### Method
GET

### Endpoint
/api/v1/charges

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by status: PENDING, COMPLETED, FAILED, CANCELLED, EXPIRED.
- **limit** (number) - Optional - Max results per page (1-100, default 20).
- **cursor** (string) - Optional - Charge ID for cursor-based pagination.

### Response
#### Success Response (200)
- **data** (array) - List of charges.
- **cursor** (string) - Cursor for next page.
- **has_more** (boolean) - Whether more results exist.
```

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

### Charge Cancellation Response

Source: https://smoopay.app/docs

Example JSON response returned after a successful charge cancellation request.

```json
{
  "id": "dPq4y7nRsT5kJwAm",
  "status": "CANCELLED",
  "amount": 250.00,
  "currency": "MZN",
  "cancelled_at": "2025-06-16T15:00:00.000Z"
}
```

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

### GET /api/v1/charges/:id

Source: https://smoopay.app/docs

Retrieve details of a specific charge.

```APIDOC
## GET /api/v1/charges/:id

### Description
Retrieve the full details of a specific charge by its ID.

### Method
GET

### Endpoint
/api/v1/charges/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the charge.
```

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

### Create Direct Payment Charge

Source: https://smoopay.app/docs

Initiates a direct payment via STK push. Requires customer_phone and provider fields.

```bash
curl -X POST https://smoopay.app/api/v1/charges \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "title": "Premium Plan",
    "customer_phone": "841234567",
    "provider": "MPESA",
    "callback_url": "https://your-server.com/webhooks/smoo",
    "metadata": { "user_id": "abc123" }
  }'
```

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

### Create a Charge with JavaScript

Source: https://smoopay.app/docs

Uses the fetch API to create a new charge. Requires a valid live API key in the Authorization header.

```javascript
const response = await fetch(
  "https://smoopay.app/api/v1/charges",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 500.0,
      title: "Annual subscription",
      customer_phone: "861234567",
      provider: "EMOLA",
      callback_url: "https://your-server.com/webhooks/smoo",
      metadata: { plan: "annual" },
    }),
  }
);

const charge = await response.json();
console.log(charge.id, charge.status);
```

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

### Create Checkout URL Charge

Source: https://smoopay.app/docs

Initiates a payment by generating a checkout URL. Omit phone and provider to use this mode.

```bash
curl -X POST https://smoopay.app/api/v1/charges \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "title": "Course Access",
    "callback_url": "https://your-server.com/webhooks/smoo"
  }'
```

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

### Test Webhook Endpoint

Source: https://smoopay.app/docs

Command to trigger a test.ping event to the configured webhook URL.

```bash
curl -X POST https://smoopay.app/api/v1/webhooks/test \
  -H "Authorization: Bearer sk_live_your_api_key"
```

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

### POST /api/v1/charges

Source: https://smoopay.app/docs

Create a new payment charge.

```APIDOC
## POST /api/v1/charges

### Description
Creates a new payment charge.

### Method
POST

### Endpoint
/api/v1/charges

### Request Body
- **amount** (number) - Required - The charge amount.
- **title** (string) - Required - Title of the charge.
- **customer_phone** (string) - Required - Customer phone number.
- **provider** (string) - Required - Payment provider (e.g., EMOLA).
- **callback_url** (string) - Optional - URL for webhooks.
- **metadata** (object) - Optional - Custom metadata.

### Request Example
{
  "amount": 500.0,
  "title": "Annual subscription",
  "customer_phone": "861234567",
  "provider": "EMOLA",
  "callback_url": "https://your-server.com/webhooks/smoo",
  "metadata": { "plan": "annual" }
}
```

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

### Manage SmooPay Charges with Node.js

Source: https://smoopay.app/docs

A collection of asynchronous functions to create, retrieve, list, and cancel charges via the SmooPay API. Requires a valid API key and base URL configuration.

```javascript
const SMOO_API_KEY = "sk_live_your_api_key";
const BASE_URL = "https://smoopay.app/api/v1";

// Create a direct M-Pesa charge
async function createDirectCharge() {
  const res = await fetch(BASE_URL + "/charges", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + SMOO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 350.0,
      title: "Monthly subscription",
      customer_phone: "851234567",
      provider: "MPESA",
      callback_url: "https://your-server.com/webhooks/smoo",
      metadata: { customer_id: "cust_42" },
    }),
  });
  return res.json();
}

// Create a checkout URL (customer picks provider)
async function createCheckout() {
  const res = await fetch(BASE_URL + "/charges", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + SMOO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 1200.0,
      title: "E-commerce order #1042",
      redirect_url: "https://your-store.com/order/1042/thank-you",
      callback_url: "https://your-server.com/webhooks/smoo",
    }),
  });
  const charge = await res.json();
  // Redirect your customer to charge.checkout_url
  return charge;
}

// Get charge details
async function getCharge(chargeId) {
  const res = await fetch(BASE_URL + "/charges/" + chargeId, {
    headers: { Authorization: "Bearer " + SMOO_API_KEY },
  });
  return res.json();
}

// List completed charges
async function listCompletedCharges() {
  const res = await fetch(BASE_URL + "/charges?status=COMPLETED&limit=20", {
    headers: { Authorization: "Bearer " + SMOO_API_KEY },
  });
  return res.json();
}

// Cancel a pending charge
async function cancelCharge(chargeId) {
  const res = await fetch(BASE_URL + "/charges/" + chargeId + "/cancel", {
    method: "POST",
    headers: { Authorization: "Bearer " + SMOO_API_KEY },
  });
  return res.json();
}
```

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

### POST /api/v1/webhooks/test

Source: https://smoopay.app/docs

Fires a test.ping event to your configured webhook URL to verify that your server is receiving events correctly.

```APIDOC
## POST /api/v1/webhooks/test

### Description
Fires a test.ping event to your configured webhook URL. Returns immediately with the delivery status.

### Method
POST

### Endpoint
/api/v1/webhooks/test

### Request Example
curl -X POST https://smoopay.app/api/v1/webhooks/test \
  -H "Authorization: Bearer sk_live_your_api_key"
```

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

### POST /api/v1/charges

Source: https://smoopay.app/docs

Creates a new payment charge. Supports direct payments via STK push (when phone and provider are provided) or hosted checkout URLs.

```APIDOC
## POST /api/v1/charges

### Description
Creates a new payment charge. Two modes are available: Direct payment (requires customer_phone and provider) or Checkout URL (omitting phone and provider returns a checkout_url).

### Method
POST

### Endpoint
https://smoopay.app/api/v1/charges

### Parameters
#### Request Body
- **amount** (number) - Required - Amount in MZN. Must be a positive number.
- **title** (string) - Required - Payment title or product name.
- **description** (string) - Optional - Optional description for the payment.
- **customer_phone** (string) - Optional - Customer phone number. Triggers direct payment when paired with provider.
- **provider** (string) - Optional - Payment provider ("MPESA" or "EMOLA"). Required when customer_phone is set.
- **callback_url** (string) - Optional - HTTPS URL for webhook notifications on status change.
- **redirect_url** (string) - Optional - URL to redirect the customer after completing checkout.
- **metadata** (object) - Optional - Arbitrary key-value pairs stored with the charge.

#### Request Headers
- **Authorization** (string) - Required - Bearer token with your API key.
- **Content-Type** (string) - Required - Must be application/json.
- **Idempotency-Key** (string) - Optional - Unique key to prevent duplicate charges.

### Request Example
{
  "amount": 150.00,
  "title": "Premium Plan",
  "customer_phone": "841234567",
  "provider": "MPESA",
  "callback_url": "https://your-server.com/webhooks/smoo",
  "metadata": { "user_id": "abc123" }
}

### Response
#### Success Response (200)
- **id** (string) - Unique charge identifier.
- **status** (string) - Current status of the charge.
- **amount** (number) - Amount charged.
- **currency** (string) - Currency code (MZN).
- **provider** (string) - Payment provider used.
- **transaction_id** (string) - Provider transaction reference.
- **checkout_url** (string) - URL for customer checkout (if applicable).

#### Response Example
{
  "id": "cLr8x3kWpN2mYvBq",
  "status": "COMPLETED",
  "amount": 150.00,
  "currency": "MZN",
  "provider": "MPESA",
  "transaction_id": "tx_7f3a9c1e"
}
```

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

### POST /api/v1/charges

Source: https://smoopay.app/docs

Creates a new payment charge for a customer using a specified mobile money provider.

```APIDOC
## POST /api/v1/charges

### Description
Creates a charge via the server to initiate an STK push to the customer's mobile device.

### Method
POST

### Endpoint
/api/v1/charges

### Parameters
#### Request Body
- **phone** (string) - Required - The customer's phone number.
- **provider** (string) - Required - The mobile money provider (e.g., 'MPESA' or 'EMOLA').
- **amount** (number) - Required - The transaction amount in MZN.
- **callback_url** (string) - Required - The URL to receive payment status webhooks.
```

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

### List Charges with cURL

Source: https://smoopay.app/docs

Retrieves a paginated list of charges. Supports filtering by status and limiting results.

```bash
curl "https://smoopay.app/api/v1/charges?status=COMPLETED&limit=10" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

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

### Forward UTMs to checkout via HTML

Source: https://smoopay.app/docs

Inject this script on your landing page to automatically append UTM parameters and click IDs to links pointing to the SMOO checkout.

```html
<!-- On the page that links to your SMOO checkout -->
<script>
  (function () {
    var src = new URLSearchParams(window.location.search);
    var keep = ["utm_source","utm_medium","utm_campaign","utm_content","utm_term","fbclid","gclid"];
    document.querySelectorAll('a[href*="smoopay.app"]').forEach(function (a) {
      try {
        var u = new URL(a.href);
        keep.forEach(function (k) {
          var v = src.get(k);
          if (v && !u.searchParams.get(k)) u.searchParams.set(k, v);
        });
        a.href = u.toString();
      } catch (_) {}
    });
  })();
</script>
```

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

### Set Authorization Header

Source: https://smoopay.app/docs

Format for the Authorization header required in all API requests.

```text
Authorization: Bearer sk_live_xxxxx
```

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

### Direct Payment Response

Source: https://smoopay.app/docs

JSON response structure for a successful direct payment charge.

```json
{
  "id": "cLr8x3kWpN2mYvBq",
  "status": "COMPLETED",
  "amount": 150.00,
  "currency": "MZN",
  "provider": "MPESA",
  "transaction_id": "tx_7f3a9c1e"
}
```

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

### Forward UTMs to checkout via JavaScript

Source: https://smoopay.app/docs

Use this function to programmatically redirect users to the checkout while preserving attribution parameters.

```javascript
function goToCheckout(slug) {
  var dest = new URL("https://smoopay.app/pay/" + slug);
  var src = new URLSearchParams(window.location.search);
  ["utm_source","utm_medium","utm_campaign","utm_content","utm_term","fbclid","gclid"]
    .forEach(function (k) {
      var v = src.get(k);
      if (v) dest.searchParams.set(k, v);
    });
  window.location = dest.toString();
}
```

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

### Checkout URL Response

Source: https://smoopay.app/docs

JSON response structure containing the checkout URL for the customer.

```json
{
  "id": "dPq4y7nRsT5kJwAm",
  "status": "PENDING",
  "amount": 250.00,
  "currency": "MZN",
  "checkout_url": "https://smoopay.app/pay/charge/dPq4y7nRsT5kJwAm"
}
```

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

### Webhook Event Payload

Source: https://smoopay.app/docs

Standard JSON structure for webhook events sent to the configured callback URL.

```json
{
  "event": "charge.completed",
  "data": {
    "id": "cLr8x3kWpN2mYvBq",
    "status": "COMPLETED",
    "amount": 150.00,
    "currency": "MZN",
    "provider": "MPESA",
    "transaction_id": "tx_7f3a9c1e",
    "metadata": { "user_id": "abc123" }
  },
  "timestamp": "2025-06-15T10:30:05.000Z"
}
```

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

### Cancel a Charge with cURL

Source: https://smoopay.app/docs

Cancels a PENDING charge to prevent further payment attempts.

```bash
curl -X POST https://smoopay.app/api/v1/charges/dPq4y7nRsT5kJwAm/cancel \
  -H "Authorization: Bearer sk_live_your_api_key"
```

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

### POST /api/v1/charges/:id/cancel

Source: https://smoopay.app/docs

Cancel a pending charge.

```APIDOC
## POST /api/v1/charges/:id/cancel

### Description
Cancels a charge that is still in PENDING status.

### Method
POST

### Endpoint
/api/v1/charges/:id/cancel

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the charge.
```

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

### API error response format

Source: https://smoopay.app/docs

The standard JSON structure returned by the API when a request fails.

```json
{
  "error": "amount is required and must be a positive number"
}
```

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

### PATCH /api/v1/charges/:id

Source: https://smoopay.app/docs

Update a pending charge.

```APIDOC
## PATCH /api/v1/charges/:id

### Description
Update a charge that is still in PENDING status. You can modify the metadata and expiration time.

### Method
PATCH

### Endpoint
/api/v1/charges/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the charge.

#### Request Body
- **metadata** (object) - Optional - New metadata object.
- **expires_at** (string) - Optional - ISO 8601 timestamp for expiration.
```

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

### Update a Pending Charge with cURL

Source: https://smoopay.app/docs

Modifies metadata or expiration time for a charge. Only applicable to charges with PENDING status.

```bash
curl -X PATCH https://smoopay.app/api/v1/charges/dPq4y7nRsT5kJwAm \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "order_id": "ORD-2025-100", "note": "Updated by admin" },
    "expires_at": "2025-07-01T00:00:00.000Z"
  }'
```
Tokens:
Raw