Introduction

Welcome to the Just-tap Partner API. This API lets integration partners resolve a Just-tap tag tap into the customer's mobile money details for a transaction — everything you need to complete a payment at your own terminal.

What you can do with this API

Customer queries

A Just-tap tag (card or wristband) is tapped at your terminal. You don't know which Just-tap customer that tag belongs to or which mobile money account to charge — a customer query resolves that. Send the tag ID along with your transaction details (merchant, terminal, reference, amount), and the API returns the matched customer's name and their mobile money number for the requested provider.

You can also list the customer queries you've previously submitted.

Authentication

Every request must include your API key in the x-api-key header:

POST /v1/jt/partners/customer-queries
x-api-key: <your-api-key>
Content-Type: application/json

API keys are issued directly by Just-tap and are scoped to your organization — contact Just-tap to request one. Your identity is derived entirely from the key, so you never need to (and can't) pass a partner identifier in a request body.

A missing, invalid, revoked, or expired key returns 401. A key that isn't authorized for customer queries returns 403.

Endpoints

Submit a customer query

POST /v1/jt/partners/customer-queries

Example request:

{
  "merchantId": "YKrpx3FrpVHWjmIwpqMt",
  "merchantName": "Young Phiroz",
  "terminalId": "D1K0600000849",
  "referenceId": "8244c279-d76c-4e30-ad3b-9efdb12ca692",
  "amount": 100,
  "tagId": "VZ9T7GM1EYV5MZ",
  "provider": "airtel_money"
}

Example response (201):

{
  "success": true,
  "data": {
    "id": "b5d746b3-d379-4900-b392-d5045abfb22c",
    "partner": {
      "partnerId": "edfa86b6-411e-4e66-a681-0cc61abba40e",
      "partnerName": "Your Organization"
    },
    "customer": {
      "firstName": "Jane",
      "lastName": "Mwansa"
    },
    "tag": {
      "tagId": "VZ9T7GM1EYV5MZ",
      "tagNumber": "TAG-000123",
      "operator": "airtel_money",
      "mobileNumber": "260970371467",
      "status": "active"
    },
    "transaction": {
      "merchantId": "YKrpx3FrpVHWjmIwpqMt",
      "merchantName": "Young Phiroz",
      "terminalId": "D1K0600000849",
      "referenceId": "8244c279-d76c-4e30-ad3b-9efdb12ca692",
      "currency": "ZMW",
      "amount": 100,
      "serviceCharge": 1,
      "status": "pending"
    },
    "createdAt": "2025-04-29T10:00:00.000Z",
    "updatedAt": "2025-04-29T10:00:00.000Z"
  }
}

Common failure cases: the tag doesn't exist or isn't active (404 / 400), no mobile money number is registered for the requested provider (404), or merchantId, terminalId, or referenceId isn't unique — each must be unique across all your queries (409).

List customer queries

GET /v1/jt/partners/customer-queries

Returns every customer query you've previously submitted. Results are automatically scoped to your API key — you'll never see another partner's queries.

Request & response conventions

• All request and response bodies are JSON (Content-Type: application/json)
• Timestamps are ISO 8601 strings (2025-04-29T10:00:00.000Z)
• Monetary amounts (amount, serviceCharge)
• Currency is always ZMW

Error envelope:

{
  "success": false,
  "message": "A record with reference ID 'b5d746b3-d379-4900-b392-d5045abfb22c' already exists",
  "code": 409,
  "error": "resource/already-exists-error"
}

Environments

Use the sandbox for integration testing. It runs against an isolated database — no real money moves.