PayBill Requests

Introduction

The Paybill Request feature enables users and businesses to initiate payouts from their account to end customers or partners via our API. This documentation covers the v3 endpoint for withdrawal transactions, including authentication, request/response formats, and code examples.

Making Paybill Requests

To initiate a withdrawal request, users need to make an HTTP POST request to the specified endpoint with the required parameters.

Endpoint

https://api.mypayd.app/api/v3/withdrawal

Authorization

Users need to include basic authentication credentials in the request headers.

AUTHORIZATION: Basic Auth

Username  <username>
Password  <password>

Request Body (Token Object)

The request body should include the necessary parameters for the paybill request, such as the account ID, recipient's phone number, withdrawal amount, narration, callback URL, and channel.

json

{
  "username": "payduser",
  "amount": 12,
  "currency": "KES",
  "phone_number": "+254712345678",
  "narration": "Payment for goods",
  "transaction_channel": "bank",
  "channel": "bank",
  "business_account": "714777",
  "business_number": "0712345678",
  "callback_url": "https://payd-test.free.beeceptor.com"
}

Code Examples

Below are code examples in different programming languages demonstrating how to pay via Paybill to businesses using HTTP POST requests.

Curl

curl --location 'https://api.mypayd.app/api/v3/withdrawal' \
--data '

{
"username": "payduser",
"amount": 12,
"currency": "KES",
"phone_number": "+254712345678",
"narration": "Payment for goods",
"transaction_channel": "bank",
"channel": "bank",
"business_account": "714777",
"business_number": "0712345678",
"callback_url": "https://payd-test.free.beeceptor.com"
}

'

Go

package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

func main() {

url := "https://api.mypayd.app/api/v3/withdrawal"
method := "POST"

payload := strings.NewReader(`

{
"username": "payduser",
"amount": 12,
"currency": "KES",
"phone_number": "+254712345678",
"narration": "Payment for goods",
"transaction_channel": "bank",
"channel": "bank",
"business_account": "714777",
"business_number": "0712345678",
"callback_url": "https://payd-test.free.beeceptor.com"
}

`)

client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)

if err != nil {
fmt.Println(err)
return
}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}

Nodejs

var axios = require('axios');
var data = '{
"username": "payduser",
"amount": 12,
"currency": "KES",
"phone_number": "+254712345678",
"narration": "Payment for goods",
"transaction_channel": "bank",
"channel": "bank",
"business_account": "714777",
"business_number": "0712345678",
"callback_url": "https://payd-test.free.beeceptor.com"
}';

var config = {
method: 'post',
maxBodyLength: Infinity,
url: 'https://api.mypayd.app/api/v3/withdrawal',
headers: { },
data : data
};

axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

Python

import requests

url = "https://api.mypayd.app/api/v3/withdrawal"

payload = {
"username": "payduser",
"amount": 12,
"currency": "KES",
"phone_number": "+254712345678",
"narration": "Payment for goods",
"transaction_channel": "bank",
"channel": "bank",
"business_account": "714777",
"business_number": "0712345678",
"callback_url": "https://payd-test.free.beeceptor.com"
}
headers = {}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

PHP

var axios = require('axios');
var data = '{\n <?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.mypayd.app/api/3/withdrawal');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setBody('{
"username": "payduser",
"amount": 12,
"currency": "KES",
"phone_number": "+254712345678",
"narration": "Payment for goods",
"transaction_channel": "bank",
"channel": "bank",
"business_account": "714777",
"business_number": "0712345678",
"callback_url": "https://payd-test.free.beeceptor.com"
});
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}

Example of a successful response

{
  "success": true,
  "correlator_id": "12345abcd",
  "message": "Payout processed successfully",
  "status": "completed"
}

</Tabs>

Conclusion

The paybill requests feature provides a convenient way for users to pay for good and services from their accounts securely. By following the instructions outlined in this documentation, users can easily integrate paybill requests into their applications or services.