MENU navbar-image

Introduction

WegaPay payment gateway REST API v1. Collect payments, manage invoices, handle subscriptions, and more.

This documentation aims to provide all the information you need to work with our API.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Health Check

Check the API status.

API Status

Returns the current operational status of the API.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/status" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/status"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "status": "operational",
        "version": "v1",
        "name": "WegaPay"
    }
}
 

Request      

GET api/v1/status

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

Payments

Collect payments from customers and manage payment records.

Charge

requires authentication

Initiate a payment collection from a customer via a payment provider.

Example request:
curl --request POST \
    "http://wega.test/api/v1/payments/charge" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 500,
    \"currency\": \"KES\",
    \"payment_method\": \"mobile_money\",
    \"customer_phone\": \"254712345678\",
    \"customer_email\": \"john@example.com\",
    \"reference\": \"INV-2026-001\",
    \"description\": \"Monthly subscription\",
    \"callback_url\": \"https:\\/\\/yourapp.com\\/hooks\\/payment\",
    \"return_url\": \"https:\\/\\/yourapp.com\\/payment\\/success\",
    \"metadata\": []
}"
const url = new URL(
    "http://wega.test/api/v1/payments/charge"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 500,
    "currency": "KES",
    "payment_method": "mobile_money",
    "customer_phone": "254712345678",
    "customer_email": "john@example.com",
    "reference": "INV-2026-001",
    "description": "Monthly subscription",
    "callback_url": "https:\/\/yourapp.com\/hooks\/payment",
    "return_url": "https:\/\/yourapp.com\/payment\/success",
    "metadata": []
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "status": "pending",
        "provider": "mpesa",
        "tracking_id": "uuid",
        "provider_ref": null,
        "redirect_url": null,
        "error_message": null
    }
}
 

Example response (422):


{
    "success": false,
    "error": {
        "code": "unsupported_payment_method",
        "message": "No provider available for card in KES"
    }
}
 

Request      

POST api/v1/payments/charge

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

amount   number   

The amount to charge. Example: 500

currency   string   

ISO 4217 currency code (3 chars). Example: KES

payment_method   string   

Payment method: mobile_money or card. Example: mobile_money

customer_phone   string  optional  

Phone number (required for mobile_money). Example: 254712345678

customer_email   string  optional  

Email (required for card). Example: john@example.com

reference   string   

Your unique reference for this charge. Example: INV-2026-001

description   string  optional  

Optional description. Example: Monthly subscription

callback_url   string  optional  

URL to receive payment status updates. Example: https://yourapp.com/hooks/payment

return_url   string  optional  

URL to redirect customer after payment. Example: https://yourapp.com/payment/success

metadata   object  optional  

Optional key-value metadata.

List Payments

requires authentication

Retrieve a paginated list of payments for the authenticated merchant.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/payments?per_page=10" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/payments"
);

const params = {
    "per_page": "10",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "status": "completed",
            "amount": "100.00",
            "fee": "2.50",
            "total_amount": "102.50",
            "currency": "KES",
            "reference": "INV-001",
            "receipt_reference": "abc123",
            "details": null,
            "transaction_type": null,
            "created_at": "2026-02-22T10:00:00.000000Z",
            "updated_at": "2026-02-22T10:00:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}
 

Request      

GET api/v1/payments

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

per_page   integer  optional  

Number of results per page. Default: 20. Example: 10

Get Payment

requires authentication

Retrieve a single payment by its UUID.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/payments/550e8400-e29b-41d4-a716-446655440000" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/payments/550e8400-e29b-41d4-a716-446655440000"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "uuid",
        "status": "completed",
        "amount": "100.00",
        "fee": "2.50",
        "total_amount": "102.50",
        "currency": "KES",
        "reference": "INV-001",
        "receipt_reference": "abc123",
        "details": null,
        "transaction_type": null,
        "created_at": "2026-02-22T10:00:00.000000Z",
        "updated_at": "2026-02-22T10:00:00.000000Z"
    }
}
 

Request      

GET api/v1/payments/{uuid}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the payment. Example: 550e8400-e29b-41d4-a716-446655440000

Refund Payment

requires authentication

Initiate a refund for a completed payment.

