Direct Topup Webhook

Direct-topup Declare Stock - Seller Documentation

Overview

Direct topup webhook (order notification) is now available for topup products, enabling sellers to accept more orders than their current inventory (declared stock) by integrating with external topup providers.

The "Direct Topup Webhook" feature allows you as a seller to automate top-up transactions for gaming products without manually managing individual transactions. The Direct-topup Webhook feature enables real-time top-up processing for gaming products, allowing you to provide instant top-up services through automated API integration .

Enabling "Direct Topup Webhook" Feature

You can enable the direct topup webhook feature directly from your Driffle dashboard. Follow the steps below to enable direct topups for your products:

  1. Login to your seller dashboard.

  2. Navigate to Store Settings > Direct Top-up Webhook.

Step 1: Connect Webhook

To begin, you must connect and verify your system's endpoints with Driffle.

  • Dummy Product Offer: We have created a dummy offer for product ID: 888888. This product will not be visible to users. This is for you to test that the endpoints are configured with the correct responses on production.

  • Authorization: Provide your API key in the Bearer token field for authenticating requests between Driffle and your system.

  • Recharge details: Enter a test User ID and Server ID that your system can use to process the dummy top-up request. These are test payload, actual payload will be different for each topup product.

  • Direct topup webhook: Enter the URL of your endpoint that will handle the top-up provisioning. Driffle will send a request to this endpoint to credit the user's account. Once entered, click "Verify" to ensure your endpoint is reachable and responds correctly. A "Verified" status will appear upon successful connection.

After filling in all the required fields and verifying the endpoint, click Save.

Step 2: Enable Feature

Once your endpoints are successfully connected and verified, you can enable the direct topup feature.

  • Read the terms and conditions for selling with the linked API.

  • Check the box for "I agree to the terms and conditions."

  • Click Enable to finalize the setup.

Managing Topup Products

After enabling the Direct Topup API, you can manage your top-up products from the "Currently Selling" section of your dashboard.

  1. Navigate to My Store > Currently Selling.

  2. Select the Direct-Topup filter to view all your direct top-up products.

  3. From here, you can see a list of all your active and in-active top-up items, including the title, last sold date, and status.

Editing Topup Denominations and Pricing

You can manage individual denominations for each top-up product.

  1. On the "Currently Selling" page, click on a top-up product to expand the view of denomination.

  2. This will display a list of all available denominations for that product (e.g., Weekly Diamond, Diamonds, Twilight Pass).

  1. For each denomination, you can:

  • Toggle the Status to make it active or inactive.

  • View the number of Declared topups and the total number of Topups performed.

  • Set the Auto. Price.

  • View and set the lowest selling price.

  • See the commission and the amount you will receive.

  • Click Edit to modify the details of that specific denomination.

Managing Campaigns

You can also create and manage promotional campaigns for your top-up products.

  1. While editing a top-up item, click on the Campaign button.

  2. This will take you to the "Active Campaigns" section for that product.

  3. Here you can:

    • View all running, paused, not started, and inactive campaigns.

    • Click + Create campaign to set up a new promotion to help boost your sales.

Locating Form Fields (Payload) via Seller Dashboard (UI)

Sellers can view the required configuration fields for specific products directly through the portal.

Steps to view Form Fields:

  1. Log in to your Seller Dashboard.

  2. Navigate to the Currently Selling section.

  3. Select an existing offer and click Edit.

  4. Scroll to the Product Configuration section. You will see a new area labeled Details. This displays the specific payload schema sent to your system by the web hook.

2. API Reference: Accessing Form Fields Schema

For developers integrating with our system, the form_fields object has been added to the response payloads of the Product and Offers APIs. This object defines the structure of account information required for topup.

A. Product List & Single Product Details API

When fetching the product list or details for a specific Item ID, the response now includes the form_fields parameter. This describes the schema (data types, labels, and validation rules) required for the product.

Endpoint Reference:

Products

New Response Parameter:

  • form_fields: Contains the JSON schema for dynamic inputs. This object defines the structure of account information required for topup.

Example Response:

codeJSON

B. Offers API

The Offers API has also been updated. When creating or retrieving offers, the form_fields data ensures that your system knows exactly what information must be collected or validated during the transaction.

Endpoint Reference:

Offers (Auction)

Topup-Webhook(formerly provision endpoint)

The system will make three attempts with a 5s sleep interval and 60s timeout for you to respond. In case of final failure, the order will be canceled.

Example:

  • Request 1: Fails immediately (pending status)

  • Wait time: 5 seconds

  • Request 2: Fails after timeout (60 seconds) (pending status)

  • Wait time: 5 seconds

  • Request 3: Fails (pending status)

  • Order gets cancelled

Request Body

Response

By successfully responding (HTTP status 200) to the Provision request with the payload structure below, you indicate that you can fully fulfill the topup provision.

Response Data Fields

Field

