Recording an AR payment
Use POST/v3/invoices/record-payment to record an invoice payment received outside your BILL system. Apply the recorded payment amount to one or more invoices for a customer. Any recorded unapplied amount is an overpayment and is available as a customer balance in your BILL system.
NOTE
The listed invoices must belong to the same customer in your
POST/v3/invoices/record-paymentrequest.
Set the required fields in your request.
| Field | Description |
|---|---|
paymentDate | Payment date. The value is in the yyyy-MM-dd format. |
paymentType | Payment type (CASH, CHECK, CREDIT_CARD, ACH, PAYPAL, or OTHER) |
amount | Payment amount |
invoices | List of invoices being paid. In the invoices array, set the required information.- id- amount |
See the /v3/invoices/record-payment API for more information about the other invoice fields you can set.
Sample request
In this cURL example, an AR payment of $100 is recorded. The paymentType is set as CREDIT_CARD. The invoices array lists two invoices ($50 and $30) to be paid. In the example, an additional $20 ($100 - $50 - $30) is recorded.
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/invoices/record-payment' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
"amount": "100",
"customerId": "{customer_id}",
"invoices": [
{
"amount": "50",
"id": "{invoice_id01}"
},
{
"amount": "30",
"id": "{invoice_id02}"
}
],
"paymentDate": "2024-12-20",
"paymentType": "CREDIT_CARD",
"description": "Accepted credit card payment in store"
}'
Response
In the response, a BILL-generated received payment id is available. The value begins with 0rp. The listed invoices are marked as PAID.
{
"id": "{received_payment_id}",
"customerId": "{customer_id}",
"paymentType": "CREDIT_CARD",
"paymentDate": "2024-12-20",
"amount": 100.00,
"unappliedAmount": 100.00,
"status": "PAID",
"description": "Accepted credit card payment in store",
"invoices": [
{
"id": "{invoice_id01}",
"payments": [
{
"id": "{invoice_payment_id01}",
"amount": 50.00,
"status": "PAID",
"date": "2024-12-20"
}
]
},
{
"id": "{invoice_id02}",
"payments": [
{
"id": "{invoice_payment_id02}",
"amount": 30.00,
"status": "PAID",
"date": "2024-12-20"
}
]
}
]
}
In this example, since an additional $20 is recorded, this $20 is added to the customer balance amount (available with GET /v3/customers/{customerId}).
Updated 7 months ago