Example request:
curl --request POST \
    "http://wega.test/api/v1/payments/550e8400-e29b-41d4-a716-446655440000/refund" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 100,
    \"reason\": \"Customer requested cancellation\"
}"
const url = new URL(
    "http://wega.test/api/v1/payments/550e8400-e29b-41d4-a716-446655440000/refund"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 100,
    "reason": "Customer requested cancellation"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "refund-uuid",
        "payment_id": "payment-uuid",
        "amount": "100.00",
        "currency": "KES",
        "status": "pending",
        "reason": "Customer requested cancellation",
        "created_at": "2026-02-22T10:00:00.000000Z"
    }
}
 

Example response (422):


{
    "success": false,
    "error": {
        "code": "refund_failed",
        "message": "Refund amount exceeds payment amount"
    }
}
 

Request      

POST api/v1/payments/{uuid}/refund

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the payment to refund. Example: 550e8400-e29b-41d4-a716-446655440000

Body Parameters

amount   number   

The amount to refund. Example: 100

reason   string  optional  

Optional reason for the refund. Example: Customer requested cancellation

Checkout Sessions

Create and manage hosted checkout sessions for collecting payments.

Create Checkout Session

requires authentication

Create a hosted checkout page that your customers can be redirected to.

Example request:
curl --request POST \
    "http://wega.test/api/v1/checkout/sessions" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 1500,
    \"currency\": \"KES\",
    \"success_url\": \"https:\\/\\/yourapp.com\\/success\",
    \"cancel_url\": \"https:\\/\\/yourapp.com\\/cancel\",
    \"callback_url\": \"https:\\/\\/yourapp.com\\/hooks\\/checkout\",
    \"payment_method_types\": [
        \"card\",
        \"mobile_money\"
    ],
    \"customer_email\": \"john@example.com\",
    \"customer_phone\": \"254712345678\",
    \"line_items\": [
        []
    ],
    \"metadata\": []
}"
const url = new URL(
    "http://wega.test/api/v1/checkout/sessions"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 1500,
    "currency": "KES",
    "success_url": "https:\/\/yourapp.com\/success",
    "cancel_url": "https:\/\/yourapp.com\/cancel",
    "callback_url": "https:\/\/yourapp.com\/hooks\/checkout",
    "payment_method_types": [
        "card",
        "mobile_money"
    ],
    "customer_email": "john@example.com",
    "customer_phone": "254712345678",
    "line_items": [
        []
    ],
    "metadata": []
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):


{
    "success": true,
    "data": {
        "id": "checkout-uuid",
        "url": "https://pay.wegapay.com/checkout/checkout-uuid",
        "amount": "1500.00",
        "currency": "KES",
        "status": "open",
        "expires_at": "2026-02-23T10:00:00.000000Z"
    }
}
 

Request      

POST api/v1/checkout/sessions

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

amount   number   

The payment amount. Example: 1500

currency   string   

ISO 4217 currency code (3 chars). Example: KES

success_url   string   

URL to redirect after successful payment. Example: https://yourapp.com/success

cancel_url   string  optional  

URL to redirect if customer cancels. Example: https://yourapp.com/cancel

callback_url   string  optional  

URL to receive payment webhook. Example: https://yourapp.com/hooks/checkout

payment_method_types   string[]  optional  

Accepted methods.

customer_email   string  optional  

Customer email. Example: john@example.com

customer_phone   string  optional  

Customer phone. Example: 254712345678

line_items   object[]  optional  

Line items for the checkout.

metadata   object  optional  

Optional key-value metadata.

Get Checkout Session

requires authentication

Retrieve a checkout session by its UUID.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/checkout/sessions/550e8400-e29b-41d4-a716-446655440000" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/checkout/sessions/550e8400-e29b-41d4-a716-446655440000"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "checkout-uuid",
        "url": "https://pay.wegapay.com/checkout/checkout-uuid",
        "amount": "1500.00",
        "currency": "KES",
        "status": "open",
        "expires_at": "2026-02-23T10:00:00.000000Z"
    }
}
 

Request      

GET api/v1/checkout/sessions/{uuid}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the checkout session. Example: 550e8400-e29b-41d4-a716-446655440000

Invoices

Create and manage invoices for your customers.

Create Invoice

requires authentication

Create a new invoice for a customer.

