Skip to main content

​
Create Invoice

Creates and publishes an invoice immediately. 
const invoice = await modempay.invoices.create({
  amount: 5000,
  customer_email: "[email protected]",
  customer_name: "John Doe",
  customer_phone: "+2203334444",
  line_items: [
    { item: "sku_001", quantity: 2, unit_price: 2500 }
  ],
  discount: { type: "percentage", amount: 10 },
  due_date: "2025-12-31",
  notes: "Monthly subscription",
  invoice_number: "INV-001",
  callback_url: "https://yourapp.com/callback",
  sub_account: "sub_123"
});

​
Parameters

ParameterTypeRequiredDescription
amountnumberYes*Total amount (set to 0 if line_items present)
customerstringNoCustomer ID
customer_emailstringNo**Customer email address
customer_namestringNo**Customer name
customer_phonestringNoCustomer phone number
line_itemsarrayNoArray of line item objects
discountobjectNoDiscount configuration
due_datestringNoDue date (ISO 8601 or YYYY-MM-DD)
notesstringNoAdditional notes
invoice_numberstring/numberNoCustom invoice number
callback_urlstringNoEvent notification webhook URL for invoice status updates
sub_accountstringNoSub-account identifier for split payment or revenue sharing
*Required if no line_items
**Required if no customer ID

​
Response

{
  "id": "c44cd39d-53f0-435f-8036-fefb8ad7b66e",
  "type": "professional",
  "status": "not-paid",
  "amount": 4500,
  "sub_total": 5000,
  "total": 4500,
  "currency": "GMD",
  "customer_email": "[email protected]",
  "payment_link": "https://test.checkout.modempay.com/invoice/...",
  "sent_date": "2025-11-24T10:30:00Z",
  "test_mode": true
}

​
Create Draft Invoice

Creates invoice without sending to customer.
nodejs
const draft = await modempay.invoices.draft({
  amount: 5000,
  customer_email: "[email protected]",
  customer_name: "Adama Jobe",
  due_date: "2025-12-31"
});

​
Parameters

Same as Create Invoice

​
Response

Same structure, but sent_date: null

​
Retrieve Invoice

Get invoice by ID.
nodejs
const invoice = await modempay.invoices.retrieve(
  "c44cd39d-53f0-435f-8036-fefb8ad7b66e"
);

​
Response

{
  "id": "c44cd39d-53f0-435f-8036-fefb8ad7b66e",
  "status": "paid",
  "amount": 5000,
  "paid_date": "2025-11-24T14:22:00Z",
  "reminder_count": 1,
  ...
}

​
Update Invoice

Modify existing invoice.
nodejs
const updated = await modempay.invoices.update(
  "c44cd39d-53f0-435f-8036-fefb8ad7b66e",
  {
    amount: 6000,
    notes: "Updated pricing"
  }
);

​
Parameters

Same as Create Invoice (all optional)
Updating published invoices may confuse customers. Use with caution.

​
Pay Invoice

Manually mark invoice as paid (offline payments).
nodejs
await modempay.invoices.pay(
  "c44cd39d-53f0-435f-8036-fefb8ad7b66e"
);

​
Response

Returns updated invoice with status: "paid"

​
Send Draft Invoice

Publish draft and notify customer.
nodejs
await modempay.invoices.sendDraftInvoice(
  "c44cd39d-53f0-435f-8036-fefb8ad7b66e"
);

​
Response

Returns updated invoice with status: "not-paid" and sent_date

​
Send Reminder

Send payment reminder to customer.
nodejs
await modempay.invoices.sendReminder(
  "c44cd39d-53f0-435f-8036-fefb8ad7b66e"
);
Increments reminder_count on invoice.

​
List Invoices

Retrieve paginated list of invoices.
nodejs
const invoices = await modempay.invoices.list({
  limit: 20,
  offset: 0
});

​
Parameters

ParameterTypeDefaultDescription
limitnumber10Results per page
offsetnumber0Skip N results

​
Response

{
  "data": [...],
  "meta": {
    "total": 150,
    "limit": 20,
    "offset": 0
  }
}

​
Types Reference

​
LineItem

{
  item: string;              // Required: Product SKU/ID
  quantity: number;          // Required: Quantity
  unit_price: number;        // Required: Price per unit
  total_price?: number;      // Auto-calculated
}

​
Discount

{
  type: "fixed" | "percentage";
  amount: number;  // Fixed amount or percentage value
}

​
Invoice Object

{
  id: string;
  reference: string;
  type: "simple" | "professional";
  status: "not-paid" | "paid" | "overdue";
  customer: string;
  customer_email?: string;
  customer_name?: string;
  customer_phone?: string;
  currency: string;
  business_id: string;
  merchant_name: string;
  account_id: string;
  amount: number;
  sub_total?: number;
  total?: number;
  discount?: Discount;
  line_items?: LineItem[];
  due_date?: string;
  invoice_number?: string | number;
  notes?: string;
  sent_date?: string;
  paid_date?: string;
  payment_link?: string;
  callback_url?: string;
  sub_account?: string;
  reminder_count: number;
  test_mode: boolean;
  createdAt: string;
  updatedAt: string;
}

​
Webhook Events

​
paymentrequest.success

Triggered when invoice is paid. 
{
  "event": "paymentrequest.success",
  "payload": {
    "id": "...",
    "status": "paid",
    "paid_date": "2025-11-24T14:22:00Z",
    ...
  }
}

​
invoice.overdue

Triggered when due date passes (production only). 
{
  "event": "invoice.overdue",
  "payload": {
    "id": "...",
    "status": "overdue",
    "due_date": "2025-11-30",
    ...
  }
}

​
Error Responses

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

​
Common Error Codes

  • validation_error - Invalid parameters
  • not_found - Invoice doesn’t exist
  • already_paid - Invoice already paid
  • authentication_error - Invalid API key
  • rate_limit_exceeded - Too many requests