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...",
  "recipient": {
    "institution": "058",
    "accountIdentifier": "0123456789",
    "accountName": "John Doe",
    "currency": "NGN"
  }
}

Response

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

POST/offramp/instant

Initiate a crypto-to-fiat transaction with immediate payout via SafeHaven. This is currently only supported for NGN.

Request Body

{
  "digest": "tx_digest_string...",
  "cryptoAsset": "USDC",
  "recipient": {
    "institution": "058",
    "accountIdentifier": "0123456789",
    "accountName": "John Doe",
    "currency": "NGN",
    "memo": "Instant payout"
  }
}

Response

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

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"
}

POST/verify-nin

Verify the identity of a user using their National Identification Number (NIN) or Phone Number. This is required for KYC compliance.

Request Body

{
  "firstname": "John",
  "lastname": "Doe",
  "suiAddress": "0x123...",
  "nin": "12345678901",
  "phone": "08012345678",
  "dob": "1990-01-01",
  "gender": "m"
}

Response

{
  "status": {
    "status": "verified",
    "state": "MATCH_FOUND"
  },
  "nin": {
    "firstname": "John",
    "lastname": "Doe",
    "nin": "12345678901",
    "phone": "08012345678",
    "dob": "1990-01-01",
    "gender": "m"
  }
}

Error Responses

401 Unauthorized - Paused Partner

{
  "statusCode": 401,
  "message": "Partner operations are currently paused. Please contact support."
}

401 Unauthorized - Unverified Partner

{
  "statusCode": 401,
  "message": "Partner account is not verified. Please contact support."
}

403 Forbidden - Key Rotation

{
  "statusCode": 403,
  "message": "Partner account must be verified before API keys can be generated or rotated"
}