Skip to main content

​
Overview

When you use the DVM’s Billing & Charging capability, Bango manages the full billing lifecycle on your behalf — collecting charges and issuing refunds for the subscription offers you create in the DVM Offer Catalog. Refunds are sent directly to your billing system via a POST /refunds request, and your system is responsible for processing and acknowledging each one.
Refunds are only issued when you have licensed the DVM’s Billing & Charging capability. If you manage billing externally, refund handling is your responsibility.

​
When refunds are issued

There are three scenarios in which the DVM will issue a refund to your billing system:

Downgrade

A consumer moves to a lower-priced product tier mid-cycle. They receive a pro-rated refund of the price difference for the unused days remaining in the billing period.

Immediate Cancellation

A consumer immediately cancels their offer, ending the billing lifecycle. They receive a pro-rated refund against their last renewal charge for the unused days remaining.

Right to Withdrawal

In certain circumstances, a consumer may be automatically eligible for a full refund following cancellation — for example, if they cancel within a statutory right-to-withdrawal period.
For pro-rated refund calculations — including how remaining days are counted and the formula used — see the Pro-ration page.

​
Refund types

The DVM issues two types of refund requests to your billing system, depending on the scenario:

​
Example refund request

Below is an example of a PRO_RATED_REFUND request your billing system will receive from the DVM. This represents a consumer who has downgraded their product entitlement mid-cycle.

​
Key fields explained

These are the fields most important for your billing system to understand and act on:
​
string
required
A Bango-generated UUID for this request. You must echo this back in your response — it’s how Bango correlates requests and responses.
​
string
required
Tells you the type of refund being issued. Either PRO_RATED_REFUND (partial, mid-cycle) or SINGLE_REFUND (full refund).
​
string
required
The unique ID of the original charge transaction that this refund relates to. Use this to locate and reverse the correct payment in your system.
​
string
required
A unique identifier for this specific refund transaction. Note that a single charge can have more than one partial refund, each with its own refundId.
​
integer
required
The total refund amount, expressed in minor currency units (e.g. cents, pence). For example, 750 = $7.50 USD.
​
string
required
The currency of the refund in ISO 4217 format (e.g. USD, GBP, EUR).
​
boolean
required
Indicates whether this is a retry of a previously failed refund attempt. If true, check refundAttempt to see which attempt number this is. Use refundId to identify and deduplicate the refund in your system.
​
integer
required
The attempt number for this refund. 0 = first attempt, 1 = first retry, and so on.
​
array
required
The breakdown of what is being refunded. For pro-rated refunds on tier changes, the lineItemType will be OFFER_ENTITLEMENT_TIER_DELTA, with the amount representing the pro-rated price delta. For full refunds, lineItemType will be SINGLE_REFUND.
​
object
The billing period the refund relates to, including startDate, endDate, duration (ISO 8601), and phaseType (FREE, DISCOUNT, or FULL_PRICE). Useful for reconciliation.

​
How to respond

Your billing system must respond to every refund request with a 200 status and a JSON body indicating whether the refund was processed or declined.

​
Approved

Return this when the refund has been successfully processed in your billing system:

​
Declined

Return this when you are unable to process the refund. You must include a reason code so Bango can determine whether to retry:

​
Decline reason codes

The reason field tells Bango why the refund was declined and whether a retry should be attempted:
If you return DECLINED with no reason, or return an unexpected response code, Bango may treat it as a processing error and retry the refund. Always include a valid reason to ensure predictable behavior.