Pesa Business API Documentation

Welcome to the Pesa Business API documentation. This guide provides everything you need to start interacting with Orion's services programmatically. The API is built using ConnectRPC and accepts and returns JSON.

Base Transport: ConnectRPC (HTTP/2-friendly, works over gRPC-web & JSON). All examples shown below use the JSON mapping.

Authentication#

All requests to the Pesa Business API must be authenticated using a Bearer Token. Include an Authorization header with your API key in every request. 

Authorization: Bearer YOUR_API_KEY

Failure to include a valid token or using an invalid / expired token will result in a 401 Unauthorized response.

Common Workflows#

Making a Payment#

  1. Create a Beneficiary: Save recipient details with CreateBeneficiary.
  2. Create a Quote: Lock in an FX rate (if cross-currency) with CreateQuote. The response returns quote_id that remains valid for a short window.
  3. Create a Payment: Provide the wallet_id to debit, the quote_id (if required), and a beneficiary to transfer funds using CreatePayment.

Error Handling#

The Pesa Business API uses standard HTTP status codes to indicate success or failure. In JSON responses, error details will be included in the body (schema may vary by error type).

Code Meaning Description
400 Bad Request Malformed JSON or invalid field types.
401 Unauthorized Missing / invalid / expired API key.
403 Forbidden Insufficient permission for requested action.
404 Not Found Requested resource does not exist.
422 Unprocessable Entity Request semantically invalid (e.g., insufficient funds).
429 Too Many Requests Rate limit exceeded; back off and retry later.
5xx Server Error Unexpected error on Orion side. Retry with exponential backoff; contact support if persistent.

Endpoints#

The Pesa Business API's JSON endpoints follow the ConnectRPC HTTP mapping. Each RPC method is exposed as an HTTP POST to a fully-qualified service/method path. Example: /orionapi.v1.OrionService/CreateWallet.

Wallets#

POST/orionapi.v1.OrionService/CreateWallet#

Creates a new wallet for a specified currency.

Field Type Description Required
currency string (ISO 4217) Wallet currency code. Ex: "USD", "CAD". Yes
Sample Request 
{
  "currency": "CAD"
}
Sample Response 
{
  "wallet": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "currency": "CAD",
    "available_balance": "0.00",
    "last_transactions": [],
    "funding_accounts": [
      {
        "id": "fa_12345",
        "account_name": "CAD Local Account",
        "local_account": {
          "institution_name": "PesaPeer Bank",
          "institution_number": "001",
          "transit_number": "12345",
          "account_number": "123456789"
        }
      }
    ]
  }
}

POST/orionapi.v1.OrionService/ListWallets#

Retrieve all wallets associated with your account. Optionally filter by currency.

Field Type Description Required
currency string (ISO 4217) Filter list by wallet currency. No
Sample Request 
{
  "currency": "CAD"
}
Sample Response 
{
  "wallets": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "currency": "CAD",
      "available_balance": "5420.50",
      "last_transactions": [],
      "funding_accounts": []
    },
    {
      "id": "b2c3d4e5-f6a7-8901-2345-678901bcdefa",
      "currency": "USD",
      "available_balance": "1230.00",
      "last_transactions": [],
      "funding_accounts": []
    }
  ]
}

Transactions#

POST/orionapi.v1.OrionService/ListWalletTransactions#

Retrieve transactions for a specific wallet. Supports date range, type, category, free-text search, and cursor pagination.

