PayIns

Overview

PayIn transactions allow you to receive payments from your customers via mobile money, card, or bank transfer. When a customer pays you, the funds are credited to your merchant wallet.

ℹī¸ Note: PayIn transactions are asynchronous. You'll receive an immediate acknowledgment, then get the final status via webhook callback or by querying the transaction status.

Supported Payment Methods

Below are the payment channels and methods available:

Mobile Money

Available for the following countries:

Country Code Available Methods
Democratic Republic of Congo CD mpesa, airtel, orange, afrimoney
Zambia ZM airtel, mtn, zamtel
💡 Tip: Use these method slugs in the method parameter when initiating transactions.
Bank Transfer

Bank transfer payments are accepted in NGN for Nigeria. The API creates a virtual bank account that your customer transfers money into. No phone_number or method parameter is required — set channel to bank_transfer and country to NG.

Country Code Currency Method
Nigeria NG NGN bank_transfer

Upon successful initialization, the API returns a bank_account object. Redirect or display these details to your customer so they can complete the transfer from their own bank app.

⚠ī¸ Important: The virtual account is single-use and tied to this transaction. Do not reuse it for a different payment.
Card

Card payments are accepted globally in USD only. No country or method parameter is required — set channel to card and the system handles the rest.

Upon successful initialization, the API returns a payment_url where the customer must be redirected to complete the card payment on the hosted payment page.

💡 Tip: Use "is_test": true to process test card transactions without real charges. Test mode is only available for the card channel.

POST Initiate PayIn 

https://genesyspay.com/api/v2/payins

Create a new PayIn transaction to receive payment from a customer.

Request Parameters
Common Parameters
Parameter Type Required Description
amount number Required Transaction amount
currency string Required 3-letter currency code (e.g., CDF, USD, ZMW). Card payments only accept USD.
channel string Required Payment channel: mobile_money or card
country string Required* 2-letter country code (e.g., CD, ZM). *Required for mobile_money, not used for card.
method string Required* Payment method (e.g., airtel, orange). *Required for mobile_money, not used for card.
phone_number string Required* Customer phone number. *Required for mobile_money and card.
email string Required* Customer email address. *Required for card.
tx_ref string Required Your unique transaction reference
callback_url string Optional URL to receive transaction status webhook
redirect_url string Optional URL to redirect the customer after successful card payment
cancel_url string Optional URL to redirect the customer if they cancel the card payment
bearer string Optional Who bears the transaction fee: customer (default) or merchant
extras object Optional Custom data to attach to transaction (returned in webhooks)
Bank Transfer Parameters

When channel is bank_transfer, use the following instead of phone_number/method:

Parameter Type Required Description
country string Required Must be NG for bank transfer
currency string Required Must be NGN for bank transfer
method string Required Use bank_transfer
Card-Specific Parameters

The following billing parameters are required when channel is card:

Parameter Type Required Description
first_name string Required Cardholder first name
last_name string Required Cardholder last name
billing_address_line1 string Required Billing street address
billing_city string Required Billing city
billing_state string Required Billing state / province
billing_postal_code string Required Billing postal / ZIP code
billing_country string Required 2-letter billing country code (e.g., US, CD)
is_test boolean Optional Set to true to process a test card transaction (no real charge). Only available for card channel.
Example Request — Mobile Money
curl -X POST https://genesyspay.com/api/v2/payins \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -d '{
  "currency": "CDF",
  "amount": 100,
  "country": "CD",
  "channel": "mobile_money",
  "method": "airtel",
  "phone_number": "2439xxxxxxxx",
  "tx_ref": "X238V",
  "callback_url": "https://yoursite.com/webhook",
  "extras": {
    "customer_id": "3028",
    "order_id": "F23"
  }
}'
Success Response — Mobile Money
{
  "status": "success",
  "message": "Payment initialized successfully",
  "data": {
    "transaction_id": "MP260214.081725.E7B5DBC4",
    "tx_ref": "X238V",
    "amount": "100.00",
    "fee": "0.00",
    "total_amount": "100.00",
    "currency": "CDF",
    "status": "SUBMITTED",
    "channel": "mobile_money",
    "payment_method": "airtel",
    "summary": "Payment to BIZ via airtel",
    "mobile_money": {
      "phone_number": "2439xxxxxxxx",
      "network": "airtel",
      "mno_transaction_id": null
    },
    "failure_reason": null,
    "extras": {
      "customer_id": "3028",
      "order_id": "F23"
    },
    "account_balance": null,
    "created_at": "2026-02-14T08:17:25+00:00",
    "updated_at": "2026-02-14T08:17:27+00:00",
    "phone_number": "2439xxxxxxxx"
  }
}
Example Request — Card
curl -X POST https://genesyspay.com/api/v2/payins \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -d '{
  "currency": "USD",
  "amount": 25.00,
  "channel": "card",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone_number": "2439xxxxxxxx",
  "billing_address_line1": "123 Main Street",
  "billing_city": "Kinshasa",
  "billing_state": "Kinshasa",
  "billing_postal_code": "00000",
  "billing_country": "CD",
  "tx_ref": "CARD-X001",
  "redirect_url": "https://yoursite.com/payment/success",
  "cancel_url": "https://yoursite.com/payment/cancel",
  "callback_url": "https://yoursite.com/webhook",
  "is_test": true
}'
Success Response — Card

