Deposit via Payment Page

curl --request POST \
  --url https://api.sandbox.pawapay.io/v2/paymentpage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "returnUrl": "https://merchant.example.com/checkout-result",
  "customerMessage": "Note of 4 to 22 chars",
  "amountDetails": {
    "amount": "15",
    "currency": "ZMW"
  },
  "phoneNumber": "260763456789",
  "language": "EN",
  "country": "ZMB",
  "reason": "Ticket to festival",
  "metadata": [
    {
      "orderId": "ORD-123456789"
    },
    {
      "customerId": "customer@email.com",
      "isPII": true
    }
  ]
}
'

import requests

url = "https://api.sandbox.pawapay.io/v2/paymentpage"

payload = {
    "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
    "returnUrl": "https://merchant.example.com/checkout-result",
    "customerMessage": "Note of 4 to 22 chars",
    "amountDetails": {
        "amount": "15",
        "currency": "ZMW"
    },
    "phoneNumber": "260763456789",
    "language": "EN",
    "country": "ZMB",
    "reason": "Ticket to festival",
    "metadata": [
        { "orderId": "ORD-123456789" },
        {
            "customerId": "customer@email.com",
            "isPII": True
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    depositId: 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',
    returnUrl: 'https://merchant.example.com/checkout-result',
    customerMessage: 'Note of 4 to 22 chars',
    amountDetails: {amount: '15', currency: 'ZMW'},
    phoneNumber: '260763456789',
    language: 'EN',
    country: 'ZMB',
    reason: 'Ticket to festival',
    metadata: [{orderId: 'ORD-123456789'}, {customerId: 'customer@email.com', isPII: true}]
  })
};

fetch('https://api.sandbox.pawapay.io/v2/paymentpage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.pawapay.io/v2/paymentpage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'depositId' => 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',
    'returnUrl' => 'https://merchant.example.com/checkout-result',
    'customerMessage' => 'Note of 4 to 22 chars',
    'amountDetails' => [
        'amount' => '15',
        'currency' => 'ZMW'
    ],
    'phoneNumber' => '260763456789',
    'language' => 'EN',
    'country' => 'ZMB',
    'reason' => 'Ticket to festival',
    'metadata' => [
        [
                'orderId' => 'ORD-123456789'
        ],
        [
                'customerId' => 'customer@email.com',
                'isPII' => true
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.sandbox.pawapay.io/v2/paymentpage"

	payload := strings.NewReader("{\n  \"depositId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"returnUrl\": \"https://merchant.example.com/checkout-result\",\n  \"customerMessage\": \"Note of 4 to 22 chars\",\n  \"amountDetails\": {\n    \"amount\": \"15\",\n    \"currency\": \"ZMW\"\n  },\n  \"phoneNumber\": \"260763456789\",\n  \"language\": \"EN\",\n  \"country\": \"ZMB\",\n  \"reason\": \"Ticket to festival\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.pawapay.io/v2/paymentpage")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"depositId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"returnUrl\": \"https://merchant.example.com/checkout-result\",\n  \"customerMessage\": \"Note of 4 to 22 chars\",\n  \"amountDetails\": {\n    \"amount\": \"15\",\n    \"currency\": \"ZMW\"\n  },\n  \"phoneNumber\": \"260763456789\",\n  \"language\": \"EN\",\n  \"country\": \"ZMB\",\n  \"reason\": \"Ticket to festival\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.pawapay.io/v2/paymentpage")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"depositId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"returnUrl\": \"https://merchant.example.com/checkout-result\",\n  \"customerMessage\": \"Note of 4 to 22 chars\",\n  \"amountDetails\": {\n    \"amount\": \"15\",\n    \"currency\": \"ZMW\"\n  },\n  \"phoneNumber\": \"260763456789\",\n  \"language\": \"EN\",\n  \"country\": \"ZMB\",\n  \"reason\": \"Ticket to festival\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "status": "REJECTED",
  "failureReason": {
    "failureCode": "PROVIDER_TEMPORARILY_UNAVAILABLE",
    "failureMessage": "The provider 'MTN_MOMO_ZMB' is currently not able to process payments. Please consult our status page for downtime information on all providers. Programmatic access is also available, please consult our API docs."
  }
}

POST

paymentpage

Deposit via Payment Page

curl --request POST \
  --url https://api.sandbox.pawapay.io/v2/paymentpage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "returnUrl": "https://merchant.example.com/checkout-result",
  "customerMessage": "Note of 4 to 22 chars",
  "amountDetails": {
    "amount": "15",
    "currency": "ZMW"
  },
  "phoneNumber": "260763456789",
  "language": "EN",
  "country": "ZMB",
  "reason": "Ticket to festival",
  "metadata": [
    {
      "orderId": "ORD-123456789"
    },
    {
      "customerId": "customer@email.com",
      "isPII": true
    }
  ]
}
'

