Sign in

v1

latestOpenAPI 3.0.12026-07-24310590875.6 KB
receivable-payments

Charge a customer

Charge a customer for one or more invoices.

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.
post/v3/receivable-payments

Headers

sessionIdstring nullable

API session ID generated with /v3/login

Example:{{session_id}}
devKeystring nullable

Developer key generated with your BILL developer account

Example:{{developer_key}}

Request body

customerIdstring required

BILL-generated ID of the customer. The value begins with 0cu.

descriptionstring

Invoice payment description. This value is included in the check memo or in the bank descriptor for electronic payments.

paymentDatestring date

Received payment date. Funds are withdrawn from the customer bank account on this date.This value is in the yyyy-MM-dd format.

Example request

{
  "customerId": "{{customer_id}}",
  "fundingAccount": {
    "id": "{{customer_bank_account_id}}",
    "type": "BANK_ACCOUNT"
  },
  "description": "Invoice 202602 customer payment",
  "paymentDate": "2026-12-15",
  "invoicePayments": [
    {
      "invoiceId": "{{invoice_id}}",
      "amount": 100
    }
  ]
}

Response

Charge a customer response

idstring

BILL-generated ID of the received payment. The value begins with 0rp.

customerIdstring

BILL-generated ID of the customer. The value begins with 0cu.

descriptionstring

Invoice payment description. This value is included in the check memo or in the bank descriptor for electronic payments.

paymentDatestring date

Received payment date. Funds are withdrawn from the customer bank account on this date.

amountnumber required

Received payment amount. For a payment in an international currency (not USD), this value is in the local currency.

unappliedAmountnumber

Unapplied received payment amount. This value is available for an overpayment, double payment, or customer payment not currently linked to an invoice.

convenienceFeeAmountnumber

Convenience fee charged to the customer

receivablesType'CASH' | 'CHECK' | 'CREDIT_CARD' | 'ACH' | 'PAYPAL' | 'OTHER' | 'WALLET' | 'VIRTUAL_CARD' | 'UNDEFINED'

Received payment disbursement type.

status'PAID' | 'VOID' | 'SCHEDULED' | 'CANCELED' | 'ESCHEATED' | 'UNDEFINED'

Received payment status.

referenceNumberstring

Received payment reference number

onlinePaymentboolean

Information about how the received payment is recorded.

  • true: The payment is received with BILL
  • false: The payment is received outside BILL, and then recorded in BILL
createdTimestring date-time

Received payment created date and time

updatedTimestring date-time

Received payment updated date and time