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.

Method	Endpoint	Description
`POST`	`/v1/collections/mobile-money`	Initiate STK Push payment
`GET`	`/v1/collections/check/:referenceId`	Check payment status
`GET`	`/v1/collections/:id`	Get collection details

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 1, Maximum 10,000.
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 (202 Accepted):

{
  "success": true,
  "data": {
    "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):

{
  "success": true,
  "data": {
    "referenceId": "fcb818fb-110e-4dad-b00f-41d1f789ff41",
    "statusText": "failed",
    "transactionCode": "INTERNAL_SYSTEM_ERROR",
    "reason": "An unexpected error occurred."
  }
}

Error Response (422 Unprocessable Entity):

{
  "success": false,
  "data": null,
  "code": "E_VALIDATION_ERROR",
  "type": "https://httpstatuses.com/422",
  "title": "Validation Error",
  "status": 422,
  "detail": "Validation failure",
  "instance": "/v1/collections/check/c156a0b5-d6fc-4e1e-b6f6-98ea03bedc4999",
  "errors": [
    {
      "message": "The referenceId field must be a valid UUID",
      "rule": "uuid",
      "field": "params.referenceId"
    }
  ],
  "requestId": "ta0hnxdxs3sip8vruzqxe83g"
}

Collection Statuses

Status	Description
`pending`	Collection created, awaiting payment
`successful`	Payment successful
`failed`	Payment failed