Creating and distributing direct bill payments

Use the following endpoint to create a direct bill payment:

  • POST /billing/v1/accounts/{accountId}/db-money-rcvds

Minimum creation criteria

At a minimum, you must specify the following:

  • amount - A MonetaryAmount value that specifies both amount and currency
  • currency - A typekey from the Currency typelist
  • paymentInstrument - The ID of the associated payment instrument
  • receivedDate - The date the payment was received.

Note that the payment's currency is specified twice - as part of the amount field and in the currency field.

A payment with only the minimum required fields has no target and will be placed in the account's unapplied fund.

For example, the following request creates a payment of $120 USD in cash (payment instrument bc:111) received on March 3, 2024 for account bc:99.

Command

POST /billing/v1/accounts/bc:99/db-money-rcvds

Request body

{
  "data": {
    "attributes": {
        "amount": {
            "amount": "120",
            "currency": "usd"
        },
        "currency": {
            "code": "usd"
        },
        "paymentInstrument": {
            "id": "bc:111"
        },
        "receivedDate": "2024-03-03"
    }
  }
}

When creating a payment, the payment instrument must be cash, check, or a non-universal payment instrument associated with the account.

Payments with a specific target

A payment can target a specific policy period or invoice. To do so, include either the policyPeriod or invoice field in the request. Set the field to the target's id.

For example, the following request creates a payment of $50 USD in cash (payment instrument bc:111) received on March 3, 2024 for account bc:99. The payment targets invoice bc:3300.

Command

POST /billing/v1/accounts/bc:99/db-money-rcvds

Request body

{
  "data": {
    "attributes": {
        "amount": {
            "amount": "50",
            "currency": "usd"
        },
        "currency": {
            "code": "usd"
        },
        "invoice": {
            "id": "bc:3300"
        },
        "paymentInstrument": {
            "id": "bc:111"
        },
        "receivedDate": "2024-03-03"
    }
  }
}

Similarly, the following request creates a payment of $50 USD in cash (payment instrument bc:111) received on March 3, 2024 for account bc:99. The payment targets policy period bc:775.

Command

POST /billing/v1/accounts/bc:99/db-money-rcvds

Request body

{
  "data": {
    "attributes": {
        "amount": {
            "amount": "50",
            "currency": "usd"
        },
        "currency": {
            "code": "usd"
        },
        "paymentInstrument": {
            "id": "bc:111"
        },
        "policyPeriod": {
            "id": "bc:775"
        },
        "receivedDate": "2024-03-03"
    }
  }
}

Restrictions

A single payment cannot target both a policy period and an invoice, even if the invoice is for the given policy period. You can set only the policyPeriod, only the invoice, or neither. When you specify neither, the payment targets only the account.

All direct bill payments pass through an unapplied fund. However, a payment cannot target an unapplied fund directly, as the unappliedFund field is read-only. The relevant unapplied fund is determined by other settings for the account and the payment itself.

  • For accounts that use policy-level billing with cash separation:
    • If the payment has a specified policyPeriod or invoice, it is initially placed in the associated policy's unapplied fund.
    • If the payment has no specified policyPeriod or invoice, it is initially placed in the account's unapplied fund.
  • For accounts that use account-level billing or policy-level billing without cash separation:
    • The payment is initially placed in the account's unapplied fund.

Distributing direct bill payments when they are created

You can distribute a direct bill payment in the same call that creates the payment. When you distribute a direct bill payment, portions of the funds included in the payment are applied to specific invoice items.

When distributing direct bill payments in this manner, you specify the invoice items that funds will be applied to and how much to apply. When the funds are distributed, BillingCenter updates the amounts of the invoices.

Specifying distribution information

To distribute a direct bill payment when creating the payment using Cloud API, include the directBillPayment object in the attributes object of the POST request. The directBillPayment object has two required fields:

  • directBillPaymentItems - Array in which each element specifies funds to be applied to a single invoice item. The required fields for each item are listed in the table below.
  • currency - The currency of the direct bill payment, as a typekey reference.
Each element in the directBillPaymentItems array must contain the following:
Field Type Description
invoiceItem Object containing a simple reference to an invoice item’s id The id of the target invoice item.
currency Typekey reference to the Currency typelist The currency of the invoice item.
grossAmountToApply Monetary amount object The gross amount that will be applied to that invoice item.

Collecting information for the distribution

To create the distribution object, you need to know the id and amount of the invoice items you want to distribute funds to. You can distribute to items owned by that account, or owned by other entities in BillingCenter.

You can retrieve invoice item information using Cloud API. For example, to get invoice items on an account's invoice stream, you can make two Cloud API calls:
  • Get the invoices on the account using GET /billing/v1/accounts/{accountId}/invoices
  • For the desired invoices, get the invoice items using GET /billing/v1/invoices/{invoiceId}/invoice-items

Example request

The following request creates a direct bill payment of $120. $95 of the payment is applied to invoice item bc:993. The remaining $25 of the payment will be added to the account's unapplied fund.

Command

POST /billing/v1/accounts/bc:99/db-money-rcvds

Request body

{
  "data": {
    "attributes": {
        "amount": {
            "amount": "120",
            "currency": "usd"
        },
        "currency": {
            "code": "usd"
        },
        "directBillPayment": {
            "directBillPaymentItems": [
                {
                    "invoiceItem": {
                        "id": "bc:993"
                    },
                    "currency": {
                        "code": "usd"
                    }, 
                    "grossAmountToApply": {
                        "amount": "95.00",
                        "currency": "usd"
                    }
                }
            ],
            "currency": {
                "code": "usd"
            }
        },
        "paymentInstrument": {
            "id": "bc:SJ83VFGDddseddrTxfVLZ"
        },
        "receivedDate": "2026-03-03"
    }
  }
}

The response contains information about the payment itself, but no information about the distribution. To verify that the distribution was executed correctly, see Querying for distribution information.

Distributing direct bill payments after creation

You can distribute direct bill payments that have been created but not yet distributed by calling the following endpoint:

  • POST /accounts/{accountId}/db-money-rcvds/{dbMoneyRcvdId}/distribute

When you distribute a payment using this endpoint, the distribution occurs automatically. The money is taken from the account's unapplied fund and applied to eligible invoice items for that account. It is not necessary or possible to specify invoice items to distribute the funds toward. If there are no eligible invoice items, or if the payment already has a distribution, the call returns a 400 response.

No body is required.

Command

POST /billing/v1/accounts/bc:55/db-money-rcvds/bc:1011/distribute

Request body

(no request body)
Response
{
    "data": {
        "attributes": {
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "distributedDate": "2026-12-18T23:17:23.317Z",
            "frozenByArchiving": false,
            "id": "bc:SA5sDQUgM3s5jmX7_r7Qi",
            "netDistributedToInvoiceItems": {
                "amount": "70.00",
                "currency": "usd"
            },
            "netInSuspense": {
                "amount": "0.00",
                "currency": "usd"
            }
        }
    }
}

The response contains information about the distribution entity that is created.