PeeX Peers Exchange

Collection Requests

The collection endpoints enable you to request fund collections from mobile money wallets, track transaction statuses, and retrieve transaction history.

POST/collection/request_payment

Request payment collection

Request a collection of funds from a user's mobile money wallet account. This initiates a payment request that will be sent to the user's phone for approval.

Request body

  • Name
    track_id
    Type
    string
    Description

    Unique reference for the transaction provided by the partner. This ID must be unique across all your transactions.

  • Name
    phone
    Type
    string
    Description

    The user's mobile phone number in international format (e.g., +237678923563). No spaces or hyphens.

  • Name
    amount
    Type
    number
    Description

    The amount to be collected from the user's wallet.

  • Name
    currency
    Type
    string
    Description

    The currency code for the transaction (e.g., "XAF" for Central African CFA franc).

  • Name
    customer_name
    Type
    string
    Description

    The customer's full name for identification purposes.

  • Name
    country
    Type
    string
    Description

    The customer's country in ISO Alpha-2 format (e.g., "CM" for Cameroon).

  • Name
    description
    Type
    string
    Description

    Description of the transaction reason. Required for compliance and audit purposes.

Response codes

  • Name
    200
    Description

    Transaction successfully initiated. Returns transaction object with status.

  • Name
    422
    Description

    Invalid parameters provided. Check the error message for details.

  • Name
    401
    Description

    Unauthorized - invalid or missing secret key.

Request

POST
/collection/request_payment
curl -X POST \
  https://sandbox.peexit.com/api/v1/collection/request_payment \
  -H "SECRETKEY: 37528871-1f6c-43e9-a74a-0ad1f4baba76" \
  -H "Content-Type: application/json" \
  -d '{
    "track_id": "TEST_COLLECT_005",
    "amount": 5,
    "customer_name": "Paul Doe",
    "country": "CM",
    "currency": "XAF",
    "phone": "+237675287689",
    "description": "Salary"
  }'

Response

{
  "id": 5,
  "amount": 5,
  "country": "CM",
  "currency": "XAF",
  "phone": "+237675287689",
  "description": "Salary",
  "customer_name": "Paul Doe",
  "track_id": "TEST_COLLECT_005",
  "method": "mtn-api",
  "payment_proof": "11458739150",
  "message": "{\"financialTransactionId\":\"11458739150\",
              \"externalId\":\"049e6de4-2be7-4c46-ba8c-ccda82d9cbeb\",
              \"amount\":\"5\",\"currency\":\"XAF\",
              \"payer\":{\"partyIdType\":\"MSISDN\",
              \"partyId\":\"237675287689\"},
              \"payerMessage\":\"PX-5\",
              \"payeeNote\":\"CM\",\"status\":\"PENDING\"}",
  "status": "pending"
}

Collection Requests

Retrieve details of a specific transaction using your reference ID (track_id). This endpoint returns the complete transaction object with current status.

Query parameters

  • Name
    track_id
    Type
    string
    Description

    Your unique transaction reference that was provided when creating the collection request.

Transaction statuses

  • Name
    new
    Description

    Transaction has reached the PEEX server and is being processed.

  • Name
    pending
    Description

    Transaction has been initiated and is awaiting user confirmation.

  • Name
    paid
    Description

    Transaction has been successfully paid and confirmed.

  • Name
    failed
    Description

    Automatic payment failed. Check the payment_proof field for the reason.

  • Name
    canceled
    Description

    Transaction was manually canceled. Reason is in the payment_proof field.

  • Name
    rejected
    Description

    Transaction was rejected. The reason is included in the response.

Request

GET
/collection/all_requests
curl -X GET \
  "https://sandbox.peexit.com/api/v1/collection/all_requests?track_id=TEST_COLLECT_005" \
  -H "SECRETKEY: ########-####-####-####-############"

Response

{
  "id": 5,
  "amount": 5,
  "country": "CM",
  "currency": "XAF",
  "phone": "+237675287689",
  "description": "Salary",
  "customer_name": "Paul Doe",
  "track_id": "TEST_COLLECT_005",
  "method": "mtn-api",
  "payment_proof": "11458739150",
  "message": "{\"financialTransactionId\":\"11458739150\",
              \"externalId\":\"049e6de4-2be7-4c46-ba8c-ccda82d9cbeb\",
              \"amount\":\"5\",
              \"currency\":\"XAF\",
              \"payer\":{\"partyIdType\":\"MSISDN\",
                \"partyId\":\"237675287689\"},
              \"payerMessage\":\"PX-5\",
              \"payeeNote\":\"CM\",
              \"status\":\"SUCCESSFUL\"}",
  "status": "paid"
}

Provider unavailable

If the provider is unavailable, you will receive this response after initiating the transaction.

Response

{
  success: false,
  message: 'Service Unavailable',
  details: "Collect service Provider for this transaction is unavailble for the moment, please contact Peex support"  
}

Best practices

Transaction tracking - Always use unique track_id values for each

transaction - Store the track_id in your database for reconciliation - Implement webhook handlers for real-time status updates

Phone number format Phone numbers must be in international format with

country code and no special characters: - ✅ Correct: +237675287689 - ❌ Wrong: 237-675-287-689 - ❌ Wrong: 675287689

Handling responses

When a collection request is initiated, the transaction goes through several states:

  1. New - Transaction received by PEEX
  2. Pending - Awaiting user confirmation on their phone
  3. Paid - Successfully completed
  4. Failed/Canceled/Rejected - Transaction unsuccessful

Monitor the status by either:

  • Polling the transaction details endpoint
  • Setting up webhooks to receive real-time updates

Was this page helpful?