Example request:
curl --request POST \
    "http://wega.test/api/v1/invoices" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 5000,
    \"currency\": \"KES\",
    \"customer_name\": \"John Doe\",
    \"customer_email\": \"john@example.com\",
    \"customer_phone\": \"254712345678\",
    \"description\": \"Web development services\",
    \"due_date\": \"2026-03-01\",
    \"items\": [
        {
            \"description\": \"Design work\",
            \"amount\": 2500,
            \"quantity\": 2
        }
    ]
}"
const url = new URL(
    "http://wega.test/api/v1/invoices"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 5000,
    "currency": "KES",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "customer_phone": "254712345678",
    "description": "Web development services",
    "due_date": "2026-03-01",
    "items": [
        {
            "description": "Design work",
            "amount": 2500,
            "quantity": 2
        }
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):


{
    "success": true,
    "data": {
        "id": "invoice-uuid",
        "amount": "5000.00",
        "currency": "KES",
        "customer_name": "John Doe",
        "status": "open",
        "items": [],
        "created_at": "2026-02-22T10:00:00.000000Z"
    }
}
 

Request      

POST api/v1/invoices

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

amount   number   

The total invoice amount. Example: 5000

currency   string   

ISO 4217 currency code (3 chars). Example: KES

customer_name   string   

Customer name. Example: John Doe

customer_email   string  optional  

Customer email address. Example: john@example.com

customer_phone   string  optional  

Customer phone number. Example: 254712345678

description   string  optional  

Invoice description. Example: Web development services

due_date   string  optional  

Due date (YYYY-MM-DD). Example: 2026-03-01

items   object[]  optional  

Line items.

description   string   

Item description. Example: Design work

amount   number   

Item unit price. Example: 2500

quantity   integer   

Quantity. Example: 2

List Invoices

requires authentication

Retrieve a paginated list of invoices.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/invoices?per_page=10" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/invoices"
);

const params = {
    "per_page": "10",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "invoice-uuid",
            "amount": "5000.00",
            "currency": "KES",
            "customer_name": "John Doe",
            "status": "open",
            "due_date": "2026-03-01",
            "created_at": "2026-02-22T10:00:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}
 

Request      

GET api/v1/invoices

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

per_page   integer  optional  

Number of results per page. Default: 20. Example: 10

Get Invoice

requires authentication

Retrieve a single invoice by its UUID.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "invoice-uuid",
        "amount": "5000.00",
        "currency": "KES",
        "customer_name": "John Doe",
        "status": "open",
        "due_date": "2026-03-01",
        "items": [],
        "created_at": "2026-02-22T10:00:00.000000Z"
    }
}
 

Request      

GET api/v1/invoices/{uuid}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the invoice. Example: 550e8400-e29b-41d4-a716-446655440000

Payouts

Disburse funds to mobile money, paybill, or bank accounts.

Create Payout

requires authentication

Initiate a payout (disbursement) to a destination.

Example request:
curl --request POST \
    "http://wega.test/api/v1/payouts" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 1000,
    \"currency\": \"KES\",
    \"destination_type\": \"mobile_money\",
    \"destination_phone\": \"254712345678\",
    \"destination_paybill\": \"174379\",
    \"destination_account\": \"ACC001\",
    \"reference\": \"PAY-2026-001\",
    \"details\": \"Salary payment\"
}"
const url = new URL(
    "http://wega.test/api/v1/payouts"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "amount": 1000,
    "currency": "KES",
    "destination_type": "mobile_money",
    "destination_phone": "254712345678",
    "destination_paybill": "174379",
    "destination_account": "ACC001",
    "reference": "PAY-2026-001",
    "details": "Salary payment"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):


{
    "success": true,
    "data": {
        "id": "uuid",
        "status": "created",
        "amount": "1000.00",
        "currency": "KES",
        "reference": "PAY-2026-001",
        "created_at": "2026-02-22T10:00:00.000000Z"
    }
}
 

Example response (422):


{
    "success": false,
    "error": {
        "code": "unsupported_destination",
        "message": "Bank account payouts not yet supported"
    }
}
 

Request      

POST api/v1/payouts

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

amount   number   

The payout amount. Example: 1000

currency   string   

ISO 4217 currency code (3 chars). Example: KES

destination_type   string   

Destination type: mobile_money, paybill, or bank_account. Example: mobile_money

destination_phone   string  optional  

Phone number (required for mobile_money). Example: 254712345678

destination_paybill   string  optional  

Paybill number (required for paybill). Example: 174379

destination_account   string  optional  

Account number for paybill/bank. Example: ACC001

reference   string   

Your unique reference. Example: PAY-2026-001

details   string  optional  

Optional description. Example: Salary payment

Get Payout

requires authentication

