Create and distribute agency bill payments

Agency bill payments can be entered into BillingCenter using the following endpoint:
  • POST /billing/v1/producers/{producerId}/ab-money-rcvds

When creating an agency bill payment through Cloud API, you can either distribute it immediately, or you can enter it without distribution and manually distribute it later through the BillingCenter user interface. Whether the payment is distributed immediately or not depends on the body of the POST request. Both of these scenarios are described in the following sections.

For more on agency bill distributions in BillingCenter, see the BillingCenter Application Guide.

Create an agency bill payment without distribution

To create an agency bill payment without distribution, the following fields are required:

Field Type Description
amount MonetaryAmount object The net amount of the agency bill payment.
currency Typekey reference to the Currency typelist The currency of the payment.
paymentInstrument Object containing a simple reference to the payment instrument’s id The payment instrument used to make the payment. Must be cash, check, or a non-universal payment instrument associated with the producer. See Producer payment instruments.
receivedDate String The date the payment was received, in the format YYYY-MM-DD.

The following example request creates a $200 payment. Because no distribution is specified, $200 is added to the producer’s unapplied fund.

Command

POST /billing/v1/producers/bc:423/ab-money-rcvds
Request body
{
  "data": {
    "attributes": {
      "amount": {
        "amount": "200",
        "currency": "usd"
      },
      "currency": {
        "code": "usd"
      },
      "paymentInstrument": {
        "id": "bc:Sad-gdQzXPb79g-_vKMph"
      },
      "receivedDate": "2024-10-10"
    }
  }
}

Create an agency bill payment with distribution

To create a payment and distribute it, you must include an additional agencyCyclePayment object in the POST request. This object has the following required fields:

  • currency, a typekey reference
  • Either agencyPaymentItems or agencySuspPmntItems or both—both are arrays of objects
Note: This topic only discusses agency payment items, which are used to distribute funds to invoice items. You can also include agency bill suspense payment items using the agencySuspPmntItems object. For information on agency bill suspense items in Cloud API, see Agency bill suspense items.

Each object in the agencyPaymentItems array specifies distribution for a single invoice item. The following fields are required for each object in the agencyPaymentItems array:

Field Type Description
invoiceItem Object containing a simple reference to an invoice item’s id The id of the target invoice item.
commissionAmountToApply Monetary amount object The commission that the producer withholds for that invoice item.
grossAmountToApply Monetary amount object The gross amount that will be applied to that invoice item.
currency Typekey reference to the Currency typelist The currency of the invoice item.
disposition Typekey reference to the DistItemDisposition typelist The action BillingCenter takes to address invoice items that have been underpaid or overpaid, such as creating exceptions or writing off the difference. See Underpaying invoice items in the Cloud API Developer Guide for an overview of how the different values affect behavior.

Finding the gross and commission amounts due for an invoice item

You can find the gross and commission due on an invoice item using the GET /billing/v1/charges/{chargeId}/invoice-items/{invoiceItemId} endpoint.

The following fields on invoice items are useful when calculating distribution amounts:
  • amount - the gross amount on that invoice item
  • primaryCommissionAmount - the commission amount that the producer is expected to retain
  • grossSettled - the gross amount on the invoice item that has been settled (when subtracted from the gross amount, can be used to calculate the unpaid gross for the invoice for the invoice item)
  • primaryCommissionReserve - the unpaid commission for the invoice

For more, see Working with invoice items.

Example payment and distribution

The following creates a payment and distributes it to two invoice items.

Note the following about this request:

  • The net amount that the insurer receives from the producer is $140.00 USD.
  • The total amount distributed to the invoice items is $175.50 USD.
    • This is calculated as the gross minus the commission for both invoice items. In this request, it is calculated as follows: (95.00 - 9.50) + (100.00 - 10.00) = 175.50
  • The net provided by the producer is less than the amount that is distributed. This means that the agency bill payment will be over-distributed. The difference (-35.50) is added to the producer’s unapplied fund.
  • The disposition for both invoice items is autoexception, meaning that an exception is created only when there is a payment mismatch between the expected amount and the provided amount.
Command
POST /billing/v1/producers/bc:423/ab-money-rcvds
Request body
{
    "data": {
        "attributes": {
            "agencyCyclePayment": {
                "agencyPaymentItems": [
                    {
                        "invoiceItem": {
                            "id": "bc:S7ucVhmRCNCXawTskyeNj"
                        },
                        "commissionAmountToApply": {
                            "amount": "9.50",
                            "currency": "usd"
                        },
                        "currency": {
                            "code": "usd"
                        }, 
                        "disposition": {
                            "code": "autoexception"
                        },
                        "grossAmountToApply": {
                            "amount": "95.00",
                            "currency": "usd"
                        }
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:SEBiAS1muTtfo5PgFSOfT"
                        },
                        "commissionAmountToApply": {
                            "amount": "10.00",
                            "currency": "usd"
                        },
                        "currency": {
                            "code": "usd"
                        }, 
                        "disposition": {
                            "code": "autoexception"
                        },
                        "grossAmountToApply": {
                            "amount": "100.00",
                            "currency": "usd"
                        }
                    }
                ],
                "currency": {
                    "code": "usd"
                }
            },
            "amount": {
                "amount": "140.00",
                "currency": "usd"
            },
            "currency": {
                "code": "usd"
            },
            "paymentInstrument": {
                "id": "bc:Sw5rLwGO9lj0XgxE3HeFa"
            },
            "receivedDate": "2024-06-23"
        }
    }
}

Differences between distribution in the user interface and in Cloud API