For card payments the response includes a payment_url. Redirect your customer to this URL to complete the payment on the hosted card payment page.

{
  "status": "success",
  "message": "Payment initialized successfully",
  "data": {
    "transaction_id": "CP260410.102530.A1B2C3D4",
    "tx_ref": "CARD-X001",
    "amount": "25.00",
    "fee": "0.75",
    "total_amount": "25.75",
    "currency": "USD",
    "status": "SUBMITTED",
    "channel": "card",
    "payment_method": "card",
    "summary": "Card payment to BIZ",
    "failure_reason": null,
    "extras": null,
    "account_balance": null,
    "payment_url": "https://pay.gofreshpay.com/checkout/abc123xyz",
    "created_at": "2026-04-10T10:25:30+00:00",
    "updated_at": "2026-04-10T10:25:31+00:00",
    "email": "[email protected]"
  }
}
Example Request — Bank Transfer (Nigeria)
curl -X POST https://genesyspay.com/api/v2/payins \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -d '{
  "currency": "NGN",
  "amount": 5000,
  "country": "NG",
  "channel": "bank_transfer",
  "method": "bank_transfer",
  "tx_ref": "BT-NG-001",
  "callback_url": "https://yoursite.com/webhook"
}'
Success Response — Bank Transfer

The response includes a bank_account object. Display these details to your customer so they can complete the transfer.

{
  "status": "success",
  "message": "Payment initialized successfully",
  "data": {
    "transaction_id": "BT260521.141500.X9Y8Z7W6",
    "tx_ref": "BT-NG-001",
    "amount": "5000.00",
    "fee": "50.00",
    "total_amount": "5050.00",
    "currency": "NGN",
    "status": "SUBMITTED",
    "channel": "bank_transfer",
    "payment_method": "bank_transfer",
    "summary": "Bank transfer to BIZ",
    "bank_account": {
      "account_number": "1234567890",
      "account_name": "BIZ / BT-NG-001",
      "bank_name": "VFD Bank"
    },
    "failure_reason": null,
    "extras": null,
    "account_balance": null,
    "created_at": "2026-05-21T14:15:00+00:00",
    "updated_at": "2026-05-21T14:15:01+00:00"
  }
}
💡 How it works: Once your customer makes the bank transfer to the displayed account, we receive a confirmation from the banking network and update the transaction to SUCCESS, then fire a webhook to your callback_url.
⚠ī¸ Important: The payment_url is a one-time link. Redirect the customer to this URL as soon as possible after receiving the response. The link expires after a short period of inactivity.
Test Cards

Use the following test card numbers when "is_test": true is set. Use any future expiry date and any 3-digit CVV.

Card Number Expiry Result
4000 0000 0000 0002 Any future date Successful payment
Error Responses
Error Code HTTP Status Description
VALIDATION_ERROR 422 Invalid or missing parameters
INVALID_CURRENCY 422 Currency not supported
INVALID_COUNTRY 422 Country not supported
METHOD_NOT_AVAILABLE 422 Payment method not available for currency/country
INVALID_ARGUMENT 400/422 tx_ref already exists or amount outside limits
PAYMENT_FAILED 422 Payment processing failed
PROVIDER_ERROR 422 Payment provider error

