Wallet Withdraw to Mobile

Withdraw funds from your UpesiPay wallet to MPESA or Airtel Money

POST https://upesipay.com/api/v2/withdraw

Headers

Parameter	Type	Description
Authorization*	String	Basic auth token
Content-Type*	String	application/json

Request Body

Parameter	Type	Description
external_reference	String	Your unique reference to track this transaction (e.g., INV-009)
amount*	Integer	Withdrawal amount (e.g., 100)
phone_number*	String	Phone number in international format (e.g., 254787677676). Must start with country code
network_code*	String	Mobile money provider code: 63902 (MPESA) or 63903 (Airtel Money)
callback_url	String	Your endpoint URL that we will use to send payment status response (e.g., https://example.com/callback.php)
channel*	String	Value: `mobile`
channel_id	Integer	Your Payment Wallet Channel ID
payment_service	String	Value: `b2c`

Responses

201 Created

{
  "status": "QUEUED",
  "merchant_reference": "W5ZBQBHJOS",
  "checkout_request_id": "553125-97e66f37-200d-47ef-84bb-eb9b64ab8ad5",
  "response_code": "0",
  "conversation_id": "97e66f37-200d-47ef-84bb-eb9b64ab8ad5"
}

Notes

network_code: 63902 for MPESA, 63903 for Airtel Money
phone_number: Must start with country code (e.g., 254 for Kenya)
Callback URL: Will receive payment status updates

Try It Out

Please set your authentication token in the sidebar to test this API.

Headers

Authorization *

Content-Type *

Request Body

amount *

phone_number *

network_code *

channel *

external_reference

callback_url

channel_id

payment_service

Code Samples

curl -X POST \
  'https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet' \
  -H 'Authorization: Basic YOUR_AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{{"external_reference":"INV-009","amount":100,"phone_number":"254787677676","network_code":"63902","callback_url":"https://example.com/callback.php","channel":"mobile","payment_service":"b2c"}}'

const url = 'https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Basic YOUR_AUTH_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    external_reference: 'INV-009',
    amount: 100,
    phone_number: '254787677676',
    network_code: '63902',
    callback_url: 'https://example.com/callback.php',
    channel: 'mobile',
    payment_service: 'b2c'
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const axios = require('axios');

const config = {
  method: 'post',
  url: 'https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet',
  headers: {
    'Authorization': 'Basic YOUR_AUTH_TOKEN',
    'Content-Type': 'application/json'
  },
  data: {
    external_reference: 'INV-009',
    amount: 100,
    phone_number: '254787677676',
    network_code: '63902',
    callback_url: 'https://example.com/callback.php',
    channel: 'mobile',
    payment_service: 'b2c'
  }
};

axios(config)
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
    'external_reference' => 'INV-009',
    'amount' => 100,
    'phone_number' => '254787677676',
    'network_code' => '63902',
    'callback_url' => 'https://example.com/callback.php',
    'channel' => 'mobile',
    'payment_service' => 'b2c'
  )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic YOUR_AUTH_TOKEN',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);
echo $response;

import requests

url = 'https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet'

headers = {
    'Authorization': 'Basic YOUR_AUTH_TOKEN',
    'Content-Type': 'application/json'
}

data = {
    'external_reference': 'INV-009',
    'amount': 100,
    'phone_number': '254787677676',
    'network_code': '63902',
    'callback_url': 'https://example.com/callback.php',
    'channel': 'mobile',
    'payment_service': 'b2c'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

var client = HttpClient.newHttpClient();

var body = "{\"external_reference\":\"INV-009\",\"amount\":100,\"phone_number\":\"254787677676\",\"network_code\":\"63902\",\"callback_url\":\"https://example.com/callback.php\",\"channel\":\"mobile\",\"payment_service\":\"b2c\"}";

var request = HttpRequest.newBuilder()
  .uri(URI.create('https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet'))
  .header('Authorization', 'Basic YOUR_AUTH_TOKEN')
  .header('Content-Type', 'application/json')
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build;

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

package main

import (
  "fmt"
  "net/http"
  "io"
  "bytes"
)

data := []byte(`{{"external_reference":"INV-009","amount":100,"phone_number":"254787677676","network_code":"63902","callback_url":"https://example.com/callback.php","channel":"mobile","payment_service":"b2c"}}`)
req, _ := http.NewRequest("POST", "https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet", bytes.NewBuffer(data))

req.Header.Set("Authorization", "Basic YOUR_AUTH_TOKEN")
req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

require 'net/http'
require 'json'

uri = URI('https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet')

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Basic YOUR_AUTH_TOKEN'
request['Content-Type'] = 'application/json'
request.body = JSON.generate({ external_reference: 'INV-009', amount: 100, phone_number: '254787677676', network_code: '63902', callback_url: 'https://example.com/callback.php', channel: 'mobile', payment_service: 'b2c' })

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

response = http.request(request)
puts JSON.parse(response.body)

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        var body = new { external_reference = \"INV-009\", amount = 100, phone_number = \"254787677676\", network_code = \"63902\", callback_url = \"https://example.com/callback.php\", channel = \"mobile\", payment_service = \"b2c\" };
        var content = new StringContent(JsonSerializer.Serialize(body), System.Text.Encoding.UTF8, \"application/json\");
        
        var request = new HttpRequestMessage(HttpMethod.Post, \"https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet\")  { Content = content };
        request.Headers.Add(\"Authorization\", \"Basic YOUR_AUTH_TOKEN\");
        
        var response = await client.SendAsync(request);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    {
}

import Foundation

let url = URL(string: \"https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet\")!
var request = URLRequest(url: url)

request.httpMethod = \"POST\"
request.setValue(\"Basic YOUR_AUTH_TOKEN\", forHTTPHeaderField: \"Authorization\")
request.setValue(\"application/json\", forHTTPHeaderField: \"Content-Type\")

let body = [\"external_reference\": \"INV-009\", \"amount\": 100, \"phone_number\": \"254787677676\", \"network_code\": \"63902\", \"callback_url\": \"https://example.com/callback.php\", \"channel\": \"mobile\", \"payment_service\": \"b2c\"]
request.httpBody = try? JSONSerialization.data(withJSONObject: body)

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data {
        if let json = try? JSONSerialization.jsonObject(with: data) {
            print(json)
        }
    }
}
task.resume()

import okhttp3.*
import java.io.IOException

val client = OkHttpClient()
val body = """{{"external_reference":"INV-009","amount":100,"phone_number":"254787677676","network_code":"63902","callback_url":"https://example.com/callback.php","channel":"mobile","payment_service":"b2c"}}""".toRequestBody(\"application/json\".toMediaType())

val request = Request.Builder()
    .url(\"https://upesipay.com/api/v2/withdraw?wallet_type=service_wallet\")
    .addHeader(\"Authorization\", \"Basic YOUR_AUTH_TOKEN\")
    .post(body)
    .build)

client.newCall(request).enqueue(object : Callback {
    override fun onFailure(call: Call, e: IOException) {
        e.printStackTrace()
    }

    override fun onResponse(call: Call, response: Response) {
        println(response.body?.string())
    }
})

Was this page helpful?

Top up your service wallet with funds.

Service Wallet Top Up

Check the status of your payment transaction.

Get Transaction Status

Wallet Withdraw to Mobile

Headers

Request Body

Responses

201 Created

Notes

Try It Out

Headers

Request Body

Code Samples

Was this page helpful?

Previous

Next