Modify agency bill payments

After an agency bill payment has been executed, you can update certain values on the payment. For example, you might want to change the amount or the payment instrument if the values were entered incorrectly. You can modify agency bill payments using Cloud API.

For information about modifying agency bill payments in the BillingCenter user interface, see Agency bill payments.

How BillingCenter handles agency bill payment modification

When you modify an agency bill payment, BillingCenter does not update values on the existing payment entity. Instead, it creates a brand new agency bill payment entity based on the original. Therefore, modifying a payment results in two payments in the BillingCenter database:
  • The original payment, with the modified field set to true. The original payment cannot be modified again, and BillingCenter preserves it only for record keeping.
  • The modifying payment, created as a new payment entity with values from the original payment and new values set during the modification. In Cloud API, modifying payments include a moneyBeingModified object, which associates the modifying payment with the original payment.

The BillingCenter user interface only shows the modifying payment, not the original payment. However, BillingCenter Cloud API returns both modifying and original payments when you call the GET /billing/v1/producers/{producerId}/ab-money-rcvds endpoint. See Querying for agency bill payments for more.

Modify an agency bill payment using Cloud API

Use the following endpoint to modify agency bill payments.
  • POST /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/modify

When you modify an agency bill payment using Cloud API, you can only change the payment itself, not the distribution. If the amount of the payment is changed, the difference is added to the producer’s unapplied fund.

Agency bill payments must be executed to be modified. They cannot be in the saved state or reversed state, and they cannot have been previously modified (you cannot modify an agency bill payment with modified set to true). Further, only select fields can be modified, such as amount, name, and payment instrument.

The following call demonstrates all the possible fields you can modify on an agency bill payment:

Command
POST /billing/v1/producers/bc:48/ab-money-rcvds/bc:1091/modify
Request body
{
    "data": {
        "attributes": {
            "amount": {
                "amount": "300",
                "currency": "usd"
            },
            "name": "Updated January payment",
            "description": "Entered one too many zeroes",
            "paymentInstrument": {
                "id": "bc:SvIIFL6cLwCgnBuL6kNeJ"
            },
            "receivedDate": "2024-01-02",
            "referenceNumber": "bc:434923408"
        }
    }
}

The request returns the modified payment. The modified payment has a different id than the original payment, because as explained above, it is a different entity in the database.