import requests

url = "https://api.sandbox.pawapay.io/v2/paymentpage"

payload = {
    "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
    "returnUrl": "https://merchant.example.com/checkout-result",
    "customerMessage": "Note of 4 to 22 chars",
    "amountDetails": {
        "amount": "15",
        "currency": "ZMW"
    },
    "phoneNumber": "260763456789",
    "language": "EN",
    "country": "ZMB",
    "reason": "Ticket to festival",
    "metadata": [
        { "orderId": "ORD-123456789" },
        {
            "customerId": "customer@email.com",
            "isPII": True
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    depositId: 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',
    returnUrl: 'https://merchant.example.com/checkout-result',
    customerMessage: 'Note of 4 to 22 chars',
    amountDetails: {amount: '15', currency: 'ZMW'},
    phoneNumber: '260763456789',
    language: 'EN',
    country: 'ZMB',
    reason: 'Ticket to festival',
    metadata: [{orderId: 'ORD-123456789'}, {customerId: 'customer@email.com', isPII: true}]
  })
};

fetch('https://api.sandbox.pawapay.io/v2/paymentpage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.pawapay.io/v2/paymentpage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'depositId' => 'f4401bd2-1568-4140-bf2d-eb77d2b2b639',
    'returnUrl' => 'https://merchant.example.com/checkout-result',
    'customerMessage' => 'Note of 4 to 22 chars',
    'amountDetails' => [
        'amount' => '15',
        'currency' => 'ZMW'
    ],
    'phoneNumber' => '260763456789',
    'language' => 'EN',
    'country' => 'ZMB',
    'reason' => 'Ticket to festival',
    'metadata' => [
        [
                'orderId' => 'ORD-123456789'
        ],
        [
                'customerId' => 'customer@email.com',
                'isPII' => true
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.sandbox.pawapay.io/v2/paymentpage"

	payload := strings.NewReader("{\n  \"depositId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"returnUrl\": \"https://merchant.example.com/checkout-result\",\n  \"customerMessage\": \"Note of 4 to 22 chars\",\n  \"amountDetails\": {\n    \"amount\": \"15\",\n    \"currency\": \"ZMW\"\n  },\n  \"phoneNumber\": \"260763456789\",\n  \"language\": \"EN\",\n  \"country\": \"ZMB\",\n  \"reason\": \"Ticket to festival\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.pawapay.io/v2/paymentpage")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"depositId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"returnUrl\": \"https://merchant.example.com/checkout-result\",\n  \"customerMessage\": \"Note of 4 to 22 chars\",\n  \"amountDetails\": {\n    \"amount\": \"15\",\n    \"currency\": \"ZMW\"\n  },\n  \"phoneNumber\": \"260763456789\",\n  \"language\": \"EN\",\n  \"country\": \"ZMB\",\n  \"reason\": \"Ticket to festival\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.pawapay.io/v2/paymentpage")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"depositId\": \"f4401bd2-1568-4140-bf2d-eb77d2b2b639\",\n  \"returnUrl\": \"https://merchant.example.com/checkout-result\",\n  \"customerMessage\": \"Note of 4 to 22 chars\",\n  \"amountDetails\": {\n    \"amount\": \"15\",\n    \"currency\": \"ZMW\"\n  },\n  \"phoneNumber\": \"260763456789\",\n  \"language\": \"EN\",\n  \"country\": \"ZMB\",\n  \"reason\": \"Ticket to festival\",\n  \"metadata\": [\n    {\n      \"orderId\": \"ORD-123456789\"\n    },\n    {\n      \"customerId\": \"customer@email.com\",\n      \"isPII\": true\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "status": "REJECTED",
  "failureReason": {
    "failureCode": "PROVIDER_TEMPORARILY_UNAVAILABLE",
    "failureMessage": "The provider 'MTN_MOMO_ZMB' is currently not able to process payments. Please consult our status page for downtime information on all providers. Programmatic access is also available, please consult our API docs."
  }
}

Initiates a deposit using the PawaPay Payment Page.

Check the guide!

Follow the step-by-step guide on how to build a payment flow using the payment page.

The request will return a redirectURL.
The customer should be forwarded to this URL to start the payment process.
Once the customer completes the payment process on the Payment Page, they will be forwarded to the returnUrl.
The original depositId will be passed as a query parameter.

Your page on the returnUrl has two options to determine the status of the payment. You can do that by either:

Waiting for a callback

If you have configured callbacks, just wait for it.

Checking the status

Or poll the Check Deposit Status endpoint.

The customer experience of the Payment Page can be changed through the following parameters during initiation.

Parameter	Behaviour if specified	Behaviour if not specified
`amountDetails`	The specified amount will be used for the payment. Customer is not able to change it.	The customer is able to enter the amount they wish to pay. For example, when depositing into their eWallet.
`phoneNumber`	The payment will be initiated from the specified mobile money wallet. Customer is not able to change it.	The customer can specify the phone number of the mobile money wallet they wish to pay from.
`country`	The customer can pay only using a mobile money wallet from the specified country.	The customer can pay with a mobile money wallet from any country that is configured on your PawaPay account.
`reason`	The reason will be shown to the customer on the Payment Page	The customer will not be shown what they are paying for.

Authorizations

Authorization

string

header

required

See Authentication.

Body

application/json

depositId

string<uuid>

required

A UUIDv4 based unique ID for this payment. We require you to provide the unique ID for all initiated payments to ensure you can always reconcile all payments. Please store this ID in your system before initiating the payment with PawaPay.

Required string length: 36

Example:

"f4401bd2-1568-4140-bf2d-eb77d2b2b639"

returnUrl

string<uri>

required

The URL the customer should be redirected to after the payment is processed.

Example:

"https://merchant.example.com/checkout-result"

customerMessage

string

A short narration for the transaction. Depending on the 'provider', this message may be visible to the customer in the SMS receipt or within their transaction history.

Defaults to your company name as registered on your PawaPay account trimmed to fit the length limitations.

Required string length: 4 - 22

Pattern: ^[a-zA-Z0-9 ]+$

Example:

"Note of 4 to 22 chars"

amountDetails

object

Show child attributes

phoneNumber

string

The phone number (MSISDN) of the customer paying or receiving payment. The format is described in Wikipedia.

Use predict provider to validate and sanitise the phone number.

Phone number validation has following rules:

Only digits without whitespaces or any other separators or prefixes like '+'.
Should not start with zero.
Country code is mandatory.
Should not exceed or be less than the valid length of specified country.

Example:

"260763456789"

language

enum<string>

The language in which the Payment Page will be presented to the customer. If the user has explicitly changed their languages preferences, their selection will override this parameter.

Available options:

EN,

FR

Example:

"EN"

country

string

If specifified, allows payment from phone numbers only from a specific country. If not specified, the customer can select any country that is configured for your account in PawaPay.

You can use the active configuration endpoint to verify which countries and providers have been configured for your account.

Format must be the ISO 3166-1 alpha-3, three character country code in upper case. Read more from Wikipedia.

Example:

"ZMB"

reason

string

An optional text which will be displayed to the customer on the payment page to specify what they are paying for.

Required string length: 1 - 50

Example:

"Ticket to festival"

metadata

object[]

A list of metadata that you can attach to the payment for providing additional context about the payment. For example, adding the channel from which the payment was initated, product ID or anything else that might help your operations team.

Metadata will be included in:

In the dashboard on payment details pages
Financial statements as JSON object
Callbacks

Metadata can be used when searching in the PawaPay Dashboard. Full value of the metadata field must be used for searches.

Metadata will not be visible to the customer that is involved in this payment.

Up to 10 metadata fields can be attached to a payment.

Show child attributes

Example:

[
  { "orderId": "ORD-123456789" },
  {
    "customerId": "customer@email.com",
    "isPII": true
  }
]

Response

Payment Page session is created successfully

redirectUrl

string<uri>

The unique URL for this Payment Page. Customer has to be forwarded to this URL where they can complete the payment.

Please note! The URL is valid for 15 minutes.

Example:

"https://paywith.pawapay.io/?token=AgV4aA3ZxKfGcdMIo6a6Upf7X2MRptdFUrc6Oi3U53CxC0YAkAADABVhd3MtY3J5cHRvLXB1YmxpYy1rZXkAREFzdDR5WktOeWVTRTZ5bTdhVTJJeno3bG1ydkFYenFpUWZqNVQxbGQ2RUgweEpkZVZ0cWJGM3hwMzI1VWN6VGxEdz09AAdwdXJwb3NlAA5jcmVhdGUtc2Vzc2lvbgAFc3RhZ2UAD3NpZ24tY2xvdWRmcm9udAACAAdhd3Mta21zAE5hcm46YXdzOmttczpldS1jZW50cmFsLTE6MTAxOTQ0Mzc3ODY2OmtleS82ZTgzZmVjMS00MWRhLTQxMWQt"

Checkout callback Wallet balances

⌘I

Deposits

Payouts

Refunds

Remittances

Checkouts

Payment page

Finances

Toolkit

Deposit via Payment Page

Check the guide!

Waiting for a callback

Checking the status

Authorizations

Body

Response