Creating direct bill payments

Use the following endpoint to create a direct bill payment:

POST /billing/v1/account/{accountId}/db-money-rcvds

Note: Whenever a direct bill payment is created through Cloud API, the money received is always added to the account's unapplied fund. This is true regardless of whether the payment has a target or not. There is no way to distribute payments to invoice items through Cloud API. Payments that come in through Cloud API can only be distributed by a batch process.

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.