Bank Payment Request

Request a bank payment to a PEEX user by sending their IBAN account number. This endpoint handles bank money transactions through various banking operators.

Overview

The bank payment request endpoint enables the initiation of bank payments to Peex users.

Key Features:

Bank payments via an IBAN account
Real-time transaction tracking
AML/CFT compliance verification
Comprehensive sender and recipient information

Request

Method: POST

URL: {{base_url}}clients/request_bank_payment

Headers:

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

Required Parameters:

bank_address: Bank full address of the beneficiary
bank_swift: Bank swift code of the beneficiary
bank_iban: Bank IBAN of the beneficiary
amount: The amount to be sent
aml_cft: Compliance confirmation (must be 1)
fxrate: the rate will be used to convert from_currency to_currency
sender_first_name: Sender's first name
sender_last_name: Sender's last name
sender_mobile_phone: Sender's mobile phone
sender_country: Sender's country
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:

bank_name: Bank name in which the beneficiary will receive the fund
to_currency: Destination currency (default: XAF)
sender_email: Sender's email
sender_city: Sender's sender_city
email: The user email to whom the payment will be done
mobile_phone: The user mobile_phone to whom the payment will be documentation
to_currency: The destination currency (optional default XAF )
first_name: the beneficiary first name
last_name: the beneficiary last name

cURL Request

curl -X POST \
  https://sandbox.peexit.com/api/v1/clients/request_bank_payment \
  -H 'SECRETKEY: ########-####-####-####-############' \
  -H 'Content-Type: application/json' \
  -d '{
    "bank_name": "CCA",
    "bank_address": "Douala Bonamoussadi",
    "bank_iban": "1245451245878754",
    "bank_swift": "CM1245",
    "track_id": "TEST_dev_042",
    "amount": 1,
    "aml_cft": 1,
    "fxrate": 1.0,
    "from_currency": "XAF",
    "to_currency": "XAF",
    "to_country": "CM",
    "transaction_type": "bank",
    "mobile_phone": "+237677777777",
    "sender_first_name": "TEST",
    "sender_last_name": "TEST",
    "sender_email": "peex@peex.com",
    "sender_mobile_phone": "+237666667777",
    "sender_country": "CM",
    "purpose": "Familial Aid",
    "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.from_currency: Source currency
request.to_currency: Destination currency
request.bank_iban: IBAN account
request.bank_swift: bank swift code
request.bank_address: bank address
request.bank_name:bank name
request.payment_proof: Payment proof (if available)
request.identifier_by: Recipient identifier (if available)
request.track_id: Your tracking reference
request.type: Transaction type ("bank")

Success Response

{
  "request": {
    "id": 195416,
    "amount": 1,
    "status": "new",
    "from_currency": "XAF",
    "to_currency": "XAF",
    "payment_proof": null,
    "identifier_by": "690597777",
    "track_id": "fess-TEST0011",
    "bank_name": "CCA BANK",
    "bank_address": "Douala Bonanoussadi",
    "bank_iban": "1245451245878754",
    "bank_swift": "CCAMCMCYXXX",
    "type": "bank",
  }
}

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

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