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 SuperAdmin in the backoffice — you do not create them 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 and credential your token maps to — and nothing sensitive.

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

{
  "masterid": 42,
  "tokenid": 7
}

• masterid is your tenant. Every merchant-scoped call is constrained to it.
• tokenid identifies which of your credentials this is — useful when you rotate tokens or need to quote one to support. It is never the token value.

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",
      "services": { "eft": true, "card": false, "tally": false }
    }
  ],
  "total": 1,
  "page": 1,
  "pagesize": 25
}

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.