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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
]
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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"
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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."
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
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
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.