Field Type Description Required
wallet_id string (UUID) Wallet to query. Yes
start_date string (YYYY-MM-DD) Inclusive range start. No
end_date string (YYYY-MM-DD) Inclusive range end. No
currency string Filter by transaction currency. No
network_reference string Filter by network reference. No
payer_instrument string Filter by payer instrument. No
type enum TRANSACTION_TYPE_CREDIT | TRANSACTION_TYPE_DEBIT. No
category enum E.g., TRANSACTION_CATEGORY_PAYMENT, TRANSACTION_CATEGORY_FUNDING. No
pagination PaginationCursor Cursor-based pagination settings. No
name string Search by name. No
search string Free-text search across common fields. No
Sample Request 
{
  "wallet_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "pagination": {
    "page_size": 10
  }
}
Sample Response 
{
  "data": [
    {
      "id": "txn_12345",
      "wallet_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "currency": "CAD",
      "credit_amount": "500.00",
      "balance_amount": "5920.50",
      "narration": "Payment from John Doe",
      "type": "TRANSACTION_TYPE_CREDIT",
      "category": "TRANSACTION_CATEGORY_PAYMENT",
      "created_at": "2023-01-15T14:30:00Z"
    }
  ],
  "pagination": {
    "next_page_cursor": "c3RhcnRfa2V5PXR4bl82Nzg5MA==",
    "page_size": 10
  }
}

Payments#

POST/orionapi.v1.OrionService/CreatePayment#

Initiate a payment from one of your wallets to a beneficiary. Use the quote_id from CreateQuote when sending cross-currency payments.

Field Type Description Required
wallet_id string (UUID) Wallet to debit. Yes
quote_id string (UUID) FX quote to apply (required for FX payments). Yes*
memo string Visible memo for recipient. No
customer_reference string Your unique reference for idempotency / reconciliation. No
beneficiary Beneficiary Recipient details. Yes
otp string (len=6) Six-digit 2FA OTP, if enabled. No
Sample Request 
{
  "wallet_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "quote_id": "e63a049c-233e-4b22-b862-acc43556996c",
  "memo": "Invoice #INV-2023-001",
  "customer_reference": "CUST_PAY_98765",
  "beneficiary": {
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "type": "BENEFICIARY_TYPE_INTERAC",
    "entity_type": "BENEFICIARY_ENTITY_TYPE_INDIVIDUAL",
    "currency": "CAD",
    "country": "CA"
  }
}
Sample Response 
{
  "customer_reference": "CUST_PAY_98765",
  "payment_reference": "pay_123abc456def",
  "network_reference": "CAQDpWCrwq7J",
  "status": "STATE_PENDING"
}

POST/orionapi.v1.OrionService/ListPayments#

Retrieve a list of payments. Supports filtering, simple pagination, and search by multiple identifiers.

Field Type Description Required
destination_currency string Filter by destination currency. No
start_date string (YYYY-MM-DD) Filter by earliest date. No
end_date string (YYYY-MM-DD) Filter by latest date. No
status enum E.g., STATE_COMPLETED, STATE_FAILED. No
customer_reference string Your unique reference. No
payment_reference string System payment reference. No
network_reference string Network reference. No
wallet_id string (UUID) Source wallet. No
page_size number Results per page. No
last_seen_id string (UUID) For simple page iteration. No
beneficiary_id string (UUID) Filter by beneficiary. No
initiator string Payment initiator name/id. No
source_currency string Filter by source currency. No
Sample Request 
{
  "status": "STATE_COMPLETED",
  "start_date": "2023-01-01",
  "page_size": 5
}
Sample Response 
{
  "payments": [
    {
      "reference": "pay_123abc456def",
      "wallet_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "source_currency": "CAD",
      "source_amount": "150.00",
      "destination_currency": "CAD",
      "destination_amount": "150.00",
      "memo": "Invoice #INV-2023-001",
      "status": "STATE_COMPLETED",
      "date": "2023-01-20T10:00:00Z",
      "beneficiary": {
        "id": "bene_zyxw9876",
        "name": "Jane Smith",
        "currency": "CAD",
        "country": "CA"
      }
    }
  ],
  "last_seen_id": "pay_lmn456opq789"
}

POST/orionapi.v1.OrionService/GetPayment#

Retrieve details of a single payment by its system ID or your customer_reference.

Field Type Description Required
payment_id string (UUID) Payment identifier. Conditional*
customer_reference string Your reference for the payment. Conditional*

*Provide either payment_id or customer_reference. If both are provided, payment_id takes precedence.

