Overview

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

Example #1: Create a Customer with a Balance

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
}

Example #2: Create a customer John Doe with a bill

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
}

Example #3: Create a customer John Doe with two accounts

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
}

Example #4: Create a customer with an account which has a bill associated with it

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
}

Example #5: Update the balance for an existing customer

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
}

Example #6: Update the amount paid by the customer against an existing bill

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
}

Example #7: Update the name of an existing customer and the metadata of a bill under that customer

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
}

Collect

Billing

Miscellaneous

Key Features

Benefits

Entities

1. Customers

2. Accounts

3. Bills

4. Relationships Between Entities

Use Cases

Step 1: Create a customer

Step 1: Create a bill under a new customer

Step 1: Create an account under a new customer

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

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

Step 1: Update the balance for an existing customer

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

Step 1: Update an customer

Step 2: Update the bill

Collect

Billing

Miscellaneous

​Key Features

​Benefits

​Entities

​1. Customers

​2. Accounts

​3. Bills

​4. Relationships Between Entities

​Use Cases

Key Features

Benefits

Entities

1. Customers

2. Accounts

3. Bills

4. Relationships Between Entities

Use Cases