Retrieve a payout by its UUID.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/payouts/550e8400-e29b-41d4-a716-446655440000" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/payouts/550e8400-e29b-41d4-a716-446655440000"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "uuid",
        "status": "completed",
        "amount": "1000.00",
        "currency": "KES",
        "reference": "PAY-2026-001",
        "created_at": "2026-02-22T10:00:00.000000Z"
    }
}
 

Request      

GET api/v1/payouts/{uuid}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the payout. Example: 550e8400-e29b-41d4-a716-446655440000

Wallets

View merchant wallet balances and transaction history.

List Wallets

requires authentication

Retrieve all wallets for the authenticated merchant.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/wallets" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/wallets"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Main Wallet",
            "slug": "main",
            "balance": 50000,
            "currency": "KES"
        }
    ]
}
 

Request      

GET api/v1/wallets

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Wallet Transactions

requires authentication

Retrieve paginated transactions for a specific wallet.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/wallets/1/transactions?per_page=10" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/wallets/1/transactions"
);

const params = {
    "per_page": "10",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "tx-uuid",
            "type": "deposit",
            "amount": 1000,
            "confirmed": true,
            "meta": {},
            "created_at": "2026-02-22T10:00:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}
 

Request      

GET api/v1/wallets/{id}/transactions

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

id   integer   

The wallet ID. Example: 1

Query Parameters

per_page   integer  optional  

Number of results per page. Default: 20. Example: 10

Plans

Create and manage subscription plans.

List Plans

requires authentication

Retrieve a paginated list of plans for the authenticated merchant.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/plans?per_page=10" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/plans"
);

const params = {
    "per_page": "10",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "plan-uuid",
            "name": "Pro",
            "slug": "pro",
            "description": "Pro monthly plan",
            "currency": "KES",
            "amount": "999.00",
            "billing_interval": "monthly",
            "billing_interval_count": 1,
            "trial_period_days": 14,
            "setup_fee": "0.00",
            "is_active": true,
            "metadata": null,
            "created_at": "2026-02-22T10:00:00.000000Z",
            "updated_at": "2026-02-22T10:00:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}
 

Request      

GET api/v1/plans

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

per_page   integer  optional  

Number of results per page. Default: 20. Example: 10

Create Plan

requires authentication

Create a new subscription plan.

Example request:
curl --request POST \
    "http://wega.test/api/v1/plans" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Pro Monthly\",
    \"slug\": \"pro-monthly\",
    \"description\": \"Professional plan billed monthly\",
    \"currency\": \"KES\",
    \"amount\": 999,
    \"billing_interval\": \"monthly\",
    \"billing_interval_count\": 1,
    \"trial_period_days\": 14,
    \"setup_fee\": 0,
    \"metadata\": []
}"
const url = new URL(
    "http://wega.test/api/v1/plans"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Pro Monthly",
    "slug": "pro-monthly",
    "description": "Professional plan billed monthly",
    "currency": "KES",
    "amount": 999,
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "trial_period_days": 14,
    "setup_fee": 0,
    "metadata": []
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):


{
    "success": true,
    "data": {
        "id": "plan-uuid",
        "name": "Pro Monthly",
        "slug": "pro-monthly",
        "currency": "KES",
        "amount": "999.00",
        "billing_interval": "monthly",
        "is_active": true,
        "created_at": "2026-02-22T10:00:00.000000Z"
    }
}
 

Example response (422):


{
    "success": false,
    "error": {
        "code": "slug_taken",
        "message": "A plan with this slug already exists.",
        "param": "slug"
    }
}
 

Request      

POST api/v1/plans

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

name   string   

Plan name. Example: Pro Monthly

slug   string   

URL-friendly identifier (unique per merchant). Example: pro-monthly

description   string  optional  

Plan description. Example: Professional plan billed monthly

currency   string   

ISO 4217 currency code (3 chars). Example: KES

amount   number   

Recurring charge amount. Example: 999

billing_interval   string   

One of: daily, weekly, monthly, quarterly, yearly. Example: monthly

billing_interval_count   integer  optional  

How many intervals between billings. Default: 1. Example: 1

trial_period_days   integer  optional  

Free trial days. Default: 0. Example: 14

setup_fee   number  optional  

One-time setup fee. Default: 0. Example: 0

metadata   object  optional  

Optional key-value metadata.

Get Plan

requires authentication

