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-payment
request.
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 5 months ago