Submit a customer query

Returns the customer’s name and every mobile-money number on the tag. Your API key identifies your organization.

POST/api/v1/partners/customer-queries

Authorization

x-api-keyAPI key · headerrequired

API key issued by Just-tap. It identifies your organization. Do not send a partner id in the body.

Request body

requiredapplication/json

tagIdstringrequired

The tag the customer tapped.

min length 1

merchantIdstringrequired

Your id for the shop.

min length 1

merchantNamestringrequired

Your name for the shop. The first name we store for this merchant id is the one we keep.

min length 1

terminalIdstringrequired

The terminal that read the tag.

min length 1

referenceIdstringrequired

Your unique id for this query.

min length 1

externalIdstring

The mobile money provider's id, if you already have it. Otherwise send it with the terminal result.

currencystring

Defaults to ZMW.

amountnumberrequired

The transaction amount.

min 0

Responses

201

The customer query was created.

dataCustomerQueryResultrequired

Show properties

idstring<uuid>required

partnerobjectrequired

Show properties

partnerIdstring<uuid>required

partnerNamestringrequired

customerobjectrequired

Show properties

firstNamestringrequired

lastNamestringrequired

tagobjectrequired

Show properties

tagIdstringrequired

tagNumberstringrequired

mobileNumbersobject[]required

Show properties

Array of object

operatorstringrequired

Allowed:airtel_moneymtn_mobile_moneyzamtel_kwacha

mobileNumberstringrequired

statusstringrequired

transactionobjectrequired

Show properties

merchantIdstringrequired

merchantNamestringrequired

terminalIdstringrequired

referenceIdstringrequired

externalIdstring | nullrequired

currencystringrequired

amountnumberrequired

serviceChargenumberrequired

Service charge of 1 kwacha.

totalAmountnumberrequired

Amount plus the service charge.

statusstringrequired

pending until you report the terminal result.

Allowed:pendingsuccessfulfailed

createdAtstring<date-time>required

updatedAtstring<date-time>required

400

The tag exists, but it is not active.

errorstringrequired

messagestringrequired

401

The API key is missing, invalid, revoked, or expired.

errorstringrequired

messagestringrequired

403

This API key cannot run customer queries.

errorstringrequired

messagestringrequired

404

The tag, its customer, or its mobile numbers could not be found.

errorstringrequired

messagestringrequired

409

A customer query with this reference already exists.

errorstringrequired

messagestringrequired

422

The request failed validation.

errorstringrequired

Allowed:VALIDATION_ERROR

messagestringrequired

errorsobject[]required

Show properties

Array of object

fieldstringrequired

rulestringrequired

messagestringrequired

500

Something went wrong on our side.

errorstringrequired

messagestringrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

API keyRemember on this deviceInclude my values in samples

Bodyapplication/json

tagIdstring*The tag the customer tapped.merchantIdstring*Your id for the shop.merchantNamestring*Your name for the shop. The first name we store for this merchant id is the one we keep.terminalIdstring*The terminal that read the tag.referenceIdstring*Your unique id for this query.externalIdstringThe mobile money provider's id, if you already have it. Otherwise send it with the terminal result.currencystringDefaults to ZMW.amountnumber*The transaction amount.

Request

curl -X POST 'https://api-uat.cards.justtap.io/api/v1/partners/customer-queries' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "tagId": "string",
  "merchantId": "string",
  "merchantName": "string",
  "terminalId": "string",
  "referenceId": "string",
  "externalId": "string",
  "currency": "string",
  "amount": 0
}'

const response = await fetch("https://api-uat.cards.justtap.io/api/v1/partners/customer-queries", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"tagId\": \"string\",\n  \"merchantId\": \"string\",\n  \"merchantName\": \"string\",\n  \"terminalId\": \"string\",\n  \"referenceId\": \"string\",\n  \"externalId\": \"string\",\n  \"currency\": \"string\",\n  \"amount\": 0\n}"
});

import requests

response = requests.post(
    "https://api-uat.cards.justtap.io/api/v1/partners/customer-queries",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"tagId\": \"string\",\n  \"merchantId\": \"string\",\n  \"merchantName\": \"string\",\n  \"terminalId\": \"string\",\n  \"referenceId\": \"string\",\n  \"externalId\": \"string\",\n  \"currency\": \"string\",\n  \"amount\": 0\n}",
)

Response

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "partner": {
      "partnerId": "bf408d53-df49-40a6-8455-a34bd4360901",
      "partnerName": "string"
    },
    "customer": {
      "firstName": "string",
      "lastName": "string"
    },
    "tag": {
      "tagId": "string",
      "tagNumber": "string",
      "mobileNumbers": [
        {
          "operator": "airtel_money",
          "mobileNumber": "string",
          "status": "string"
        }
      ],
      "status": "string"
    },
    "transaction": {
      "merchantId": "string",
      "merchantName": "string",
      "terminalId": "string",
      "referenceId": "string",
      "externalId": "string",
      "currency": "string",
      "amount": 0,
      "serviceCharge": 0,
      "totalAmount": 0,
      "status": "pending"
    },
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

{
  "error": "string",
  "message": "string"
}

{
  "error": "string",
  "message": "string"
}

{
  "error": "string",
  "message": "string"
}

{
  "error": "string",
  "message": "string"
}

{
  "error": "string",
  "message": "string"
}

{
  "error": "VALIDATION_ERROR",
  "message": "string",
  "errors": [
    {
      "field": "string",
      "rule": "string",
      "message": "string"
    }
  ]
}

{
  "error": "string",
  "message": "string"
}