GET Get Transaction by ID 

https://genesyspay.com/api/v2/payins/{identifier}

Retrieve a specific PayIn transaction by its ID or reference.

Example Request
curl -X GET https://genesyspay.com/api/v2/payins/TXN-REF-123456 \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY"
Response
{
  "status": "success",
  "data": {
    "transaction_id": "TXN-REF-123456",
    "tx_ref": "TXN-2026-001",
    "amount": "5000.00",
    "fee": "150.00",
    "total_amount": "5150.00",
    "currency": "CDF",
    "status": "SUCCESS",
    "channel": "mobile_money",
    "payment_method": "airtel",
    "summary": "Payment completed successfully",
    "mobile_money": {
      "phone_number": "0707070707",
      "network": "airtel",
      "mno_transaction_id": "MNO123456789"
    },
    "account_balance": {
      "previous_balance": "10000.00",
      "current_balance": "14850.00",
      "balance_type": "AVAILABLE"
    },
    "created_at": "2026-02-14T10:30:00Z",
    "updated_at": "2026-02-14T10:32:15Z"
  }
}

GET Get Transaction by tx_ref 

https://genesyspay.com/api/v2/payins/status/{txRef}

Retrieve a PayIn transaction using your custom transaction reference.

Example Request
curl -X GET https://genesyspay.com/api/v2/payins/status/TXN-2026-001 \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY"

GET List PayIn Transactions 

https://genesyspay.com/api/v2/payins

Retrieve a paginated list of all PayIn transactions.

Query Parameters
Parameter Type Description
status string Filter by status: PENDING, SUBMITTED, SUCCESS, FAILED, CANCELLED
per_page integer Results per page (1-100, default: 20)
page integer Page number (default: 1)
Example Request
curl -X GET "https://genesyspay.com/api/v2/payins?status=SUCCESS&per_page=10&page=1" \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY"
Response
{
  "status": "success",
  "data": [
    {
      "transaction_id": "TXN-REF-123456",
      "tx_ref": "TXN-2026-001",
      "amount": "5000.00",
      "status": "SUCCESS",
      "created_at": "2026-02-14T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 10,
    "total": 50
  }
}

Transaction Statuses

Status Description
PENDING Transaction initiated, awaiting customer action
SUBMITTED Transaction submitted to payment provider
SUCCESS Payment completed successfully
FAILED Payment failed
CANCELLED Transaction cancelled

Webhook Notification

When a transaction status changes, we'll send a POST request to your callback_url with the transaction details. For detailed webhook implementation guide, security best practices, and webhook resend functionality, see the Webhooks documentation.

Quick Overview

Here's an example of what you'll receive:

        {
            "event":"payin.successful",
            "timestamp":1770993791,
            "data":{
                "transaction_id":"MP260213.144231.E679AA9A",
                "tx_ref":"1234kj0e30m12",
                "amount":"15.00",
                "fee":"0.45",
                "total_amount":"15.45",
                "currency":"ZMW",
                "status":"SUCCESS",
                "channel":"mobile_money",
                "payment_method":"airtel",
                "summary":"Payment to BIZ via airtel",
                "failure_reason":null,
                "created_at":"2026-02-13T14:42:31+00:00",
                "updated_at":"2026-02-13T14:43:08+00:00",
                "mobile_money":{
                    "phone_number":"260773317519",
                    "network":"airtel",
                    "mno_transaction_id":null
                },
                "extras":{
                    "customer_id":"3028",
                    "order_id": "F23"
                },
                "account_balance":{
                    "previous_balance":"880.00",
                    "current_balance":"895.00",
                    "balance_type":"AVAILABLE"
                }
            }
        }
💡 Tip: Your webhook endpoint should respond with HTTP 200 to acknowledge receipt. We will retry failed webhook deliveries with exponential backoff. If you miss a webhook, you can manually resend it using the resend webhook endpoint - see the Webhooks documentation for implementation details, security best practices, and more.
Previous: Lookup Next: PayOuts