When creating a distribution, there are some settings that can be set when working in the user interface that cannot be set through Cloud API.
  • Distributing a payment after creating it - In the BillingCenter user interface, you can create a credit distribution after creating a payment. You cannot create a credit distribution in Cloud API after the call to create a payment.
  • Specifying gross versus net amounts - When distributing payments in the user interface, you can specify the net amount that is applied to each invoice item rather than the gross and the commission. When distributing payments using Cloud API, you must specify both the gross amount and the commission amount for each item. (The net is the difference between these values.)
  • Fully pay invoice items - In the Agency Bill Payment wizard, users have the option to fully pay selected invoice items without specifying invoice item amounts. This is not offered in Cloud API.

Creating a saved agency bill payment

A saved payment is a set of information pertaining to the draft of a payment. This can include information on how to distribute the payment. Saved payments are saved to the BillingCenter database, but no financial transactions have been created and no T-account amounts have been adjusted.

To create a saved payment through Cloud API, set the saved field to true in the request body.

When creating a saved payment, you must include a distribution for the payment by including the agencyCyclePayment object. However, distribution items and agency bill suspense items are optional for saved agency bill payments. For example, the following is a minimal request body for creating a saved agency bill payment:
{
    "data": {
        "attributes": {
            "agencyCyclePayment": {
                "currency": {
                    "code": "usd"
                }
            },
            "amount": {
                "amount": "140.00",
                "currency": "usd"
            },
            "currency": {
                "code": "usd"
            },
            "paymentInstrument": {
                "id": "bc:SqHIzlOLI89qiZMapbZGf"
            },
            "receivedDate": "2024-06-23",
            "saved": true
        }
    }
}

This payload results in a saved payment for 140 dollars with no distribution information. It remains in the saved state until it is executed or deleted.

Retrieve payment distribution information

After a payment has been distributed, you can retrieve information about the distribution. This information is captured in two objects:
  • An agency cycle payment object, used to record the total funds distributed for the payment. The BillingCenter user interface uses the term "agency bill distribution."
  • Agency payment item objects, which are children of agency cycle payments, used to record the funds distributed to each invoice item in the agency cycle payment. The BillingCenter user interface uses the term "

The terms agency cycle payment and agency payment item are unique to Cloud API. The information contained in these objects can be found in the Executed Payments screen and the Agency Item Events screen in the BillingCenter user interface.

Retrieve agency cycle payments

Retrieve an agency cycle payment using one of the following endpoints:
  • GET /producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments
  • GET /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}
Note: There is never more than one agency cycle payment for an agency bill payment, so the two endpoints will always return the same agency cycle payment object (if the payment was distributed). Both the collection GET and the element GET are provided in BillingCenter for data model consistency with other Cloud API endpoints.

The following is an example of retrieving the agency cycle payment on an agency bill payment. It uses the collection GET endpoint, so it retrieves an array with only one item in it.

Command
GET /billing/v1/producers/bc:423/ab-money-rcvds/bc:544/agency-cycle-payments

Response

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "currency": {
                    "code": "usd",
                    "name": "USD"
                },
                "distributedDate": "2024-09-19T20:39:53.788Z",
                "id": "bc:SJcELeJmwtc6b3DoFMpdt",
                "netDistributedToInvoiceItems": {
                    "amount": "143.60",
                    "currency": "usd"
                },
                "netInSuspense": {
                    "amount": "0.00",
                    "currency": "usd"
                }
            },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "bc:423/ab-money-rcvds/bc:544/agency-cycle-payments/bc:591",
                    "methods": [
                        "get"
                    ]
                }
            }
        ...
    }
}

Retrieving distribution items

Retrieve distribution items using the following endpoints:

  • GET /producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}/agency-payment-items
  • GET /producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}/agency-payment-items/{agencyPaymentItemId}

The following example retrieves a single distribution item. In the case of this invoice item, there is a $95.00 gross amount that was applied to the invoice, and a $9.50 commission amount that was withheld.

Note the following about distribution items:
  • The fields commissionAmountToApply and grossAmountToApply reflect the amounts that were distributed or withheld for the invoice item as a result of the distribution.
Command
GET /billing/v1/producers/bc:423/ab-money-rcvds/bc:544/agency-cycle-payments/bc:545/agency-payment-items/bc:546
Response
{
    "data": {
        "attributes": {
            "commissionAmountToApply": {
                "amount": "9.50",
                "currency": "usd"
            },
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "disposition": {
                "code": "autoexception",
                "name": "Automatic"
            },
            "grossAmountToApply": {
                "amount": "95.00",
                "currency": "usd"
            },
            "id": "bc:546",
            "invoiceItem": {
                "displayName": "09/18/2024 ($95.00)",
                "id": "bc:S9xfKCx-ufSlTGNfuzGQR",
                "type": "InvoiceItem",
                "uri": "/billing/v1/charges/bc:SQljfspJvWZAwZlyFDg9T/invoice-items/bc:S9xfKCx-ufSlTGNfuzGQR"
            }
        },
        ...
    }
}

In some cases, you may want to filter out reversed distribution items. Use the query parameter ?filter=reversedDate:eq:null when you execute the GET to exclude reversed distribution items.

Agency bill payments in suspense

Agency bill payments, like direct bill payments, can initially be created as suspense payments through Cloud API. Agency bill suspense payments can be applied to a producer in the same way that direct bill suspense payments can be applied to policies or accounts. For information on applying suspense payments, see Applying suspense payments. For applying agency bill suspense payments, you specify the producer's ID instead of the account ID or policy ID.

When applied, agency bill suspense payments are added to the target producer’s unapplied fund and recorded as an agency bill payment transaction.