For engineers and integrators

TrustPayWay Unified API

A single, secure API to interact with multiple mobile payment networks (Orange, MTN, etc.): generate tokens, initiate payments and track payment statuses in real time.

REST JSON API

OAuth-like Bearer token

PCI-DSS • GIMAC

Quick start

The TrustPayWay API lets you initiate and track mobile money payments through a unified interface. A typical flow is:

Get a TPW token (valid for 2 hours).
Call Process Payment to start the payment.
Use Check Payment Status to track the transaction.

Environment variables

base_url – API base URL
network – Payment network (mtn, orange)
secret_key – Secret key provided on registration
bearer_token – Token returned by /api/login
auth_token – Network-specific token if required

POST /api/login

Get TPW token

This endpoint returns an access_token (Bearer) valid for two hours. Use this token in the Authorization header for all protected calls.

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer {secret_key}"
}

Request body

{
  "applicationId": "38e1a762-cceb-4d71-9340-c76ad040b42a"
}

Success response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Error example

{
  "error": "invalid_credentials",
  "message": "Invalid secret key provided"
}

POST /api/{network}/process-payment

Process payment

This endpoint initiates a mobile money payment on the selected network (for example mtn or orange). Use the bearer_token obtained from /api/login.

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer {bearer_token}"
}

Request body

{
  "amount": "1",                 // Amount to be paid
  "currency": "XAF",             // Currency code
  "subscriberMsisdn": "237600000000", // Payer phone number
  "description": "payment",      // Optional description
  "orderId": "TPW12345",         // Your order ID
  "verificationToken": "unique-token-123", // Optional token to avoid duplicates
  "notifUrl": "https://yourapp.com/tpw/callback" // Webhook for payment notifications
}

Success response

{
  "data": {
    "transaction_id": "74d96622-b36c-4993-964d-345decfcbb8d"
  },
  "message": "Payment request successful",
  "status_code": 202
}

Error example

{
  "error": "invalid_request",
  "message": "Invalid phone number format",
  "status_code": 400
}

Duplicate prevention: when verificationToken is provided, any active transaction with the same merchant ID + orderId + verificationToken will be rejected as a duplicate (FAILED / CANCELED are ignored).

GET /api/{network}/get-status/{transaction_id}

Check payment status

Use this endpoint to track the status of a transaction (typical values: INITIATED, PENDING, FAILED, SUCCESSFUL).

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer {bearer_token}"
}

Success response

{
  "amount": "1",
  "confirmationStatus": "payment started",
  "description": "COULD_NOT_PERFORM_TRANSACTION",
  "orderId": "TPWid017",
  "payerPhone": "237673444815",
  "status": "FAILED",
  "transactionId": "11972264171"
}

Error example

{
  "error": "not_found",
  "message": "Transaction not found",
  "status_code": 404
}