Payfrica Partner API

The Payfrica Partner API allows 3rd party integrators to leverage Payfrica's Onramp and Offramp capabilities.

Base URL

Public API

https://backend.payfrica.xyz/api/v1/partners

Authentication

Public API Authentication (API Keys)

Used for server-to-server integration.

x-partner-api-key:pk_live_...

x-partner-api-secret:sk_live_...

CAUTION

Never expose your x-partner-api-secret in frontend code. Public API requests must be made from your secure backend server.

1. Public API Endpoints

Base URL: /api/v1/partners

GET/rates

Get real-time exchange rates for Onramp or Offramp.

Query Parameters

typestring

onramp | offramp (default: onramp)

currencystring

NGN, KES, GHS (default: NGN)

amountnumber

Fiat amount (for onramp) or Crypto amount (for offramp)

cryptostring

USDC | SUI (default: USDC)

Response

{
  "rate": "1650.50",
  "fiatAmount": "5000",
  "suiAmount": "3.03"
}

POST/onramp

Initiate a fiat-to-crypto transaction for a user.

Request Body

{
  "amount": 5000,
  "currency": "NGN",
  "suiAddress": "0x123...",
  "targetAsset": "SUI",
  "customer": {
    "email": "user@example.com"
  },
  "callbackUrl": "https://your-app.com/payment/callback"
}

Response

{
  "id": "uuid",
  "status": "WAITING_FIAT",
  "authorizationUrl": "https://paystack.com/...",
  "partnerId": "..."
}

POST/offramp

Initiate a crypto-to-fiat transaction. You provide the transaction digest of the user's crypto transfer to Payfrica.

Request Body

{
  "digest": "tx_digest_string...",
  "cryptoAsset": "USDC",
  "recipient": {
    "institution": "OPAYNGPC",
    "accountIdentifier": "0123456789",
    "accountName": "John Doe",
    "currency": "NGN",
    "memo": "Payment for services",
    "institutionName": "OPay"
  }
}

Response

{
  "id": "uuid",
  "status": "WAITING_CRYPTO"
}

GET/banks

Get a list of supported financial institutions for a given currency. Returns institutions that are supported by both Paystack (for onramp) and Paycrest (for offramp).

Query Parameters

currencystring

NGN, KES, GHS (default: NGN)

Response

{
  "success": true,
  "data": [
    {
      "name": "OPay",
      "code": "OPAYNGPC",
      "type": "MOBILE_MONEY",
      "paystackCode": "999992"
    },
    {
      "name": "PalmPay",
      "code": "PALMNGPC",
      "type": "MOBILE_MONEY",
      "paystackCode": "999991"
    },
    {
      "name": "Kuda Microfinance Bank",
      "code": "KUDANGPC",
      "type": "BANK",
      "paystackCode": "50211"
    }
  ],
  "message": "Supported institutions retrieved successfully for NGN"
}

GET/verify-account

Verify a bank account number and retrieve the account holder's name. This endpoint uses Paystack's account resolution service.

Query Parameters

accountNumber*string

The bank account number to verify

bankCode*string

The Paystack bank code (use paystackCode from /banks endpoint)

Response

{
  "success": true,
  "data": {
    "accountNumber": "0123456789",
    "accountName": "JOHN DOE"
  },
  "message": "Bank account verified successfully"
}

GET/orders/:id

Get the status of an order.

Query Parameters

id*string

The UUID of the order

Response

{
  "id": "uuid",
  "status": "COMPLETED",
  "cryptoAmountReceived": "100",
  "nairaPayoutCalculated": "150000"
}