Getting Started

This page takes you from "I have a Master Account" to "I've made my first authenticated call".

Prerequisites

1. A partner Master Account on the platform.
2. A partner API token for that account. Tokens are issued by a platform administrator, not through this API. Ask your platform contact to issue one, and store the value somewhere safe: it is shown once and it is the secret. See Authentication.

Base URLs

Integrate against sandbox first. It runs the same code against a development database, so you can create merchants, set their configuration and read your changes back without touching production data.

Your first call

The quickest way to prove your token works is GET /v1/whoami. It returns the Master Account your token maps to, and nothing sensitive.

curl -s https://dev.boapi.ppgw.net/v1/whoami \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "mastercode": "ACME",
  "mastername": "Acme Payments (Pty) Ltd"
}

• mastercode is your Master Account's code.
• mastername is its business name.

If the token is missing, malformed, disabled, or belongs to a suspended account, you get a 401 with the standard error envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "A valid bearer token is required.",
    "requestid": "8f3c1a9b2d7e4f60"
  }
}

List your merchants

curl -s "https://dev.boapi.ppgw.net/v1/merchants?page=1&pagesize=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "items": [
    {
      "merchantid": 10231,
      "merchantcode": "ME10231",
      "status": 1,
      "statuslabel": "active",
      "businessname": "Acme Online"
    }
  ],
  "total": 1,
  "page": 1,
  "pagesize": 25
}

pagesize defaults to 25. Set pagesize=0 to return every merchant in one call (unpaged).

The request contract, in brief

• Send Content-Type: application/json on any request with a body.
• Field names are all-lowercase. Send numbers as numbers, not strings.
• Set X-Request-Id on a request to correlate it with your own logs. If you don't, the API mints one and echoes it back on the X-Request-Id response header. It also appears in every error body.
• Unknown fields you send are ignored, not rejected.

Next steps

• Authentication: token handling, masking, and what each auth failure means.
• Merchant onboarding: create a merchant and understand the pending-until-activated lifecycle.
• API Reference: every endpoint with a try-it panel.