Suspense payment disbursements

When an insurer cannot determine what a suspense payment is for, the suspense payment can be disbursed. This means that the payment is returned to the party that submitted the payment. When a suspense payment is disbursed, BillingCenter creates a new disbursement object.

You can query for and create disbursements for suspense payments using Cloud API.

Querying for suspense payment disbursements

To retrieve the disbursements on a suspense payment, use the following endpoint:
  • GET /billing/v1/suspense-payments/{suspensePaymentId}/disbursements

Generally, suspense payments only have one disbursement. However, if the first disbursement is rejected, additional disbursements can be created. So a suspense payment can have multiple disbursements, although it will have at most one disbursement that has been approved. See The disbursement approval workflow for more information.

You can also retrieve suspense payment disbursements, along with other types of disbursements, with the /billing/v1/disbursements endpoint. See Disbursements for more information.

Below is an example of querying for suspense payment disbursements:

Command
GET /billing/v1/suspense-payments/bc:Sj293BrhPsFRULvM_BIod/disbursements
Response
{
    "count": 1,
    "data": [
        {
            "attributes": {
                "address": "1234 Hillsdale Blvd, Foster City, CA 12345",
                "amount": {
                    "amount": "332.00",
                    "currency": "usd"
                },
                "disbursementNumber": "1000000002",
                "dueDate": "2024-02-29",
                "id": "bc:SLm4e8iMJtMjIDgoOpjkv",
                "mailTo": "John Smith",
                "payTo": "John Smith",
                "paymentInstrument": {
                    "displayName": "Check",
                    "id": "bc:SqB1O80gYePif3EohOCnm",
                    "type": "UniversalPaymentInstrument",
                    "uri": "/billing/v1/universal-payment-instruments/bc:SqB1O80gYePif3EohOCnm"
                },
                "reason": {
                    "code": "Cancellation",
                    "name": "Cancellation"
                },
                "status": {
                    "code": "Approved",
                    "name": "Approved"
                },
                "suspensePayment": {
                    "displayName": "1000000002",
                    "id": "bc:Sj293BrhPsFRULvM_BIod",
                    "type": "SuspensePayment",
                    "uri": "/billing/v1/suspense-payments/bc:Sj293BrhPsFRULvM_BIod"
                }
            },
       ...	
    }
}

The disbursement approval workflow

If a user attempts to create a disbursement beyond their authority limits, the disbursement is created but the transaction is not. The disbursement must be approved by a user with sufficient authority, often a supervisor, to create the transaction. To facilitate this, an approval activity is triggered and the status of the disbursement is set to AwaitingApproval.

For more information on authority limits, see Authority limits and authority limit profiles.

When a disbursement that requires approval is created, additional fields related to the approval activity are set on the disbursement schema: assignedUser and openActivityCreatedByAppr. These fields are used to manage the approval workflow. They are explained as follows:

  • assignedUser is a reference to the user who needs to approve the disbursement
  • openActivityCreatedByAppr is a reference to the approval activity
Note: The openActivityCreatedByAppr field is visible only to the user who is assigned the activity. Other users who make GET requests for suspense payment disbursements will not see this field.

For more, see Requiring transaction approval.

The following describes the approval activity and disbursement at possible stages in the approval process:
  • Awaiting Approval - The activity is created. The status of the disbursement is AwaitingApproval. The assignedUser and openActivityCreatedByApp fields are set on the disbursement.
  • Approved - The activity is closed. The status of the disbursement is Approved. The assignedUser and openActivityCreatedByApp fields are set to null.
  • Rejected - The activity is closed. The status of the disbursement is Rejected. The assignedUser and openActivityCreatedByApp fields are set to null.

Creating suspense payment disbursements

To create suspense payment disbursements, use the following endpoint:

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

Minimum creation criteria

The following fields must be included in the request to create a suspense payment disbursement:
Field Description Note
address The address of the recipient
dueDate The date the outgoing payment is due to be created Cannot be in the past or before the payment date of the suspense payment
mailTo The name of the recipient By default this is the same as the payTo field, but can be different
payTo The name of the payee
reason An entry in the Reason typelist (for example, Cancellation or PolicyChange)
Additionally, the following must be true to disburse a suspense payment:
  • The suspense payment has not been reversed
  • The suspense payment has not been successfully disbursed

Suspense payment disbursement example

The following provides a minimal example of creating a suspense disbursement.

Command
POST /billing/v1/suspense-payments/bc:S05gwIPDaLQwMwA2ygkpn/disbursements
Request body
{
    "data": {
        "attributes": {
             "address": "123 Address St. San Mateo CA 94403",
             "dueDate": "2024-02-12",
             "mailTo": "John Smith",
             "payTo": "John Smith",
             "reason": {
                 "code": "Other"
            }
        }
    }
}
Response
{
    "data": {
        "attributes": {
            "address": "123 Address St. San Mateo CA 94403",
            "amount": {
                "amount": "54.00",
                "currency": "usd"
            },
            "disbursementNumber": "1000000005",
            "dueDate": "2024-02-12",
            "id": "bc:SrhyR0sLlmbkuQ1r7ZgHO",
            "mailTo": "John Smith",
            "payTo": "John Smith",
            "paymentInstrument": {
                "displayName": "Cash",
                "id": "bc:S8_HxpnMjgd0fLx5RCIJD",
                "type": "UniversalPaymentInstrument",
                "uri": "/billing/v1/universal-payment-instruments/bc:S8_HxpnMjgd0fLx5RCIJD"
            },
            "reason": {
                "code": "Other",
                "name": "Other"
            },
            "status": {
                "code": "Approved",
                "name": "Approved"
            },
            "suspensePayment": {
                "displayName": "1000000005",
                "id": "bc:SMklKGo7WhevuIbhPomsw",
                "type": "SuspensePayment",
                "uri": "/billing/v1/suspense-payments/bc:SMklKGo7WhevuIbhPomsw"
            }
        },
        "checksum": "0",
        "links": {
            "self": {
                "href": "/billing/v1/disbursements/bc:SrhyR0sLlmbkuQ1r7ZgHO",
                "methods": [
                    "get"
                ]
            }
        }
    }
}