Quickstart: Customer Balance

This guide walks through the most common billing model: creating a customer with a balance and handling the payment webhook when that balance is settled. This model is suited for merchants who track a single running balance per customer without needing separate accounts or individual bills.

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 a customer with a balance representing what they currently owe, in minor units.

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",
    "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 customer in future calls.

{
  "id": "bcus_H4jp6KnU5cPw263v1jyz4",
  "external_reference": "UCR1234567890",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "balance": 2000
}

Step 2: Present the balance for payment

With the customer created, present their balance for payment using Electronic Bill Presentment or a Payment Request.

Step 3: Handle the payment webhook

When payment is received against the customer balance, 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",
    "customer_id": "bcus_H4jp6KnU5cPw263v1jyz4"
  }
}

Use data.customer_id to identify which customer paid and data.amount to reconcile against their balance. Before processing, verify the event signature. See Webhook Verification. Respond with a 2xx status code to acknowledge receipt.

Next steps

Quickstart: Account Balance

Track balances across multiple sub-accounts within a customer.

Quickstart: Bill Amount Due

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

Electronic Bill Presentment

Present balances and bills to customers via a hosted payment page.

Uploading Bills

Ingest customer balances and bills in bulk via SFTP or file integration.

Common Operations

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

Getting Started

Collect

Stored Value

Billing

Webhooks

Changelog

Prerequisites

Step 1: Create a customer

Step 2: Present the balance for payment

Step 3: Handle the payment webhook

Next steps

Quickstart: Account Balance

Quickstart: Bill Amount Due

Electronic Bill Presentment

Uploading Bills

Common Operations

​Prerequisites

​Step 1: Create a customer

​Step 2: Present the balance for payment

​Step 3: Handle the payment webhook

​Next steps

Quickstart: Account Balance

Quickstart: Bill Amount Due

Electronic Bill Presentment

Uploading Bills

Common Operations

Prerequisites

Step 1: Create a customer

Step 2: Present the balance for payment

Step 3: Handle the payment webhook

Next steps