Milta

Introduction

Milta Wallet Partner API provides access to a global marketplace of digital products and services through a single, intuitive REST API designed for scale and reliability. It enables partners to execute instant purchases, manage international transfers, and deliver redemption codes seamlessly. With this comprehensive API, developers can integrate product catalogs, process transactions, and offer international reload services, including mobile top-ups, gift cards, gaming products, and digital payment solutions.


Core Capabilities Include:

  • 1.  Product Catalog: Browse categories, brands, and local products (mobile top-ups, gift cards, gaming, payment cards)
  • 2.  International Services: Access international providers and products for cross-border remittances and transfers
  • 3.  Transaction Management: Execute purchases, validate orders, track transactions, and manage redemption codes
  • 4.  Service Reliability: High-volume transaction support with robust error handling, rate limiting, and idempotency

Built for developers who demand reliability, speed, and simplicity. Stable and currently the only version available for integration. Future updates will be introduced as new versions (e.g., v2) to ensure backward compatibility and avoid breaking changes for existing integrations.

Base URL

https://api.dev.wallet.milta.be/api/v1/partner

All API endpoints are relative to this base path

RESTful Design

Predictable resource-oriented URLs and standard HTTP methods

JSON Everywhere

All requests and responses use JSON with UTF-8 encoding

Comprehensive Errors

Detailed error messages with codes for easy debugging purposes.

Authentication

All API requests require HTTP Basic Authentication. Use your API Key ID as the username and API Key Secret as the password.

Keep your credentials secure

Never expose your API Key ID or Secret in client-side code, public repositories, or version control. Treat them like passwords and rotate them regularly.

Basic Authentication

Most HTTP clients support Basic Auth natively. The credentials are sent in the Authorization header as a Base64-encoded string.

CredentialDescription
UsernameYour API Key ID
PasswordYour API Key Secret

Example Requests

# Using cURL with Basic Auth
curl -u "YOUR_API_KEY_ID:YOUR_API_KEY_SECRET" \
  https://api.dev.wallet.milta.be/api/v1/partner/inventories/categories
// JavaScript/Node.js
const credentials = Buffer.from(`${apiKeyId}:${apiKeySecret}`).toString('base64');

fetch('https://api.dev.wallet.milta.be/api/v1/partner/inventories/categories', {
  method: 'GET',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  }
});

Quick Start

Get up and running in minutes with our quick start guide.

1

Receive your account invitation

Your wholesaler admin creates your user account. Check your email for the invitation link.

2

Reset your temporary password & sign in

Use the invitation email to reset your temporary password and log in to the Milta Wholesalers platform.

3

Generate your API key

Navigate to Developer Center and create a new API key for integration.

4

Make your first API request

Use your API key to test the API with a simple request and verify connectivity.

5

Configure IP whitelist (optional)

Enhance security by restricting API access to specific IP addresses.

Test with Postman

Import our Postman collection to quickly test API endpoints without writing code. Our collection includes pre-configured requests for all endpoints with example payloads.

Run in Postman

One-click import directly into your Postman workspace.

Setup Instructions

1

Import the Collection

Download and import the JSON file into Postman, or use the "Run in Postman" button for quick setup.

2

Configure Basic Authentication

In Postman, go to the Authorization tab and select Basic Auth. Use your API Key ID as the username and API Key as the password.

3

Set Up Environment (Optional)

Create a Postman environment to store your API Key ID and API Key for easier reuse across requests.

4

Start Testing

Select a request, review required parameters, and click Send to test the endpoint.

Terminology

Understanding key terms used throughout our API documentation will help you integrate more effectively.

API Key

A unique credential pair (ID and Secret) used for authenticating partner requests to the APIs. Provided as Basic Auth credentials (username: API Key ID, password: API Key Secret). Each API key is associated with a specific wholesaler company and environment.

SKU Code

Stock Keeping Unit - A unique identifier assigned to each product in the inventory system. Used to retrieve detailed product information, pricing, and availability.

Commission

The profit margin or percentage earned by a wholesaler for each transaction. Commission rates are defined within a Scheme.

Brand

A product manufacturer or service provider (e.g., Apple, Amazon, Samsung). Partners can filter products by brand and manage brand display order through the platform.

Category

A product classification group such as Mobile Top-Up, Gift Cards, Gaming, or Payment Cards. Used to organize and filter products in API responses.

Rate Limit

A threshold on the number of API requests allowed within a specified time window (per 10 seconds, per minute, per hour, per day). When exceeded, the API returns a 429 Too Many Requests status. Limits are enforced per API Key.

Basic Auth

HTTP Basic Authentication method used for partner API endpoints. Credentials are encoded in Base64 format in the Authorization header as 'Basic <base64(apiKeyId:apiKeySecret)>'.

Provider

