API reference

People

Add and read the people you pay.

List people

GET/api/v1/beneficiariesscope beneficiaries.read

The people you pay, newest first, with their payout accounts.

Query

`search`string	Matches name, phone number or your own reference.
`page`integer	Page number, starting at 1. Default 1.
`pageSize`integer	Items per page, 1 to 100. Default 20.

GET /api/v1/beneficiaries · test

curl -X GET "https://api.tranzaq.com/api/v1/beneficiaries" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch("https://api.tranzaq.com/api/v1/beneficiaries", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
console.log(await response.json());

var request = new HttpRequestMessage(HttpMethod.Get, "/api/v1/beneficiaries");
request.Headers.Authorization = new("Bearer", token);

var response = await http.SendAsync(request);   // http.BaseAddress = "https://api.tranzaq.com"
Console.WriteLine(await response.Content.ReadAsStringAsync());

import uuid, requests

response = requests.get(
    "https://api.tranzaq.com/api/v1/beneficiaries",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json())

Answer · 200

Response · test

{
  "success": true,
  "message": "Operation completed",
  "code": 200,
  "result": { "items": [ … ], "total": 46, "page": 1, "pageSize": 20 }
}

Errors

401Missing, invalid or expired token.
403The token does not have the beneficiaries.read scope.

Get a person

GET/api/v1/beneficiaries/{id}scope beneficiaries.read

One person and their accounts.

Path

iduuidrequired The person's id.

GET /api/v1/beneficiaries/{id} · test

curl -X GET "https://api.tranzaq.com/api/v1/beneficiaries/PASTE_ID" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch("https://api.tranzaq.com/api/v1/beneficiaries/PASTE_ID", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
console.log(await response.json());

var request = new HttpRequestMessage(HttpMethod.Get, "/api/v1/beneficiaries/PASTE_ID");
request.Headers.Authorization = new("Bearer", token);

var response = await http.SendAsync(request);   // http.BaseAddress = "https://api.tranzaq.com"
Console.WriteLine(await response.Content.ReadAsStringAsync());

import uuid, requests

response = requests.get(
    "https://api.tranzaq.com/api/v1/beneficiaries/PASTE_ID",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json())

Answer · 200

Response · test

{
  "success": true,
  "message": "Beneficiary created",
  "code": 201,
  "result": {
    "id": "8d2f6f40-5e7a-4b0e-b1a1-2f4c9d7e1a33",
    "name": "Ama Owusu",
    "email": null,
    "phoneNumber": "0241234567",
    "externalReference": "EMP-0042",
    "status": "Active",
    "createdAt": "2026-10-18T10:10:00+00:00",
    "destinations": [
      { "id": "e0a1b2c3-d4e5-4f60-8a7b-9c8d7e6f5a4b", "type": "MobileMoney", "maskedAccountNumber": "024****567", "accountName": "Ama Owusu", "network": "MTN", "isDefault": true, "verificationStatus": "Verified" }
    ]
  }
}

Errors

404No such person in your business.

Add a person

POST/api/v1/beneficiariesscope beneficiaries.writeneeds Idempotency-Key

Add someone you pay, with a mobile money or bank account. We look up the name on the account and mark it Verified or not.

Body (JSON)

`name`stringrequired	Up to 200 characters.
`email`string	Optional.
`phoneNumber`string	Optional.
`externalReference`string	Your own id for this person, such as an employee number. Up to 100 characters.
`destination.type`string	MobileMoney or Bank.
`destination.accountNumber`string	The phone number or bank account number.
`destination.accountName`string	The name on the account, as you know it.
`destination.network`string	Mobile money only: MTN, TELECEL or AIRTELTIGO.
`destination.bankCode`string	Bank only: the bank's code.

POST /api/v1/beneficiaries · test

curl -X POST "https://api.tranzaq.com/api/v1/beneficiaries" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: a-new-guid-for-each-request" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ama Owusu", "phoneNumber": "0241234567", "externalReference": "EMP-0042", "destination": { "type": "MobileMoney", "accountNumber": "0241234567", "accountName": "Ama Owusu", "network": "MTN" } }'

const response = await fetch("https://api.tranzaq.com/api/v1/beneficiaries", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Ama Owusu",
    "phoneNumber": "0241234567",
    "externalReference": "EMP-0042",
    "destination": {
      "type": "MobileMoney",
      "accountNumber": "0241234567",
      "accountName": "Ama Owusu",
      "network": "MTN"
    }
  }),
});
console.log(await response.json());

var request = new HttpRequestMessage(HttpMethod.Post, "/api/v1/beneficiaries");
request.Headers.Authorization = new("Bearer", token);
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
request.Content = new StringContent(@"{
  ""name"": ""Ama Owusu"",
  ""phoneNumber"": ""0241234567"",
  ""externalReference"": ""EMP-0042"",
  ""destination"": {
    ""type"": ""MobileMoney"",
    ""accountNumber"": ""0241234567"",
    ""accountName"": ""Ama Owusu"",
    ""network"": ""MTN""
  }
}", Encoding.UTF8, "application/json");

var response = await http.SendAsync(request);   // http.BaseAddress = "https://api.tranzaq.com"
Console.WriteLine(await response.Content.ReadAsStringAsync());

import uuid, requests

response = requests.post(
    "https://api.tranzaq.com/api/v1/beneficiaries",
    headers={"Authorization": f"Bearer {token}", "Idempotency-Key": str(uuid.uuid4())},
    json={
      "name": "Ama Owusu",
      "phoneNumber": "0241234567",
      "externalReference": "EMP-0042",
      "destination": {
        "type": "MobileMoney",
        "accountNumber": "0241234567",
        "accountName": "Ama Owusu",
        "network": "MTN"
      }
    },
)
print(response.json())

Answer · 201

Response · test

{
  "success": true,
  "message": "Beneficiary created",
  "code": 201,
  "result": {
    "id": "8d2f6f40-5e7a-4b0e-b1a1-2f4c9d7e1a33",
    "name": "Ama Owusu",
    "email": null,
    "phoneNumber": "0241234567",
    "externalReference": "EMP-0042",
    "status": "Active",
    "createdAt": "2026-10-18T10:10:00+00:00",
    "destinations": [
      { "id": "e0a1b2c3-d4e5-4f60-8a7b-9c8d7e6f5a4b", "type": "MobileMoney", "maskedAccountNumber": "024****567", "accountName": "Ama Owusu", "network": "MTN", "isDefault": true, "verificationStatus": "Verified" }
    ]
  }
}

Errors

400A field is missing or not valid, or the Idempotency-Key header is missing.
409The same Idempotency-Key was used for a different request that is still running.