Sample Request 
{
  "payment_id": "pay_123abc456def"
}
Sample Response 
{
  "payment": {
    "reference": "pay_123abc456def",
    "wallet_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "source_currency": "CAD",
    "source_amount": "150.00",
    "destination_currency": "CAD",
    "destination_amount": "150.00",
    "memo": "Invoice #INV-2023-001",
    "customer_reference": "CUST_PAY_98765",
    "network_reference": "CAQDpWCrwq7J",
    "status": "STATE_COMPLETED",
    "date": "2023-01-20T10:00:00Z",
    "beneficiary": {
      "id": "bene_zyxw9876",
      "name": "Jane Smith",
      "currency": "CAD",
      "country": "CA",
      "total_received": "150.00"
    },
    "initiator": "John Doe",
    "exchange_rate": "1.00"
  }
}

Beneficiaries#

POST/orionapi.v1.OrionService/CreateBeneficiary#

Create a new beneficiary record (person or business) for future payments.

Field Type Description Required
beneficiary Beneficiary Beneficiary to create. Yes
Sample Request 
{
  "beneficiary": {
    "name": "Global Exports Inc.",
    "account_number": "123456789",
    "routing_number": "021000021",
    "currency": "USD",
    "address": {
      "line1": "123 Business Rd",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "type": "BENEFICIARY_TYPE_ACH",
    "entity_type": "BENEFICIARY_ENTITY_TYPE_BUSINESS",
    "country": "US"
  }
}
Sample Response 
{
  "beneficiary": {
    "id": "bene_fedcba9876",
    "name": "Global Exports Inc.",
    "account_number": "******789",
    "routing_number": "021000021",
    "currency": "USD",
    "address": {
      "line1": "123 Business Rd",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "type": "BENEFICIARY_TYPE_ACH",
    "entity_type": "BENEFICIARY_ENTITY_TYPE_BUSINESS",
    "country": "US",
    "total_received": "0.00"
  }
}

POST/orionapi.v1.OrionService/ListBeneficiaries#

List saved beneficiaries with filters and cursor pagination.

Field Type Description Required
currency string Filter by currency. No
id string (UUID) Retrieve a single beneficiary by ID. No
type enum Beneficiary type (e.g., BENEFICIARY_TYPE_SWIFT). No
entity_type enum BENEFICIARY_ENTITY_TYPE_INDIVIDUAL | BENEFICIARY_ENTITY_TYPE_BUSINESS. No
search string Free-text search on name, email, etc. No
customer_identifier string Your external ID for the beneficiary. No
email string Beneficiary email. No
pagination PaginationCursor Paging controls. No
Sample Request 
{
  "currency": "USD",
  "entity_type": "BENEFICIARY_ENTITY_TYPE_BUSINESS",
  "pagination": {
    "page_size": 10
  }
}
Sample Response 
{
  "beneficiaries": [
    {
      "id": "bene_fedcba9876",
      "name": "Global Exports Inc.",
      "currency": "USD",
      "country": "US",
      "type": "BENEFICIARY_TYPE_ACH",
      "entity_type": "BENEFICIARY_ENTITY_TYPE_BUSINESS",
      "total_received": "12500.00"
    }
  ],
  "pagination": {
    "next_page_cursor": "c3RhcnRfa2V5PWJlbmVfNzg5MGFCSQ==",
    "page_size": 10
  }
}

Quotes#

POST/orionapi.v1.OrionService/CreateQuote#

Create an FX quote to lock an exchange rate for an upcoming conversion or payment. Provide either a source amount or a target amount (but not both).

Field Type Description Required
source_currency string Currency you are selling. Yes
target_currency string Currency you are buying. Yes
source_amount string (decimal) Amount in source currency. Conditional*
target_amount string (decimal) Amount desired in target currency. Conditional*

*Supply exactly one of source_amount or target_amount.

Sample Request 
{
  "source_currency": "CAD",
  "target_currency": "USD",
  "source_amount": "1000.00"
}
Sample Response 
{
  "quote_id": "q_abcdef123456",
  "source_currency": "CAD",
  "target_currency": "USD",
  "exchange_rate": "0.7351",
  "source_amount": "1000.00",
  "target_amount": "735.10",
  "expires_at": "2023-10-27T10:05:00Z",
  "fees": "5.00"
}

Objects#

Below are the common objects returned by the Pesa Business API. Fields marked optional may be omitted or null depending on the operation and payment network.

Wallet Object#

Field Type Description
id string (UUID) Wallet identifier.
currency string ISO wallet currency.
available_balance string (decimal) Current spendable balance.
last_transactions Transaction[] Recent transactions (may be empty).
funding_accounts WalletFundingAccount[] Funding instructions (local, SWIFT, etc.).

Transaction Object#

Field Type Description
id string Transaction identifier.
wallet_id string Wallet the transaction belongs to.
currency string Transaction currency.
debit_amount string (decimal) Debited amount (for debits).
credit_amount string (decimal) Credited amount (for credits).
balance_amount string (decimal) Wallet balance after transaction.
narration string Description / memo.
type enum TRANSACTION_TYPE_CREDIT | TRANSACTION_TYPE_DEBIT.
category enum E.g., TRANSACTION_CATEGORY_FUNDING, TRANSACTION_CATEGORY_PAYMENT.
created_at string (ISO 8601) Creation timestamp.
network_reference string Upstream network reference (if any).
depositors_name string Depositor name (if known).
depositors_instrument string Depositor instrument (if known).
depositors_institution string Depositor institution (if known).
metadata object Supplemental data; may embed Payment or FXTransaction info.

Payment Object#

Field Type Description
reference string System-generated payment reference.
wallet_id string Source wallet.
source_currency string Currency debited.
source_amount string Amount debited.
memo string Memo shown to recipient.
customer_reference string Your reference for reconciliation.
network_reference string External network reference.
status enum Current payment state (e.g., STATE_PENDING, STATE_COMPLETED).
date string (ISO 8601) Processing timestamp.
beneficiary Beneficiary Recipient info.
initiator string User who initiated payment.
destination_currency string Currency received by beneficiary.
destination_amount string Amount received.
exchange_rate string Rate applied.
security_answer string Security answer (some networks only).

Beneficiary Object#

Field Type Description
id string System-generated identifier.
name string Full name of individual or business.
account_number string Bank account number. Optional.
sort_code string UK sort code. Optional.
iban string IBAN. Optional.
swift_code string SWIFT/BIC code. Optional.
institution_number string Canadian institution number. Optional.
transit_number string Canadian transit/branch number. Optional.
email string Email address. Optional.
bank_name string Beneficiary bank name. Optional.
routing_number string US ACH routing number. Optional.
currency string Account currency.
address Address Mailing address. Optional.
phone_number string Contact phone. Optional.
type enum Network/payment type (e.g., BENEFICIARY_TYPE_INTERAC, BENEFICIARY_TYPE_SWIFT).
entity_type enum BENEFICIARY_ENTITY_TYPE_INDIVIDUAL | BENEFICIARY_ENTITY_TYPE_BUSINESS.
country string 2-letter ISO country code.
total_received string Cumulative received amount.

PaginationCursor Object#

Field Type Description
prev_page_cursor string Cursor for previous page (omit on first page).
next_page_cursor string Cursor for next page (omit on last page).
page_size number Max results per page requested.

Address Object#

Field Type Description
line1 string Address line 1.
line2 string Address line 2. Optional.
city string City.
state string State / province / region.
postal_code string Postal / ZIP code.
country string 2-letter ISO country code.

WalletFundingAccount Object#

Field Type Description
id string Funding account identifier.
account_name string Name label (e.g., "CAD Local Account").
local_account FundingAccountDetails Local rails funding instructions.
swift_account FundingAccountDetails SWIFT funding instructions.

FundingAccountDetails Object#

Field Type Description
swift_code string SWIFT code. Optional.
account_number string Account number. Optional.
sort_code string UK sort code. Optional.
iban string IBAN. Optional.
institution_number string Canadian institution number. Optional.
transit_number string Canadian transit number. Optional.
email string Email for e-transfers. Optional.
institution_name string Financial institution name. Optional.
routing_number string US routing number. Optional.
address string Institution address. Optional.