A third-party service that supplies or facilitates products (e.g., a mobile carrier, gift card issuer). Providers handle the actual fulfillment of transactions on behalf of the platform.

Pagination

A mechanism for retrieving large datasets in smaller, manageable chunks. Uses 'page' and 'limit' parameters. Page numbers start from 1, and limits define items per page (typically max 50).

Page

A page number used for pagination (1-based indexing). Combined with 'limit' to retrieve specific subsets of products or brands.

Limit

The number of items to return per page in a paginated API response. Typical max limit is 50 items per page to balance performance and data transfer.

Shorten Response

A query parameter (shorten=true) that returns minimal brand information (ID and name only) instead of the full response with logos and additional metadata. Improves performance when full details are not needed.

API Responses

All API responses follow a consistent JSON structure with standard HTTP status codes.

Success Response Format

{
"message": "Operation completed successfully",
"data": {
  // Response data returned by this endpoint
}
}

Error Response Format

{
"statusCode": 400,
"message": "Request failed",
"error": {
  "code": "ACCS-001",
  "detail": "A brief description of what went wrong.",
  "solution": "Suggested action for resolving the issue."
}
}

HTTP Status Codes

CodeMeaningDescription
200OKRequest succeeded
400Bad RequestInvalid request parameters
404Not FoundRequested resource does not exist
401UnauthorizedInvalid or missing API key
403ForbiddenAccess denied to the requested resource
409ConflictResource conflict or duplicate request
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error - retry with backoff
503Service UnavailableServer is temporarily unavailable - retry with backoff

Error Codes

Comprehensive list of error codes you may encounter when using the API.

CodeDomainDescription
ACCS-001AccessProduct not accessible
AUTH-010AuthInvalid API key (key ID does not exist)
AUTH-011AuthInvalid API key context
AUTH-012AuthAPI key is not active
AUTH-020AuthWholesaler company not found
AUTH-021AuthWholesaler company is not active
AUTH-030AuthIP address not whitelisted
AUTH-031AuthInvalid client IP format
INVT-010InventoryBrand fetch failed
INVT-011InventoryCategory fetch failed
INVT-020InventoryProduct list fetch failed
INVT-021InventoryProduct detail fetch failed
INVT-022InventoryProduct not found
INVT-023InventoryProduct not available
INVT-024InventoryProduct not available in country
INVT-025InventoryInvalid product
INVT-026InventoryProduct configuration invalid
INVT-027InventoryInsufficient product availability
INVT-030InventoryInternational product not found
INVT-031InventoryInternational products fetch failed
INVT-032InventoryInternational product by SKU fetch failed
INVT-033InventoryInternational commission not configured
INVT-040InventoryInternational provider not found
INVT-041InventoryInternational providers fetch failed
INVT-051InventoryWholesaler scheme not configured
RTLM-001 Rate LimitToo many requests
SYST-010SystemInternal server error
SYST-020SystemProduct temporarily unavailable (internal)
SYST-030SystemExternal — provider service failure
SYST-031SystemExternal — provider validation failed
SYST-032SystemExternal — service temporarily unavailable
SYST-033SystemExternal — international product fetch failed
SYST-034SystemExternal — SKU lookup failed
TRXN-010TransactionDuplicate transfer reference
TRXN-020TransactionOrder placement failed
TRXN-021TransactionInternational reload processing failed
TRXN-031TransactionTransaction not found
TRXN-040TransactionDestination number country code mismatch
VALD-001ValidationRequest validation failed (generic)
VALD-010ValidationCountry code is required
VALD-011ValidationCountry code must be a string
VALD-012ValidationInvalid country code format (ISO)
VALD-013ValidationInvalid country code
VALD-014ValidationInvalid country ISO code
VALD-015ValidationCountry ISO code must be a string
VALD-020ValidationPage must be positive integer
VALD-021ValidationLimit out of range
VALD-030ValidationSKU code required
VALD-031ValidationSKU code must not be empty string
VALD-032ValidationInvalid SKU code format
VALD-040ValidationQuantity is required
VALD-041ValidationQuantity must be positive
VALD-042ValidationQuantity must be a positive integer
VALD-043ValidationQuantity must not exceed 5
VALD-050ValidationTransfer reference required
VALD-051ValidationTransfer reference must be non-empty string
VALD-060ValidationSent amount is required
VALD-061ValidationSent amount must be a positive number
VALD-070ValidationDestination number is required
VALD-071ValidationDestination number format is invalid
VALD-072ValidationInvalid mobile number format (E.164)
VALD-073ValidationDestination country code mismatch
VALD-080ValidationInvalid reload amount
VALD-090ValidationInvalid brand ID format
VALD-091ValidationInvalid category value
VALD-092ValidationCategory must be a valid brand category
VALD-100ValidationProvider ID must be a string
VALD-101ValidationInvalid provider ID
VALD-110ValidationContact number too long
VALD-111ValidationContact number format invalid
VALD-120ValidationinStock must be boolean
VALD-121Validationshorten must be boolean
VALD-122ValidationvalidateOnly must be boolean
VALD-123ValidationvalidateOnly is required
VALD-124ValidationInvalid ID format
WALT-001WalletInsufficient wallet balance
WALT-002WalletWallet not found

