Reversing payments

Reversing payments in BillingCenter

When you reverse a payment, BillingCenter undistributes the payment (if it was distributed) and removes the money from the appropriate unapplied fund.

You must specify a reason for the payment reversal. BillingCenter defines certain reasons as pejorative. (For example, in the base configuration, the one reason defined as pejorative is Returned Check.) When a payment is reversed for a pejorative reason, BillingCenter adds a payment reversal fee if one has been specified in the account's billing plan.

For more information on reversing payments, see the Application Guide.

Reversing payments in Cloud API

Use the following endpoint to reverse a payment:

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

The request must include a reversalReason, which must be a value from the PaymentReversalReason typelist, such as modification or returnedcheck.

Identifying whether a payment has been reversed

You can identify that a payment has been reversed in the following ways:

  • The reversalDate is non-null and is present in the response.
  • The reversalReason is non-null and is present in the response.

These fields are included in:

  • The default response to POST /accounts/{accountId}/db-money-rcvds/{dbMoneyRcvdId}/reverse
  • The default response to GET /accounts/{accountId}/db-money-rcvds/{dbMoneyRcvdId}

You can identify that a payment has not been reversed by executing a GET /accounts/{accountId}/db-money-rcvds/{dbMoneyRcvdId} and verifying that the reversalDate and reversalReason fields are not part of the response payload. (Cloud API does not include fields in responses whose value are NULL, even when you specify the field using the fields query parameter. Therefore, these fields will not be present in the response for a payment that has not been reversed.)

Reversing payment example

For example, the following request retrieves payment bc:1010 from account bc:55 before it is reversed. Note that the reversalDate and reversalReason fields are not part of the payload.

Command

GET /billing/v1/accounts/bc:55/db-money-rcvds/bc:1010
Response
{
    "data": {
        "attributes": {
            "amount": {
                "amount": "80.00",
                "currency": "usd"
            },
            "appliedDate": "2024-01-23T22:15:53.067Z",
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "id": "bc:1010",
            "paymentInstrument": {
                "displayName": "Check",
                "id": "bc:STFf31JkOo1Ey9wUIWaou",
                "type": "UniversalPaymentInstrument",
                "uri": "/billing/v1/universal-payment-instruments/bc:STFf31JkOo1Ey9wUIWaou"
            },
            "receivedDate": "2024-01-23T22:15:50.037Z",
            "subtype": "DirectBillMoneyRcvd",
            "unappliedFund": {
                "displayName": "Default",
                "id": "bc:SVR_B0B2oxbGhbxlWd2q9",
                "type": "UnappliedFund",
                "uri": "/billing/v1/accounts/bc:SsDCo4_asUVmbT1Z-TlO6/unapplied-funds/bc:SVR_B0B2oxbGhbxlWd2q9"
            }
        },
        ...

The following command reverses that payment with a reason of modification. Note that, in the response, the reversalDate and reversalReason fields are part of the payload.

Command

POST /billing/v1/accounts/bc:55/db-money-rcvds/bc:1010/reverse

Request
{
  "data": {
    "attributes": {
        "reversalReason": {
            "code": "modification"
        }
    }
  }
}
Response
{
    "data": {
        "attributes": {
            "amount": {
                "amount": "80.00",
                "currency": "usd"
            },
            "appliedDate": "2024-01-23T22:15:53.067Z",
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "id": "bc:S6fSPHORKdaiudGcfC7c6",
            "paymentInstrument": {
                "displayName": "Check",
                "id": "bc:STFf31JkOo1Ey9wUIWaou",
                "type": "UniversalPaymentInstrument",
                "uri": "/billing/v1/universal-payment-instruments/bc:STFf31JkOo1Ey9wUIWaou"
            },
            "receivedDate": "2024-01-23T22:15:50.037Z",
            "reversalDate": "2024-03-04T03:26:03.743Z",
            "reversalReason": {
                "code": "modification",
                "name": "Payment Modification"
            },
            "subtype": "DirectBillMoneyRcvd",
            "unappliedFund": {
                "displayName": "Default",
                "id": "bc:SVR_B0B2oxbGhbxlWd2q9",
                "type": "UnappliedFund",
                "uri": "/billing/v1/accounts/bc:SsDCo4_asUVmbT1Z-TlO6/unapplied-funds/bc:SVR_B0B2oxbGhbxlWd2q9"
            }
        }
    }
}