Applying suspense payments

When a suspense payment is applied, it is associated with a known account or policy in BillingCenter. When it is applied, BillingCenter moves the suspense payment funds to the unapplied funds of the account or policy, sets the status of the suspense payment to applied, and creates a new direct bill payment transaction.

To apply suspense payments, use the following endpoint:

  • POST /billing/v1/suspense-payments/{suspensePaymentId}/apply

To apply a suspense payment, the following must be true:

  • The suspense payment must have a status of open.
  • The suspense payment must have an existing target in the BillingCenter database.

Payloads for applying suspense payments

When applying suspense payments, the fields in the request payload depend on the existing information in the suspense payment. If the suspense payment already has en existing target (such as an account or policy that exists in BillingCenter), the payment is automatically applied to the target.

To apply a suspense payment to its target, the request body just needs a data field and a nested empty attributes field.

Command
POST /billing/v1/suspense-payments/bc:SKXlDvlIZzPhNknWLnALg/apply
Request body 
{
    "data": {
        "attributes": {
        }
    }
}
Note: If the suspense payment does not have a target, the target must be specified in the request. You must specify the target’s id. This differs from creating a disbursement, where you provide the policy number or the account number rather than the id of the target entity.

To apply the suspense payment to an account, specify the account id:

Command
POST /billing/v1/suspense-payments/bc:SKXlDvlIZzPhNknWLnALg/apply
Request body
{
    "data": {
        "attributes": {
            "account": {
                "id": "bc:SgUWi7lZZx1EcF2tpJyTx"
            }
        }
    }
}

To apply the suspense payment to a policy, it must be applied to a policy period on the policy. Specify the policy period id:

Command
POST /billing/v1/suspense-payments/bc:SKXlDvlIZzPhNknWLnALg/apply
Request body
{
    "data": {
        "attributes": {
            "policyPeriod": {
                "id": "bc:S3x3673euPQ23MAfRyYzQ"
            }
        }
    }
}

Example response

Below is an example response for when a suspense payment is applied.

In this case, the payment is applied to policy PolicyNumber_XSHXDQ98. This response details the policy period, the user who applied the suspense payment, the money received, and the updated status of the suspense payment.
{
    "data": {
        "attributes": {
            "amount": {
                "amount": "55.00",
                "currency": "usd"
            },
            "appliedByUser": {
                "displayName": "Super User",
                "id": "default_data:1",
                "type": "User",
                "uri": "/admin/v1/users/default_data:1"
            },
            "id": "bc:SrrnldTyMnZftsGKSfSh0",
            "paymentDate": "2024-01-04T00:00:00.000Z",
            "paymentInstrument": {
                "displayName": "Cash",
                "id": "bc:S1rxFPQrXj0GPNsH0PRKB",
                "type": "UniversalPaymentInstrument",
                "uri": "/billing/v1/universal-payment-instruments/bc:S1rxFPQrXj0GPNsH0PRKB"
            },
            "paymentMoneyReceived": {
                "displayName": "Account Monster-93-Elevator $55.00, Received 01/30/2024, Applied 01/30/2024",
                "id": "bc:S3AXnmg_5YQdTFmtkFU_K",
                "type": "DirectBillMoneyRcvd",
                "uri": "/billing/v1/accounts/bc:SgUWi7lZZx1EcF2tpJyTx/db-money-rcvds/bc:S3AXnmg_5YQdTFmtkFU_K"
            },
            "policyNumber": "PolicyNumber_XSHXDQ98",
            "policyPeriodAppliedTo": {
                "displayName": "PolicyNumber_XSHXDQ98-1",
                "id": "bc:S3x3673euPQ23MAfRyYzQ",
                "type": "PolicyPeriod",
                "uri": "/billing/v1/accounts/bc:SgUWi7lZZx1EcF2tpJyTx/policies/bc:SP46y8feGf1KDWbIqRX06/policy-periods/bc:S3x3673euPQ23MAfRyYzQ"
            },
            "status": {
                "code": "applied",
                "name": "Applied"
            }
        }
    }
}