Charge a customer

Use POST /v3/receivable-payments to charge a customer for one or more invoices. See the POST /v3/receivable-payments API for more information.

Charging a customer follows a set of rules.

• Customer authorization: The customer authorizedToCharge field must be set as true for you to charge the customer for invoices. Set charge customer authorization with POST /v3/customers/{customerId}/charge-authorization.
• Customer bank account: A customer bank account is required for you to charge a customer. Create a customer bank account with POST /v3/customers/{customerId}/bank-accounts. See Create a customer bank account for more information.

Set charge customer authorization

In your POST /v3/customers/{customerId}/charge-authorization request, set the required authorizedToCharge field as true. This confirms that your organization is authorized to charge the customer for invoices.

Sample request

In this cURL example, the charge customer authorization is set.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/customers/{customerId}/charge-authorization' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "authorizedToCharge": true
}'

Charge the customer

In your POST /v3/receivable-payments request, set the required fields.

See the POST /v3/receivable-payments API for more information about the other fields you can set.

Sample request

In this cURL example, a customer (customerId) is charged for $79.98. The invoiceId is associated with the customer charge. Customer funding account details are added to provide the customer bank account source for the charge.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/receivable-payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "customerId": "{customer_id}",
  "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{customer_bank_account_id}"
  },

  "invoicePayments": [
  {
    "invoiceId": "{invoice_id01}",
    "amount": "79.98",
  }
],
"description": "Paperless Band Inv#20261225"
}'

Response

In the response, a BILL-generated received payment id is available. The value begins with 0rp. The listed invoice is marked as PAID.

{
  "id": "{received_payment_id}",
  "customerId": "{customer_id}",
  "paymentType": "BANK_ACCOUNT",
  "paymentDate": "2026-12-20",
  "amount": 79.98,
  "unappliedAmount": 0.00,
  "status": "PAID",
  "description": "Paperless Band Inv#20261225",
  "invoices": [
    {
      "id": "{invoice_id01}",
      "payments": [
        {
          "id": "{invoice_payment_id01}",
          "amount": 79.98,
          "status": "PAID",
          "date": "2026-12-20"
        }
      ]
    }
  ]
}

See the /v3/receivable-payments API for more information.