API V1 (legacy)

Callbacks (V1)

The result of a V1 collection or withdrawal, sent to the request's callback URL.

You are reading the legacy V1, maintained for existing integrations. For a new integration, use V2; to migrate, see Versions and migration.

When the callback is sent#

When a payment changes status (pending, completed or failed), LabPay sends a JSON POST to the request's callback URL, with the V1 envelope:

Callback of a completed payment (example)

{
  "status_code": 200,
  "success": true,
  "orderNumber": "6f1d2c3b-8a7e-4f10-9b2c-3d4e5f607182",
  "reference": "6f1d2c3b-8a7e-4f10-9b2c-3d4e5f607182",
  "message": "La transaction a été effectuée avec succès",
  "results": {
    "status": {
      "code": "2",
      "name": "done",
      "description": "La transaction a été effectuée avec succès"
    },
    "details": {
      "amount": 100,
      "currency": "USD",
      "payment_method": "Mobile Money",
      "destinataire": "Ma Boutique",
      "amountCustomer": 107,
      "provider": {
        "id": 1,
        "name": "mpesa",
        "description": "Vodacom RDC",
        "enabled": 1
      },
      "callback": "https://boutique.example/callback"
    }
  },
  "errors": null,
  "time": "2026-11-11T10:00:42.000000Z"
}

`results.status.name`	`status_code`	Meaning
`pending`	`null`	Being processed.
`done`	`200`	Completed: balance credited (collection) or debited (withdrawal).
`failed`	`400`	Failed.

Precautions#

Read the state in results.status.name: success is true in every callback, even for a failure.
The V1 callback is not signed and is sent only once, with no redelivery. Identify the payment by orderNumber and confirm the status with verify or get-transactions before delivering.

V2 sends signed notifications (HMAC-SHA256), redelivered up to six times and available in a history: see V2 notifications.