--- title: DingConnect API Integration on Truto slug: dingconnect category: Payment Gateway canonical: "https://truto.one/integrations/detail/dingconnect/" --- # DingConnect API Integration on Truto **Category:** Payment Gateway **Status:** Beta ## MCP-ready AI tools Truto exposes 17 tools for DingConnect that AI agents can call directly. - **create_a_ding_connect_cancel_transfer** — Cancel one or more DingConnect transfers in batch by submitting an explicit list of records to cancel (use ListTransferRecords first to find TransferIds available to cancel). Each result item reports the transfer's ProcessingState — 'Cancelled' means the transfer was successfully cancelled and balance compensations applied, any other state means it could not be cancelled. Returns per item:… - **create_a_ding_connect_estimate_price** — Estimate send or receive prices for Ding products by submitting a batch of estimation requests. Returns per-item: Price (CustomerFee, DistributorFee, ReceiveValue, TaxRate), SkuCode, BatchItemRef, ResultCode, ErrorCodes. SendValue and ReceiveValue cannot both be non-zero. - **list_all_ding_connect_get_account_lookups** — Look up the provider and product information for a specific account number in DingConnect. Returns country, provider and region code details for the account number, ready to pass to GetProducts; typically a single entry, but can return multiple items, and returns an empty list when no match is found. - **list_all_ding_connect_get_balances** — Get the current DingConnect agent balance, including any commission-on-sale increments but excluding transfers that are still processing. Returns the balance record with CurrencyIso and CurrencyName. - **list_all_ding_connect_get_countries** — List the countries supported by Ding Connect, each with its ISO 3166-1 alpha-2 two letter code (XG is used for products available in all countries) and the country name in English. Returns: CountryIso, CountryName, InternationalDialingInformation, RegionCodes. - **list_all_ding_connect_get_currencies** — List the ISO 4217 currencies supported by dingconnect. Returns each currency as a three-letter code with its English name: CurrencyIso, CurrencyName. Requires no parameters. - **list_all_ding_connect_get_error_code_descriptions** — Get a list of error code descriptions in DingConnect: the human readable messages corresponding to the ErrorCodes returned in failed API responses. Returns items with: Code, Description. Messages are aimed at agents, not suitable for end-user display; new error codes may be added over time. - **list_all_ding_connect_get_product_descriptions** — List localized product descriptions in DingConnect, optionally filtered by product SKU codes and language codes. Returns each record's SkuCode, LocalizationKey, and Descriptions with the localized strings per language. English (en) is always included, and not all items have translations in every language. - **list_all_ding_connect_get_products** — List Ding Connect products that can be used in SendTransfer, filterable by country, region, provider, SKU, benefit, and account number. Returns each product's SkuCode, ProviderCode, Minimum and Maximum prices, Benefits, ProcessingMode, RedemptionMechanism, SettingDefinitions, and UatNumber. Call GetProductDescriptions for localized product text. - **list_all_ding_connect_get_promotion_descriptions** — Get localized promotion description strings from DingConnect, each keyed to its promotion via LocalizationKey. Returns: Dates, Headline, TermsAndConditionsMarkDown, BonusValidity, PromotionType, LocalizationKey, LanguageCode, SendAmounts. Optionally filter by language_codes. - **list_all_ding_connect_get_promotions** — List the Ding promotions that may apply for the submitted criteria. Returns promotion records with id and validity_period_iso (ISO8601 duration, e.g. P30D is 30 days). Localized promotion text is provided separately by the GetPromotionDescriptions endpoint. - **list_all_ding_connect_get_providers** — List the DingConnect product providers available to the agent account, optionally filtered by provider codes, country ISOs, region codes, or an account number. Returns provider records including ProviderCode, Name, RegionCode, plus ValidationRegex, CustomerCareNumber, and LogoUrl where available. All query filters are optional; use international phone number format for phone-based account numbers. - **list_all_ding_connect_get_provider_status** — Get the current status of product providers in dingconnect to check whether it is possible to send a transfer to each one. Returns status entries including the agent-facing Message detail, which is unlocalized and not suitable for end users. Optionally filter with provider_codes. - **list_all_ding_connect_get_regions** — List the regions used in the Ding Connect system. Returns: RegionCode, RegionName, CountryIso. - **list_all_ding_connect_list_transfer_records** — Query transfer records submitted by the agent in DingConnect. Returns: TransferRecord (with TransferId, SkuCode, Price, CommissionApplied, StartedUtc, CompletedUtc, ProcessingState, ReceiptText, ReceiptParams, AccountNumber), ResultCode, and ErrorCodes. Only transfers from the last 2 months are searchable. Required: Take. - **create_a_ding_connect_lookup_bill** — Search available bills for an account in dingconnect before paying them via SendTransfer. Returns each matching bill's BillRef, Price (send/receive values, fees, tax), and AdditionalInfo. Only needed for products where LookupBillsRequired is true. Required: SkuCode, AccountNumber. - **create_a_ding_connect_send_transfer** — Send a transfer to an account in DingConnect. Returns the created transfer record with TransferId, SkuCode, Price (send/receive values, fees, tax), ProcessingState, CommissionApplied, AccountNumber, and receipt details. SkuCode must come from GetProducts; transfers exceeding 90 seconds return ProviderTimedOut and are not charged. Required: SkuCode, SendValue, AccountNumber, DistributorRef, ValidateOnly. ## How it works 1. **Link your customer's DingConnect account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach DingConnect.** The Proxy API is a 1-to-1 mapping of the DingConnect API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Automate global reward and incentive fulfillment** — HR, loyalty, and survey SaaS platforms can let their customers disburse mobile top-ups, data bundles, and digital gift cards to recipients in 150+ countries without negotiating individual telco contracts. Truto handles auth and connector maintenance so the integration ships in days, not quarters. - **Embed cross-border bill pay in fintech products** — White-label wallet and neobanking SaaS can offer their end users utility bill payments and prepaid recharges across emerging markets, bypassing SWIFT fees and KYC delays for micro-value transfers. - **Trigger instant customer goodwill from support workflows** — CX and helpdesk SaaS can let agents send apology top-ups or e-vouchers directly from a ticket view, turning service recovery into a one-click action tied to the customer's phone number. - **Power channel and gig-worker spiffs** — PRM and gig economy platforms can push instant micro-rewards — a data recharge, a grocery voucher — the moment a sale is logged or a shift is completed, replacing manual payout batches. - **Enable instant earnings cash-out to real-world utility** — Gig and payroll SaaS can let workers convert a slice of pending earnings into airtime, data, or utility bill payments on demand, without waiting for bank settlement cycles. ## What you can build - **Smart recipient lookup by phone number** — Use account lookups to auto-detect the carrier and region from an MSISDN and filter the product catalog without asking the user to pick a country or operator. - **Live product and promotion catalog sync** — Continuously sync products, product descriptions, promotions, and promotion descriptions to keep SKUs, pricing bands, and localized flash-sale banners accurate in your UI. - **Pre-transaction price and bill preview** — Call estimate price and lookup bill to show the exact send amount, receive amount, FX, and taxes before the user confirms a transfer. - **Asynchronous transfer execution with status tracking** — Submit transfers via send transfer and reconcile ProcessingState by polling list transfer records, surfacing success, pending, and failure states back to the end user. - **Low-balance alerts for prepaid agent wallets** — Poll get balances to drive automated notifications and dashboards that warn admins before their Ding wallet runs dry and starts failing payouts. - **Failsafe routing and fraud clawback** — Hide SKUs in real time using provider status checks, and batch-cancel suspicious transfers through cancel transfer when fraud is detected downstream. ## FAQs ### How does authentication to DingConnect work through Truto? Truto manages the DingConnect API credentials your end users provide during the connect flow, including secure storage, header signing, and rotation. Your application calls Truto's unified endpoints and we attach the correct auth per-connection. ### Which DingConnect operations are available today? Truto exposes catalog and reference endpoints (countries, regions, currencies, providers, provider status, products, product descriptions, promotions, promotion descriptions, error code descriptions), account tooling (account lookups, balances), transaction preview (estimate price, lookup bill), and transaction execution (send transfer, list transfer records, cancel transfer). ### How should we handle transfers that take time to settle? DingConnect transfers can take up to ~90 seconds as they route through global operators. Build send transfer as an async job and reconcile the final ProcessingState by polling list transfer records before notifying the end user. ### How do we keep the product catalog fresh? Telcos change pricing bands, data limits, and promotions frequently. We recommend scheduled syncs of get products, get product descriptions, get promotions, and get promotion descriptions on an interval that matches your UX (hourly or daily is typical). ### Can we cancel or refund a transfer? Yes. You can pass transfer IDs to the cancel transfer endpoint to attempt a clawback, which is useful for fraud response or user-initiated reversals. Cancellation success depends on the current ProcessingState returned by list transfer records. ### How do we avoid surfacing SKUs from providers that are down? Poll get provider status and intersect it with your cached catalog before rendering options. This prevents end users from attempting top-ups against operators that are currently unavailable. ### Does Truto offer a unified Payment Gateway API for DingConnect? Not yet — DingConnect is available as a dedicated connector with direct access to its native endpoints. You get normalized auth, pagination, and error handling through Truto while working against DingConnect's own schema.