Payment Request

Request a payment to a PEEX user by sending their email or 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. The system supports multiple currencies and automatic currency conversion based on specified exchange rates.

Key Features:

Mobile money payments via phone number
Multi-currency support with automatic conversion
Real-time transaction tracking
AML/CFT compliance verification
Comprehensive sender and recipient information

Request

Method: POST

URL: {{base_url}}clients/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
from_currency: The origin currency
aml_cft: Compliance confirmation (must be 1)
fxrate: Compliance confirmation (must be 1)
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
to_country: Beneficiary's country (ISO Alpha 2)
purpose: Transaction purpose
fund_origin: Fund origin

Optional Parameters:

email: Beneficiary's email
to_currency: Destination currency (default: XAF)
sender_email: Sender's email
sender_city: Sender's sender_city

cURL Request

curl -X POST \
  https://sandbox.peexit.com/api/v1/clients/request_payment \
  -H 'SECRETKEY: ########-####-####-####-############' \
  -H 'Content-Type: application/json' \
  -d '{
    "track_id": "TEST-PEEX-001",
    "mobile_phone": "+241076566326",
    "amount": 656,
    "from_currency": "XAF",
    "to_currency": "XAF",
    "fxrate": 1,
    "aml_cft": 1,
    "sender_first_name": "TEST",
    "sender_last_name": "PEEX",
    "sender_mobile_phone": "+33603134666",
    "sender_country": "FR",
    "first_name": "toto",
    "last_name": "junior",
    "to_country": "GA",
    "purpose": "FAMILY",
    "fund_origin": "SALES_AND_BUSINESS_DEVELOPMENT"
  }'

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.from_currency: Source currency
request.to_currency: Destination 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": 177610,
    "amount": 656,
    "status": "new",
    "from_currency": "XAF",
    "to_currency": "XAF",
    "payment_proof": null,
    "identifier_by": "+241076566326",
    "track_id": "TEST-PEEX-001",
    "type": "mobile",
    "payment_proof_image": "/images/missing.png"
  }
}

Error Handling

Status 422 - Unprocessable Entity

This track_id already exists in our system.

Status 401 - Unauthorized

Invalid or missing secret key.

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"
  }
}

Parameter Details

Currency Codes

USD: US Dollar
EUR: Euro
XAF: Central African CFA Franc
XOF: West African
Other supported currencies

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