Method Usage Limits

Rate limits are enforced per API key to ensure fair usage and platform stability. When a limit is exceeded, the API responds with HTTP 429 Too Many Requests.

EndpointRate Limit (per 10 sec)Rate Limit (per min)Notes
GET /inventories/categories20 req100 reqFetch available product categories. Used for dropdowns/filters. Can be cached.
GET /inventories/brands15 req80 reqFetch brands under a category. Triggered when category changes. Avoid frequent re-fetching.
GET /inventories/products15 req80 reqFetch product list for a selected brand/category. Supports listing and browsing.
GET /inventories/products/{skuCode}15 req80 reqFetch detailed product info by SKU. Used in product detail view. Avoid repeated calls for same SKU.
GET /inventories/international/providers10 req50 reqFetch available international service providers. Used before selecting international products.
GET /inventories/international/products10 req50 reqFetch international products based on provider/country. Used for international reload flows.
GET /inventories/international/products/{skuCode}10 req50 reqFetch details of a specific international product. Used before pricing/validation.
GET /transactions/{transactionId}15 req80 reqFetch transaction status/details. Used for polling transaction updates after purchase.
POST /transactions/purchase10 req50 reqCreate a purchase transaction for local products. Critical endpoint — must avoid duplicate calls.
POST /transactions/international/validate-convert-reload-amount10 req50 reqValidate and convert reload amount for international transactions. Used before confirming purchase.
POST /transactions/international-reload10 req50 reqExecute international reload transaction. Final step after validation. Must prevent retries/duplicates.

Handling 429 Errors

// Retry with exponential backoff
async function requestWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw err;
      }
    }
  }
}
Note: Rate limit windows reset every 60 seconds. The response headers include X-RateLimit-Remaining and X-RateLimit-Reset to help you manage your request pace.

Querying

List endpoints support query parameters to filter and refine results. Parameters are passed as URL query strings and are always optional unless stated otherwise.

ParameterTypeDescription
categorystringFilter brands or products by category.
shortenbooleanReturn minimal brand or product data.
brandIdstringFilter products by brand ID.
countryCode/ countryIsostringFilter products or providers by country (ISO 3166-1 alpha-2 format, e.g. BE, FR).
inStockbooleanFilter products by stock availability. true = in stock, false = out of stock.
transactionIdstringRetrieve transaction by ID.
skuCodestringUnique product SKU identifier.
mobileNumberstringPhone number used to check supported providers or products.
providerIdstringFilter international products by provider ID.

Example

GET /inventories/products?country=GB&currency=GBP&productType=TOPUP

Authorization: Basic {base64(apiKeyId:apiKeySecret)}

Paging

Endpoints that return collections support pagination to manage large result sets. Use the page and pageSize query parameters to navigate through results.

ParameterTypeDescription
pageintegerPage number (1-based). Defaults to 1.
limitintegerNumber of items per page. Defaults to 10, max 200.

Sample Paginated Response

{
    "message": "Products fetched successfully",
    "data": {
        "products": [ ... ],
        "totalProducts": 9,
        "totalPages": 1,
        "currentPage": 1
    }
}

Reference Data

Reference data endpoints provide static or slowly-changing information about supported countries, currencies, providers, and products. Cache these responses to reduce API calls.

MethodEndpointDescription
GET/inventories/categoriesList all available product categories
GET/inventories/brandsList all available brands
GET/inventories/productsList all products
GET/inventories/international/providersList all available international providers
GET/inventories/international/productsList all available international products

Example Response

GET /inventories/brands

{
    "success": true,
    "message": "Brands retrieved successfully",
    "data": {
        "brands": [
            {
                "id": "6a0c49c857a2d8c5327f4567",
                "uid": "BID0015",
                "name": "Orange",
                "logoUrl": "https://cdn.wallet.milta.be/local/brands/..."
            },
            {
                "id": "6a0c497857a2d8c5327f4123",
                "uid": "BID0011",
                "name": "Libon",
                "logoUrl": "https://cdn.wallet.milta.be/local/brands/..."
            },
        ],
        "totalBrands": 2,
        "totalPages": 1,
        "currentPage": 1
    },
    "error": null
}

Optional Features

The Milta Partner API offers several optional features that can be enabled to enhance your integration.

IP Allowlisting

Restrict API access to specific IP addresses or CIDR ranges for additional security. Configurable per API key from the developer settings panel.

Need something custom? Contact your Milta account manager or reach out via the partner dashboard to discuss feature requirements tailored to your integration.