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

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 (enum, 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 \
  -H "x-api-key: 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/status/: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

List Collections

You can retrieve collections by product or specific internal ID.

• By Product: GET /v1/products/:productId/collections

• By ID: GET /v1/collections/:id

Testing Collections

Sandbox Environment

Test Phone Numbers:

• Success: +260971111111
• Failure: +260972222222
• Timeout: +260973333333

Test Amounts:

• Any amount ending in 00 → Success
• Any amount ending in 99 → Failure