Skip to main content
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.