Retrieve a single plan by its UUID.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/plans/550e8400-e29b-41d4-a716-446655440000" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/plans/550e8400-e29b-41d4-a716-446655440000"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "plan-uuid",
        "name": "Pro Monthly",
        "slug": "pro-monthly",
        "currency": "KES",
        "amount": "999.00",
        "billing_interval": "monthly",
        "is_active": true
    }
}
 

Request      

GET api/v1/plans/{uuid}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the plan. Example: 550e8400-e29b-41d4-a716-446655440000

Update Plan

requires authentication

Update an existing plan. Only specified fields are changed.

Example request:
curl --request PUT \
    "http://wega.test/api/v1/plans/550e8400-e29b-41d4-a716-446655440000" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Pro Monthly Updated\",
    \"description\": \"Updated description\",
    \"amount\": 1499,
    \"trial_period_days\": 7,
    \"setup_fee\": 100,
    \"is_active\": true,
    \"metadata\": []
}"
const url = new URL(
    "http://wega.test/api/v1/plans/550e8400-e29b-41d4-a716-446655440000"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Pro Monthly Updated",
    "description": "Updated description",
    "amount": 1499,
    "trial_period_days": 7,
    "setup_fee": 100,
    "is_active": true,
    "metadata": []
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "plan-uuid",
        "name": "Pro Monthly Updated",
        "amount": "1499.00",
        "is_active": true
    }
}
 

Request      

PUT api/v1/plans/{uuid}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the plan. Example: 550e8400-e29b-41d4-a716-446655440000

Body Parameters

name   string  optional  

Plan name. Example: Pro Monthly Updated

description   string  optional  

Plan description. Example: Updated description

amount   number  optional  

Recurring amount. Example: 1499

trial_period_days   integer  optional  

Free trial days. Example: 7

setup_fee   number  optional  

One-time setup fee. Example: 100

is_active   boolean  optional  

Whether the plan is active. Example: true

metadata   object  optional  

Optional key-value metadata.

Subscriptions

Create and manage recurring subscriptions for your customers.

Create Subscription

requires authentication

Subscribe a customer to a plan. If the plan has a trial period, the subscription starts in trialing status.

Example request:
curl --request POST \
    "http://wega.test/api/v1/subscriptions" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"plan_id\": \"550e8400-e29b-41d4-a716-446655440000\",
    \"customer_email\": \"john@example.com\",
    \"customer_phone\": \"254712345678\",
    \"customer_name\": \"John Doe\",
    \"payment_method\": \"mobile_money\",
    \"payment_provider\": \"mpesa\",
    \"metadata\": []
}"
const url = new URL(
    "http://wega.test/api/v1/subscriptions"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "plan_id": "550e8400-e29b-41d4-a716-446655440000",
    "customer_email": "john@example.com",
    "customer_phone": "254712345678",
    "customer_name": "John Doe",
    "payment_method": "mobile_money",
    "payment_provider": "mpesa",
    "metadata": []
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):


{
    "success": true,
    "data": {
        "id": "sub-uuid",
        "plan": {
            "id": "plan-uuid",
            "name": "Pro"
        },
        "customer_email": "john@example.com",
        "status": "active",
        "current_period_start": "2026-02-22T10:00:00.000000Z",
        "current_period_end": "2026-03-22T10:00:00.000000Z",
        "created_at": "2026-02-22T10:00:00.000000Z"
    }
}
 

Example response (404):


{
    "success": false,
    "error": {
        "code": "plan_not_found",
        "message": "The specified plan was not found.",
        "param": "plan_id"
    }
}
 

Example response (422):


{
    "success": false,
    "error": {
        "code": "subscription_failed",
        "message": "Cannot subscribe to an inactive plan."
    }
}
 

Request      

POST api/v1/subscriptions

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Body Parameters

plan_id   string   

UUID of the plan to subscribe to. Example: 550e8400-e29b-41d4-a716-446655440000

customer_email   string  optional  

Customer email. Example: john@example.com

customer_phone   string  optional  

Customer phone. Example: 254712345678

customer_name   string  optional  

Customer name. Example: John Doe

payment_method   string  optional  

Payment method for renewals: mobile_money, card, bank_transfer. Example: mobile_money

payment_provider   string  optional  

Provider identifier for renewals (e.g. mpesa, stripe). Example: mpesa

metadata   object  optional  

Optional key-value metadata.

List Subscriptions

requires authentication

Retrieve a paginated list of subscriptions. Optionally filter by status.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/subscriptions?status=active&per_page=10" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/subscriptions"
);

