Skip to main content
This guide walks through the account balance model: creating a customer, creating one or more accounts under that customer each with their own balance, and handling the payment webhook. This model is suited for merchants who need to track balances separately per product, service, or cost centre within a single customer.

​
Prerequisites

  • A test API key. See Authentication.
  • A registered webhook endpoint. See Webhook Setup to register your URL and obtain your signing key.

​
Step 1: Create a customer

Create the top-level customer record. At this level, no balance is required. Balances are tracked on the accounts below. 
curl -X POST https://api.momentpay.net/billing/customers \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference": "UCR1234567890",
    "name": "John Doe",
    "email": "john.doe@example.com"
  }'
The response returns an id. Store this to reference the customer when creating accounts. 
{
  "id": "bcus_H4jp6KnU5cPw263v1jyz4",
  "external_reference": "UCR1234567890",
  "name": "John Doe",
  "email": "john.doe@example.com"
}

​
Step 2: Create an account

Create an account under the customer with a balance representing what is owed on this account. 
curl -X POST https://api.momentpay.net/billing/accounts \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "bcus_H4jp6KnU5cPw263v1jyz4",
    "external_reference": "UAR1234567890",
    "name": "Subscription Account",
    "currency": "ZAR",
    "balance": 2000
  }'
balance is specified in minor units. See Monetary Amounts for details.
The response returns an id. Store this to reference the account when presenting it for payment. 
{
  "id": "bacc_H4jp6KnU5cPw263v1jyz4",
  "external_reference": "UAR1234567890",
  "customer_id": "bcus_H4jp6KnU5cPw263v1jyz4",
  "name": "Subscription Account",
  "currency": "ZAR",
  "balance": 2000
}
The customer and account can be created in a single request.

Instead of passing a customer ID, pass a customer object with the same fields used in the create customer request.

Moment creates the customer first and then creates the account, returning both IDs in the response. See Create Account.

​
Step 3: Present the account balance for payment

Present the account balance for payment using Electronic Bill Presentment or a Payment Request.

​
Step 4: Handle the payment webhook

When payment is received against the account, Moment sends an obligation.amount_applied event. 
{
  "id": "evt_2341234567890abcdef",
  "type": "obligation.amount_applied",
  "data": {
    "id": "ob_N2a38DJQWPL8K4X42354234",
    "amount": 2000,
    "currency": "ZAR",
    "payment_id": "pay_1313235234843nmafdsa",
    "account_id": "bacc_H4jp6KnU5cPw263v1jyz4"
  }
}
Use data.account_id to identify which account received the payment and data.amount to reconcile against the account balance. Before processing, verify the event signature. See Webhook Verification. Respond with a 2xx status code to acknowledge receipt.

​
Next steps

Quickstart: Customer Balance

Track a single running balance directly on a customer.

Quickstart: Bill Amount Due

Raise a specific bill with an amount due and a due date.

Electronic Bill Presentment

Present account balances to customers via a hosted payment page.

Core Concepts

Understand how customers, accounts, and bills relate to each other.

Common Operations

Examples for updating customer balances, account balances, and bills.