Skip to content
PayHero Africa

Create a payment (pay-in or pay-out)

POST
/api/global/payments
curl -X POST "https://api.payhero.africa/api/global/payments" \
  -u "API_USERNAME:API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
  "request_type": "payment",
  "transaction_channel": "momo",
  "provider": "yellowcard",
  "amount": 5500,
  "currency": "KES",
  "country": "KE",
  "reason": "Order payment for invoice INV-2025-001",
  "source": "api",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+254712345678",
    "dob": "1990-01-01T00:00:00Z",
    "country": "KE",
    "address": {
      "line_1": "Westlands Road",
      "country": "KE"
    }
  },
  "vendor_config": {
    "vendor_id": 63
  },
  "provider_config": {
    "network_id": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
    "channel_id": "27bd1cf0-8399-497a-9ce6-a30c3a9e82a0",
    "network_name": "Mobile Wallet (M-PESA)",
    "network_code": "M PESA",
    "account_type": "momo"
  },
  "payment_config": {
    "reference": "test_top_",
    "account_number": "+254712345678",
    "remark": "order payment",
    "payment_category": "bill payment",
    "callback_url": "https://payhero-dev.beeceptor.com",
    "redirect_url": "https://payhero-dev.beeceptor.com"
  }
}'

Initiates a collection (request_type: payment) or a disbursement (request_type: withdrawal). Works across all supported countries — set currency, country, provider, and the relevant provider_config.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
request_type
required

payment for pay-in (collection), withdrawal for pay-out (disbursement).

string
Allowed values: payment withdrawal
transaction_channel
required

Rail to use.

string
Allowed values: momo bank card
provider
required

Payment provider (see Discovery API).

string
amount
required
number
currency
required

ISO 4217 currency code.

string
country
required

ISO 3166-1 alpha-2 country code.

string
reason
string
source
string
customer
required

For collections this is the paying customer. For withdrawals this is the recipient (your own KYC details when withdrawing to yourself).

object
first_name
required
string
last_name
required
string
email
string format: email
phone
required

Customer phone number; usually the same as the account number.

string
dob

Date of birth. Required for bank rails; for mobile top-ups use your KYC’s DOB. Not required for mobile top-ups.

string format: date-time
country
required
string
id_type

Identity document type (e.g. national_id, NIN, passport).

string
id_number
string
additional_id_type
string
additional_id_number
string
address
object
line_1
string
country

ISO 3166-1 alpha-2 country code.

string
vendor_config
object
vendor_id

Your vendor ID.

integer
channel_id

Your wallet channel ID.

integer
provider_config

Provider/network routing details (from the Discovery API).

object
network_id
string
channel_id
string
provider_id
string
network_name
string
network_code
string
account_type
string
payment_config
object
reference
string
account_number
string
remark
string
payment_category
string
callback_url
string format: uri
redirect_url
string format: uri
payment_split
object
amount_to_save
number
Examples

Pay-in — Kenya (KES, YellowCard MoMo)

{
  "request_type": "payment",
  "transaction_channel": "momo",
  "provider": "yellowcard",
  "amount": 5500,
  "currency": "KES",
  "country": "KE",
  "reason": "Order payment for invoice INV-2025-001",
  "source": "api",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+254712345678",
    "dob": "1990-01-01T00:00:00Z",
    "country": "KE",
    "address": {
      "line_1": "Westlands Road",
      "country": "KE"
    }
  },
  "vendor_config": {
    "vendor_id": 63
  },
  "provider_config": {
    "network_id": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
    "channel_id": "27bd1cf0-8399-497a-9ce6-a30c3a9e82a0",
    "network_name": "Mobile Wallet (M-PESA)",
    "network_code": "M PESA",
    "account_type": "momo"
  },
  "payment_config": {
    "reference": "test_top_",
    "account_number": "+254712345678",
    "remark": "order payment",
    "payment_category": "bill payment",
    "callback_url": "https://payhero-dev.beeceptor.com",
    "redirect_url": "https://payhero-dev.beeceptor.com"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Payment request accepted and queued for processing.

Media typeapplication/json
object
status_code
string
merchant_reference
string
transaction_type
string
Allowed values: payin payout
success
boolean
message
string
checkout_request_id
string
gateway
string
conversation_id
string
provider_response

Raw provider response details.

object
key
additional properties
any
Examples

Pay-in accepted

{
  "status_code": "200",
  "merchant_reference": "9FD194041588.iI",
  "transaction_type": "payin",
  "success": true,
  "message": "request sent",
  "checkout_request_id": "a8e1c979-3592-5abd-b1cd-dc1dbd34e708",
  "gateway": "yellowcard",
  "conversation_id": "9FD194041588.iI",
  "provider_response": {
    "amount": 42.11,
    "convertedAmount": 5500,
    "country": "KE",
    "currency": "KES",
    "rate": 130.61,
    "status": "process"
  }
}

400

Section titled “400”

The request was rejected (validation or business-rule failure).

Media typeapplication/json
object
error_code
string
error_message
string
status_code
integer
Examples
{
  "error_code": "invalid_argument",
  "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)",
  "status_code": 400
}

401

Section titled “401”

Missing or invalid Basic auth credentials.

Media typeapplication/json
object
error_code
string
error_message
string
status_code
integer
Example
{
  "error_code": "invalid_argument",
  "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)",
  "status_code": 400
}