Create Bulk Payment Request

POST /secure/bulkpaymentrequests/create

Try it

Bodyapplication/json

jobReference*notifyUrl*compressedData*

Request sampleLanguage

curl -X POST 'https://api.ozow.com/secure/bulkpaymentrequests/create' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "jobReference": "string",
  "notifyUrl": "https://example.com/",
  "compressedData": "string"
}'

Response exampleStatus

{
  "jobId": "00000000-0000-0000-0000-000000000000",
  "jobReference": "<jobReference>",
  "errors": [
    "<errors>"
  ]
}

Built from the response schema. Values are placeholders, not real data.

POSThttps://api.ozow.com/secure/bulkpaymentrequests/createProduction

Submit up to 5000 payment requests as one job. The response says only whether the job was accepted. The payment links and the per-request results are sent to the notification URL in the request once the job finishes.

Authentication

Bearer token
The token generated by the Get API token operation. The same token is used for every request until it expires.

Request body

application/json

jobReference string required
The merchant reference for the job/batch of payment requests to be created.
max length100
notifyUrl string uri required
The URL where the results for the job will be posted to after the job has been processed.
max length150
compressedData string required
A GZIP compressed JSON string of the array of payment request records. Each element carries the fields of a payment request link; the result notification adds the outcome fields to each record it sends back.

To compress: build the JSON array, encode it as UTF-8 bytes, GZIP those bytes, then base64 the compressed bytes.

To decompress what you receive: base64 decode to bytes, GZIP decompress, then read the bytes as UTF-8.

application/xml

jobReference string required
The merchant reference for the job/batch of payment requests to be created.
max length100
notifyUrl string uri required
The URL where the results for the job will be posted to after the job has been processed.
max length150
compressedData string required
A GZIP compressed JSON string of the array of payment request records. Each element carries the fields of a payment request link; the result notification adds the outcome fields to each record it sends back.

To compress: build the JSON array, encode it as UTF-8 bytes, GZIP those bytes, then base64 the compressed bytes.

To decompress what you receive: base64 decode to bytes, GZIP decompress, then read the bytes as UTF-8.

Responses

200 OK

application/json

jobId string uuid required
The identifier for the job created to process the bulk payment requests. No identifier is returned if there was an error creating the job or if the request submitted failed the initial validation.
jobReference string required
The merchant reference for the job/batch that was passed in the create request.
max length100
errors array of string
Validation errors for the request.

application/xml

jobId string uuid required
The identifier for the job created to process the bulk payment requests. No identifier is returned if there was an error creating the job or if the request submitted failed the initial validation.
jobReference string required
The merchant reference for the job/batch that was passed in the create request.
max length100
errors array of string
Validation errors for the request.

Request

curl -X POST 'https://api.ozow.com/secure/bulkpaymentrequests/create' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "jobReference": "<jobReference>",
  "notifyUrl": "https://example.com/notifyurl",
  "compressedData": "<compressedData>"
}'

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.ozow.com/secure/bulkpaymentrequests/create");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");

request.Content = new StringContent(@"{
  ""jobReference"": ""<jobReference>"",
  ""notifyUrl"": ""https://example.com/notifyurl"",
  ""compressedData"": ""<compressedData>""
}", Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ozow.com/secure/bulkpaymentrequests/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_ACCESS_TOKEN',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "jobReference": "<jobReference>",
  "notifyUrl": "https://example.com/notifyurl",
  "compressedData": "<compressedData>"
}
JSON,
]);

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

const response = await fetch("https://api.ozow.com/secure/bulkpaymentrequests/create", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jobReference": "<jobReference>",
    "notifyUrl": "https://example.com/notifyurl",
    "compressedData": "<compressedData>"
  }),
});

const data = await response.json();

import requests

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
}

payload = {
    "jobReference": "<jobReference>",
    "notifyUrl": "https://example.com/notifyurl",
    "compressedData": "<compressedData>",
}

response = requests.post(
    "https://api.ozow.com/secure/bulkpaymentrequests/create",
    headers=headers,
    json=payload,
)

Response

{
  "jobId": "00000000-0000-0000-0000-000000000000",
  "jobReference": "<jobReference>",
  "errors": [
    "<errors>"
  ]
}

Built from the response schema. Values are placeholders, not real data.

Bad Request. The operation could not be carried out. The body is a message rather than a structured error.

There was an error processing your request

Unauthorized. The `ApiKey` header is missing or does not match the site, or for a `Secure` operation the bearer token is missing, expired or invalid.

API key is missing or invalid.