Introduction

Welcome to the Milta Wallet Partner API documentation. This API allows partners to integrate wallet, transaction, and payment services. Our REST API provides comprehensive endpoints for managing transfers, account balances, pricing estimates, and reference data. Built with developers in mind, our API is designed to be intuitive, consistent, and powerful.

Authentication

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

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', {
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  }
});

Quick Start

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

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.

Setup Instructions

Terminology

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

API Responses

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

Error Codes

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

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.

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;
      }
    }
  }
}

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.

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.

Paginated Response

{
  "status": "success",
  "data": {
    "items": [ ... ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 84,
      "totalPages": 5
    }
  }
}

Batching

Submit multiple transfer requests in a single API call using the batch endpoint. Batching reduces network overhead and simplifies bulk operations.

Batch Limits

Batch Request

POST /transfers/batch

{
  "transfers": [
    {
      "externalId": "TXN-001",
      "productId": "PRODUCT_123",
      "recipientPhone": "+447700900001",
      "amount": 10.00,
      "currency": "GBP"
    },
    {
      "externalId": "TXN-002",
      "productId": "PRODUCT_456",
      "recipientPhone": "+447700900002",
      "amount": 5.00,
      "currency": "GBP"
    }
  ]
}

Batch Response

{
  "status": "success",
  "data": {
    "batchId": "BATCH-20260101-ABC",
    "accepted": 2,
    "rejected": 0,
    "transfers": [
      { "externalId": "TXN-001", "status": "PENDING", "transferId": "T-9001" },
      { "externalId": "TXN-002", "status": "PENDING", "transferId": "T-9002" }
    ]
  }
}

Localization

The API supports locale-aware responses. Pass localization headers to receive product names, descriptions, and messages in the preferred language and currency format.

Example

GET /inventories/products
Accept-Language: fr-FR
X-Currency: EUR
X-Country: FR
Authorization: Basic {base64(apiKeyId:apiKeySecret)}

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.

Example Response

GET /inventories/countries

{
  "status": "success",
  "data": {
    "items": [
      { "code": "GB", "name": "United Kingdom", "currencyCode": "GBP" },
      { "code": "FR", "name": "France", "currencyCode": "EUR" },
      { "code": "NG", "name": "Nigeria", "currencyCode": "NGN" }
    ]
  }
}

Deferred SendTransfer

Schedule transfers for future execution using the deferred transfer feature. This allows you to prepare transfers in advance and have them execute automatically at the specified time.

How It Works

Request Example

POST /transfers

{
  "externalId": "TXN-20260101-001",
  "productId": "PRODUCT_123",
  "recipientPhone": "+447700900001",
  "amount": 10.00,
  "currency": "GBP",
  "deferred": true,
  "scheduledAt": "2026-01-15T09:00:00Z"
}

Check Status

GET /transfers/T-9001

{
  "status": "success",
  "data": {
    "transferId": "T-9001",
    "externalId": "TXN-20260101-001",
    "status": "SCHEDULED",
    "scheduledAt": "2026-01-15T09:00:00Z",
    "amount": 10.00,
    "currency": "GBP"
  }
}

Optional Features

The Milta Partner API offers several optional features that can be enabled to enhance your integration. Contact your account manager to enable features marked "Available on request".