Type

Description

orderId

string

Provision Order Id for topup purchase

success

boolean

Indicates if the topup was successful

transactionId

string

Your internal transaction ID

topupDetails

object

Details about the completed topup

TopupDetails Fields

Field

Type

Description

amount

number

The topup amount

currency

string

Currency code ( USD , EUR , etc.)

status

string

Status of the top-up ( completed , accepted, failed , pending )

API Response Status Guide

When our system sends a web hook for topup product to your API, we expect a JSON response containing an order_status field. This status determines how we handle the order lifecycle (whether we mark it complete, fail it, or wait for processing).

The topup provision system recognizes three primary status categories. When our system sends a Provision (Top-up) request to your API, we expect a JSON response containing an order_status field. This status determines how we handle the order lifecycle (whether we mark it complete, fail it, or wait for processing).

1. completed Status (Immediate Fulfillment)

The top-up has been successfully delivered to the user's account immediately upon request

  • The order is fully processed and no further action is needed

  • The customer has received their recharge

Return this status when the top-up has been successfully delivered to the user's account immediately upon request

  • Use completed when the topup has been immediately processed by the seller and the customer has received the recharge

  • Use accepted when you have confirmed the order and will fulfill it immediately (within 30 min), or when your system guarantees fulfillment. Use this when you want to do the topup manually

  • The order is marked as Delivered when either of accepted or completed is sent in order_status field.

  • The customer is notified that their top-up is done.

  • No further API calls will be made for this specific order.

  • No retry job is scheduled

  • The order is considered final and complete

  • Our system will NOT call your API again for this specific order.

  • Do not return success status if the order is still processing - use pending instead.

2. pending Status

Return pending status if you have received the request, but the top-up is still processing (e.g., waiting on an upstream provider or a slow network).

  • You have received the request, but the top-up is still processing

    • The order is waiting on an upstream provider or a slow network

    • The final outcome is not yet determined

  • The order is marked as Processing in our system.

  • Return pending status if you have received the request, but the top-up is still processing

    • Use when your provider requires time to process the recharge

    • Use when you need to verify the recharge with a third-party provider

    • Use when the order is queued in your system but not yet executed

    • The order is NOT marked as complete or failed at this stage

    How it works:

    1. Initial Response Handling:

      • When your API returns a pending status (pending), our system marks the order as pending

      • The order is NOT marked as complete or failed at this stage

    2. Automatic Retry Process:

      • Initial Retry: After 5 seconds, our system re-calls your web hook endpoint with the same payload

      • Subsequent Retries: Up to 3 additional retries with 15-second delays between each

      • Total Coverage: ~50 seconds (5s initial + 15s + 15s + 15s)

      • Total API Calls: 4 calls (initial + 3 retries)

    3. Each retry re-calls your web hook endpoint with the same orderId and payload

      • If your API returns completed or accepted → Order is marked as REDEEMED and retries stop

      • If your API returns failed → Order is marked as DEFECTIVE, refund is triggered, and retries stop

      • If still pending after all retries → Order is marked as failed and refund is triggered

    4. Idempotency Requirement (CRITICAL):

      • web hook endpoint MUST be idempotent

      • When we call your API with the same orderId multiple times, you should return the current status of that order

      • Do NOT create duplicate orders or recharge the customer multiple times.

      • If the order completes during the retry period, return a success status on the next retry

      • If processing takes longer than 50 seconds, the order will be marked as failed after all retries

3. failed Status

Return a failed status if the top-up cannot be processed (e.g., invalid Player ID, out of stock, or technical error).

  • The order is marked as Failed.

  • The transaction is reversed/refunded on our side.

  • No further actions are taken.

  • The top-up cannot be processed

    • The order was rejected or could not be fulfilled

Your API Status

Our System Interpretation

Action Taken

completed/ accepted

Order Complete

Transaction finalized.

pending

Order In-Progress

We start retrying your webhook endpoint.

failed

Order Failed

Transaction cancelled/refunded.

Status matching is case-sensitive

  • Ensure your API returns status values that match your configured mappings

  • Unknown statuses (not in any mapping) are treated as failures after retries are exhausted

Important: We never "retry" a provision request that you have already accepted (i.e., we won't accidentally purchase the item twice). If you say "Pending," we only ask "Is it done?" via the Status API.

Updating Your Configuration

To keep your topup service running smoothly:

  • Test your endpoints regularly to ensure they're working

  • Monitor your API performance to avoid cooldown periods

  • Update your API key if needed for security

  • Check your domain verification status periodicallyTransaction Management

  • Monitor completed transactions in your dashboard

  • Handle refunds through the Driffle refund system

  • Track commission fees and earnings

  • View transaction history and analytics

Ready to get started? Log in to your seller dashboard and navigate to Settings → Topup API to begin the setup process!

PreviousPre-Order-Declare-StockNextSettlement flow

Last updated