Overview

The Collections API allows you to initiate push requests (STK Push) to a customer's mobile money account and track the status of these transactions.

Create Mobile Money Collection

[POST] Create Collection

Endpoint: /v1/collections/mobile-money

Description: Initiates a push request (STK Push) to a customer's mobile money account.

Request Body:

• productId (uuid, required): The ID of the product receiving the funds.
• referenceId (uuid, required): An external unique reference for this transaction.
• phoneNumber (string, required): Customer's phone number (Zambian format).
• currency (string, required): ZMW.
• amount (number, required): Minimum 0.5.
• narration (string, optional): Max 100 characters.

Request Example:

curl -X POST https://api.justtap.io/v1/collections/mobile-money \
  -H "Authorization: Bearer jtpgw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "7486f059-e935-43a5-9c8e-a9d0f4d38c64",
    "referenceId": "550e8400-e29b-41d4-a716-446655440000",
    "phoneNumber": "0971234567",
    "currency": "ZMW",
    "amount": 10.50,
    "narration": "Payment for Order #12345"
  }'

Response (201 Created):

{
  "referenceId": "uuid",
  "status": "pending"
}

Check Collection Status

[GET] Check Status

Endpoint: /v1/collections/check/:referenceId

Description: Polls the status of a specific collection request.

Response (200 OK):

{
  "referenceId": "uuid",
  "externalId": "string",
  "statusText": "completed|pending|failed",
  "reason": "string (nullable)"
}

Collection Statuses