Skip to main content
The Billing APIs allows merchants to store and manage their customers, bills & accounts in the Moment ecosystem.

​
Key Features

  • High Availability & Low Latency – 99.99% uptime with optimized API performance.
  • Seamless Payments – Accept payments from Moment’s Channel Partners.
  • Flexible Customer & Billing Management – Supports multi-level structure: Customers → Accounts → Bills.

​
Benefits

  • Scalability – Expand globally with multi-currency support and diverse payment methods.
  • Simplicity – Manage customers, accounts, and bills effortlessly via a single API.
  • Efficiency – Reduce API calls with composite operations for faster workflows.
  • Reliability – 99.99% uptime ensures seamless transactions with low latency.

​
Entities

​
1. Customers

Customers are the top-level entities representing individual users or businesses.
  • A Customer can have a balance associated with it.
    • Negative balance → The customer has credit.
    • Positive balance → The customer owes that amount.
  • A Customer may have multiple Accounts (sub-customer entities).
  • A Customer can also have Bills directly associated with them.

​
2. Accounts

Accounts represent sub-customer entities within a Customer.
  • An Account can have a balance associated with it.
    • Negative balance → The customer has credit.
    • Positive balance → The customer owes that amount.
  • An Account can have multiple Bills associated with it.

​
3. Bills

Bills represent one-off payments that need to be collected.
  • A Bill must belong to either a Customer or an Account.
  • A Bill must have an amount_due and can optionally have a due_date.
  • Each Bill has a status field, which can be:
    • UNPAID → The bill has not been fully paid.
    • PAID → The bill has been fully paid.

​
4. Relationships Between Entities

  • Customer → Accounts: A Customer can have multiple Accounts.
  • Customer → Bills: A Customer can have multiple Bills.
  • Account → Bills: An Account can have multiple Bills.

​
Use Cases

​
Step 1: Create a customer

In this example, for a biller following the Customer model, we will create a new customer, John Doe, with an initial balance of ZAR 20.00.Endpoint : Create CustomerRequest Body:
{
	"external_reference": "CUS1234567890",
	"name": "John Doe",
	"currency": "ZAR",
	"balance": 2000
}

​
Step 1: Create a bill under a new customer

In this example, for a biller following the Bill model (customers with bills), we will create a customer John Doe with a bill with an amount due of ZAR 20.00.Endpoint : Create BillRequest Body:
{
	"customer": {
      "external_reference": "CUS1234567890",
      "name": "John Doe"
    },
    "external_reference": "BILL1234567890",
    "currency": "ZAR",
    "amount_due": 2000
}

​
Step 1: Create an account under a new customer

In this example, for a biller following the Account model, we will create a customer John Doe with one account: “Primary Account”. “Primary Account” has a balance to pay of ZAR 50.00 .Endpoint : Create AccountRequest Body:
  
{
	"customer": {
  		"external_reference": "CUS1234567890",
  		"name": "John Doe",
	},
	"external_reference": "ACC0001",
	"name": "Primary Account",
	"currency": "ZAR",
	"balance": 5000
}

​
Step 2: Create the second account under the previously created customer

Now we will create an account: “Secondary Account” for the same customer. “Secondary Account” has a balance to pay of ZAR 20.00 .Endpoint : Create AccountRequest Body:
   
{
	"customer": "CUS1234567890",
	"external_reference": "ACC0002",
 	"name": "Secondary Account",
 	"currency": "ZAR",
 	"balance": 2000
}

​
Step 1: Create a bill under a new account under a new customer

In this example, for a biller following the Bill model, we will create a customer John Doe with a Primary account which has a bill with an amount due of ZAR 20.00.Endpoint : Create BillRequest Body:
  
{
	"customer": {
    	"external_reference": "CUS1234567890",
      	"name": "John Doe"
    },
    "account": {
      	"external_reference": "ACC0001",
      	"name": "Primary"
    },
    "external_reference": "BILL0001",
    "currency": "ZAR",
    "amount_due": 2000
}

​
Step 1: Update the balance for an existing customer

In this example, we will update a customer with an new balance to pay of ZAR 50.00.Endpoint : Update CustomerRequest Body:
  
{
	"currency": "ZAR",
    "balance": 5000
}

​
Step 1: Update the amount paid by the customer against an existing bill

In this example, we will set the amount paid by the customer to ZAR 50.00 for an existing bill.Endpoint : Update BillRequest Body:
  
{
	"currency": "ZAR",
    "amount_paid": 5000
}

​
Step 1: Update an customer

In this example, we will update the customer’s name to Johnny Doe.Endpoint : Update CustomerRequest Body:
  
{
	"name": "Johnny Doe"
}

​
Step 2: Update the bill

Now we will update one of the customer’s bill to have received a payment of ZAR 20.00 by updating the value of the amount paid.Endpoint : Update BillRequest Body:
  
{
    "currency": "ZAR",
    "amount_paid": 2000
}