Creating suspense payments

Create suspense payments using the following endpoint:
  • POST /billing/v1/suspense-payments

Minimum creation criteria

When creating a suspense payment, you must include the following fields in the request:
  • amount - A MonetaryAmount object that specifies both amount and currency
  • paymentDate - The date the payment was made as a string in the format YYYY-MM-DD
  • paymentInstrument - An object that contains the id of the payment instrument (for information on how to retrieve this id, see Payment instruments)

The following request creates a minimal suspense payment.

Command
POST /billing/v1/suspense-payments
Request body
{
    "data": {
      "attributes": {
            "amount": {
                "amount": "20.00",
                "currency": "usd"
            },
            "paymentDate": "2024-10-05",
            "paymentInstrument": {
                "id": "bc:S6_cD6OL_JHsrHOZ3BURd"
            }
        }
    }
}

Additional fields

The following table details common optional fields when creating a suspense payment.

Field Description
refNumber The check number (if the payment was made with a check)
invoiceNumber The related invoice for the payment
accountNumber* The account number of the expected target account
policyNumber* The policy number of the expected target policy
description A note about the suspense payment

*Either the policy number or the account number can be set while creating the suspense payment, but not both. See the discussion of suspense payment targets below for more.

When creating suspense payments, no validation is run on the optional fields in the above table. This means that the accountNumber or policyNumber strings do not have to correspond with existing entities in BillingCenter. (This is because, in theory, these entities have not yet been created.)

However, when applying suspense payments, accurate identification information must be given. For more information, see Applying suspense payments.

Suspense payment targets

The target of a suspense payment is the object that owns the invoice items that the payment is meant to pay for. When a suspense payment is created, it either has no target, or it has a target but the target does not exist in BillingCenter. A suspense payment does not have to have a target, and it cannot have more than one target.

A target can optionally be included when the suspense payment is created. When creating suspense payments through Cloud API, there are two target fields that can be set:
  • accountNumber
  • policyNumber
Because you cannot have more than one target on a suspense payment, you cannot create a request that includes both an accountNumber and a policyNumber.
Note: As of this release, you cannot create suspense payments with producers as targets using Cloud API.

Detailed suspense payment example

Below is a detailed suspense payment creation payload.

Command
POST /billing/v1/suspense-payments
Request body
{
    "data": {
      "attributes": {
            "accountNumber": "bc:Sxpw_OP1JgFLGIWHCp-dS",
            "amount": {
                "amount": "20.00",
                "currency": "usd"
            },
            "paymentDate": "2024-10-05",
            "paymentInstrument": {
                "id": "bc:S6_cD6OL_JHsrHOZ3BURd"
            },
            "refNumber": "12345",
            "invoiceNumber": "1000000000",
            "description": "Note on suspense payment"
        }
    }
}

This request creates a similar suspense payment to the minimal example above. However, this suspense payment has a target account, a check number, an invoice number, and a description of the suspense payment.