Charge to payment gateway

You can now instead have the DVM collect payment through a third-party payment service provider (Payment Gateway). The consumer enters their card details on the gateway’s hosted checkout page, and the DVM drives every charge, renewal, refund and cancellation against that stored payment method for the life of the subscription. Use this when:

You want to sell subscriptions to consumers you don’t already bill directly.
You want card payments handled by a provider that already holds your PCI compliance and tax obligations and is acting as teh Merchant of Record on your behalf
You want Bango to keep owning the subscription lifecycle, plans, phases, renewals, entitlements, rather than splitting it across multiple systems.

What stays the same: your catalog, your offers, your entitlement provisioning, and your cancellation APIs all behave exactly as they do today. What changes is one step in the purchase journey, and one new response you need to handle.

Before you start

Payment Gateway charging is enabled by Bango, Talk to your Bango account contact to:

Choose your provider. Bango integrates with a set of supported Payment service providers. Your account contact will confirm which providers are available for your market.
Connect your account. You hold the commercial relationship with the PSP. Bango needs credentials to create checkouts and submit charges on your behalf.
Map your product categories. Some providers require a product category on every checkout for tax purposes. Bango passes this through.
Agree your redirect URLs. You’ll supply success and failure URLs per request (see below), but Bango needs to allow-list the domains.

Once configured, the change is visible in your integration only through the new response described in the next section.

The purchase journey

1. Create the consumer offer

Call POST /consumerOffers as you do today, with one addition: redirectionParameters, telling Bango where to send the consumer after checkout.

{
  "offerId": "offer_7f3a91",
  "consumer": {
    "consumerIdentifier": "consumer_4471bd"
  },
  "redirectionParameters": {
    "successUrl": "https://shop.example.com/checkout/return?session=b41f9c2e",
    "failureUrl": "https://shop.example.com/checkout/error?session=b41f9c2e"
  }
}

Include a unique, token in both URLs and validate it when the consumer returns.

2. Redirect the consumer to checkout

Where an add-to-bill offer would return a created offer, a payment gateway offer returns an action for you to perform:

{
  "consumerOfferId": "co_9d2e77",
  "status": "REQUESTED",
  "subStatus": "PENDING_ACTION",
  "action": {
    "type": "NAVIGATE_TO_URL",
    "url": "https://checkout.provider.com/s/8f2a4c19bd"
  }
}

Send the consumer to action.url. Do not embed it in an iframe — providers block this, and some journeys require full-page redirects for strong customer authentication. At this point nothing has been provisioned. No entitlements exist, no plan has started, and no money has moved.

3. Wait for the offer to complete

When the consumer finishes checkout, the payment gateway notifies the DVM directly and returns the consumer to your successUrl. Bango then creates the entitlements and starts the billing plan.

4. Activate

Present the activation URLs to the consumer as normal. Depending on your offer’s start trigger, the first charge is taken when the offer is fully created or when it is fully activated.

When checkout doesn’t complete

Two things can go wrong, and they look different to you. The consumer abandons. They close the tab, or never finish. The payment is refused. The payment Gateway rejects the card, returns the consumer to your failureUrl, and tells teh DVM . The offer moves to status: "REQUESTED", subStatus: "ACTION_FAILED".

{
  "consumerOfferId": "co_9d2e77",
  "status": "REQUESTED",
  "subStatus": "ACTION_FAILED"
}

In life

Renewals, phase changes and price changes need nothing from you. The DVM notifies the Payment Gateway ahead of each renewal, then submits the charge on the due date. Your existing reseller notifications are unaffected. Payment method updates are handled by the Payment Gateway, not by the DVM. Providers require this for compliance. After checkout, the consumer receives details from the provider for managing their payment method.

Cancellations and refunds

Your cancellation APIs are unchanged.

Soft cancellation: The DVM tells the payment gateway the subscription is ending, stops further renewals at end of term, and confirms when it has ended.
Hard cancellation: The DVM tells the Payment Gateway to stop charging immediately, then submits a pro-rated refund against the original payment.

Refunds are executed by the Payment Gateway and settle on the consumer’s original payment method according to that provider’s timelines.

Status reference

Status	Sub-status	Meaning	What to do
`REQUESTED`	`PENDING_ACTION`	Awaiting the consumer at checkout	Redirect to `action.url`, or keep polling if they’ve returned
`REQUESTED`	`ACTION_FAILED`	Payment was refused	Show your error page; offer a retry
`FULLY_CREATED`	—	Entitlements created	Present activation URLs
`FULLY_ACTIVATED`	—	Consumer has activated	Nothing, billing is running

Welcome

Getting started

Partner management

Migrating to DVM

Offer management

Entitlement management

Billing & Charging

Notifications

Correlation and reconciliation

Dashboard and reporting

Partner care

Before you start

The purchase journey

1. Create the consumer offer

2. Redirect the consumer to checkout

3. Wait for the offer to complete

4. Activate

When checkout doesn’t complete

In life

Cancellations and refunds

Status reference

​Before you start

​The purchase journey

​1. Create the consumer offer

​2. Redirect the consumer to checkout

​3. Wait for the offer to complete

​4. Activate

​When checkout doesn’t complete

​In life

​Cancellations and refunds

​Status reference

Before you start

The purchase journey

1. Create the consumer offer

2. Redirect the consumer to checkout

3. Wait for the offer to complete

4. Activate

When checkout doesn’t complete

In life

Cancellations and refunds

Status reference