BIbill
receivable-payments

Charge a customer

Changed on

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

Request

  • Base URL
    https://gateway.stage.bill.com/connect
  • URL
    https://gateway.stage.bill.com/connect/v3/receivable-payments
  • Auth
    none declared

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

Changes

  • 54edddceb0a5Revision changes
    • breaking

      the ///// response's property type changed from string to no type for status

    • warning

      removed the optional property ///// from the response with the status

    • warning

      removed the optional property ///// from the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added subschema #2 to the ///// response property allOf list for the response status