const params = {
    "status": "active",
    "per_page": "10",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "sub-uuid",
            "plan": {
                "id": "plan-uuid",
                "name": "Pro",
                "amount": "999.00"
            },
            "customer_email": "john@example.com",
            "status": "active",
            "current_period_start": "2026-02-22T10:00:00.000000Z",
            "current_period_end": "2026-03-22T10:00:00.000000Z",
            "created_at": "2026-02-22T10:00:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}
 

Request      

GET api/v1/subscriptions

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

status   string  optional  

Filter by status: trialing, active, past_due, paused, canceled, expired. Example: active

per_page   integer  optional  

Number of results per page. Default: 20. Example: 10

Get Subscription

requires authentication

Retrieve a single subscription by its UUID.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440000" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440000"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "sub-uuid",
        "plan": {
            "id": "plan-uuid",
            "name": "Pro"
        },
        "customer_email": "john@example.com",
        "status": "active",
        "current_period_end": "2026-03-22T10:00:00.000000Z"
    }
}
 

Request      

GET api/v1/subscriptions/{uuid}

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the subscription. Example: 550e8400-e29b-41d4-a716-446655440000

Cancel Subscription

requires authentication

Cancel a subscription. By default, cancels at the end of the current billing period. Set immediately to true for immediate cancellation.

Example request:
curl --request POST \
    "http://wega.test/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440000/cancel" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"reason\": \"Customer requested cancellation\",
    \"immediately\": false
}"
const url = new URL(
    "http://wega.test/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440000/cancel"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "reason": "Customer requested cancellation",
    "immediately": false
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "sub-uuid",
        "status": "active",
        "canceled_at": "2026-02-22T10:00:00.000000Z",
        "ends_at": "2026-03-22T10:00:00.000000Z"
    }
}
 

Example response (422):


{
    "success": false,
    "error": {
        "code": "already_canceled",
        "message": "This subscription is already canceled or expired."
    }
}
 

Request      

POST api/v1/subscriptions/{uuid}/cancel

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the subscription. Example: 550e8400-e29b-41d4-a716-446655440000

Body Parameters

reason   string  optional  

Cancellation reason. Example: Customer requested cancellation

immediately   boolean  optional  

Cancel immediately instead of at period end. Default: false. Example: false

Pause Subscription

requires authentication

Pause an active subscription. Billing will stop until resumed.

Example request:
curl --request POST \
    "http://wega.test/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440000/pause" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440000/pause"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "sub-uuid",
        "status": "paused"
    }
}
 

Example response (422):


{
    "success": false,
    "error": {
        "code": "pause_failed",
        "message": "Only active subscriptions can be paused."
    }
}
 

Request      

POST api/v1/subscriptions/{uuid}/pause

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the subscription. Example: 550e8400-e29b-41d4-a716-446655440000

Resume Subscription

requires authentication

Resume a paused subscription. If the billing period has lapsed, a new period is started.

Example request:
curl --request POST \
    "http://wega.test/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440000/resume" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440000/resume"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": "sub-uuid",
        "status": "active"
    }
}
 

Example response (422):


{
    "success": false,
    "error": {
        "code": "resume_failed",
        "message": "Only paused subscriptions can be resumed."
    }
}
 

Request      

POST api/v1/subscriptions/{uuid}/resume

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

uuid   string   

The UUID of the subscription. Example: 550e8400-e29b-41d4-a716-446655440000

Webhooks

View webhook delivery events and their statuses.

List Webhook Events

requires authentication

Retrieve a paginated list of webhook events sent to your endpoints.

Example request:
curl --request GET \
    --get "http://wega.test/api/v1/webhooks/events?per_page=10" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "http://wega.test/api/v1/webhooks/events"
);

const params = {
    "per_page": "10",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "event-uuid",
            "event_type": "payment.completed",
            "status": "delivered",
            "endpoint_url": "https://yourapp.com/hooks",
            "attempts": 1,
            "response_status_code": 200,
            "created_at": "2026-02-22T10:00:00.000000Z",
            "last_attempt_at": "2026-02-22T10:00:05.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}
 

Request      

GET api/v1/webhooks/events

Headers

Authorization      

Example: Bearer {YOUR_AUTH_KEY}

Content-Type      

Example: application/json

Accept      

Example: application/json

Query Parameters

per_page   integer  optional  

Number of results per page. Default: 20. Example: 10