Payment Request

Request a payment to a PEEX user by sending their mobile phone number. This endpoint handles mobile money transactions through various network operators.

Overview

The payment request endpoint allows you to initiate mobile money payments to Peex users.

Key Features:

Mobile money payments via phone number
Real-time transaction tracking
Comprehensive sender and recipient information

Request

Method: POST

URL: {{base_url}}disbursement/request_payment

Headers:

SECRETKEY: Your API secret key
Content-Type: application/json

Required Parameters:

amount: The amount to be sent
track_id: The transaction reference
mobile_phone: Beneficiary's mobile phone
currency: The origin currency
sender_first_name: Sender's first name
sender_last_name: Sender's last name
sender_mobile_phone: Sender's mobile phone
first_name: Beneficiary's first name
last_name: Beneficiary's last name
country: Sender's and Beneficiary's country (ISO Alpha 2)
purpose: Transaction purpose
fund_origin: Fund origin

cURL Request

curl -X POST \
  https://sandbox.peexit.com/api/v1/disbursement/request_payment \
  -H 'SECRETKEY: ########-####-####-####-############' \
  -H 'Content-Type: application/json' \
  -d '{
    "track_id": "TEST-PEEX-001",
    "mobile_phone": "+237677777777",
    "amount": 656,
    "currency": "XAF",
    "sender_first_name": "TEST",
    "sender_last_name": "PEEX",
    "sender_mobile_phone": "+237699999999",
    "first_name": "toto",
    "last_name": "junior",
    "country": "CM",
    "purpose": "FAMILY",
    "fund_origin": "SALARY"
  }'

Response

Status 200 - Success

The transaction object with status information:

request.id: Transaction ID
request.amount: Transaction amount
request.status: Transaction status (new, pending, paid, failed)
request.currency: Source currency
request.payment_proof: Payment proof (if available)
request.identifier_by: Recipient identifier
request.track_id: Your tracking reference
request.type: Transaction type ("mobile")

Success Response

{
  "request": {
    "id": 12,
    "amount": 656,
    "status": "new",
    "currency": "XAF",
    "payment_proof": null,
    "identifier_by": "+237677777777",
    "track_id": "TEST-PEEX-001",
    "type": "mobile",
    "payment_proof_image": "/images/missing.png"
  }
}

To simulate each transaction status in the sandbox environment, use the dedicated test mobile numbers below as the beneficiary mobile_phone. Each number is uniquely mapped to a single final status — using a number from one list will always drive the transaction to that exact status.

These test numbers are only valid in sandbox.

Each number is accepted with or without the Cameroon country code (237). For example, 677100001, 237677100001, and +237677100001 are all recognized as the same test number.

Failed (`status: "failed"`)

Transactions sent to one of these numbers will be marked as failed.

677100001 | 677100002 | 677100003 | 677100004 | 677100005

Pending (`status: "pending"`)

Transactions sent to one of these numbers will remain pending.

699000001 | 699000002 | 699000003 | 699000004 | 699000005

Rejected (`status: "rejected"`)

Transactions sent to one of these numbers will be marked as rejected.

699100001 | 699100002 | 699100003 | 699100004 | 699100005

Paid (`status: "paid"`)

Transactions sent to one of these numbers will be marked as paid (successful).

677000001 | 677000002 | 677000003 | 677000004 | 677000005

Error Handling

Status 422 - Unprocessable Entity

This track_id already exists in our system.

Status 401 - Unauthorized

Invalid or missing secret key.

Status 400 - Bad Request

You are not using the correct number for the test.

existing track_id

{
  "error": {
    "statusCode": 422,
    "name": "UnprocessableEntityError",
    "message": "This transaction reference has already been used!"
  }
}

Authentication error response

{
  "error": {
    "statusCode": 401,
    "name": "UnauthorizedError",
    "message": "The key provided doest not exists in our system"
  }
}

Bad request error

{
  "error": {
    "statusCode": 400,
    "name": "BadRequestError",
    "message": "Disbursement initiation refused: phone \"677104401\" not in allowed tests wallets. Use a number found in the documentation."
  }
}

Parameter Details

Currency Codes

XAF: Central African CFA Franc

Purpose Values

FAMILY: Family support
BUSINESS: Business transactions
EDUCATION: Educational expenses
MEDICAL: Medical expenses
Other predefined purposes

Fund Origin Values

SALARY: Employment salary
SALES_AND_BUSINESS_DEVELOPMENT: Business income
INVESTMENT: Investment returns
Other compliance-approved origins

Transaction Lifecycle

New - Transaction created successfully
Pending - Payment initiated, awaiting confirmation
Paid - Transaction completed successfully
Failed - Transaction failed (reason in payment_proof)
Canceled - Transaction canceled manually
Rejected - Transaction rejected (reason provided)

Next Steps

After creating a payment request:

Track Transactions Setup Webhooks