API Reference

The PayTaara API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Sandbox vs Live Mode

You can use the PayTaara API in test mode, which doesn't affect your live data or interact with banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.

Base URL

All API requests should be made to our base URL.

https://api.paytaara.com/v1

Authentication

Authenticate your API requests by including your secret key in the Authorization header.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Bearer Token

Provide your secret key as a Bearer token in the Authorization header. You can manage your API keys in the Developer Dashboard.

Authentication Example

curl https://api.paytaara.com/v1/balance \
  -H "Authorization: Bearer sk_test_123456789"

Create a Payout

POST

Send money directly to any supported bank account globally.

POST/v1/payouts

Request Parameters

amount

integerRequired

Amount to send in the lowest denomination (e.g., kobo or cents). For example, 50000 = ₦500.00.

bank_code

stringRequired

The 3-digit central bank code of the destination bank. You can fetch a list of supported banks via the /v1/banks endpoint.

account_number

stringRequired

The recipient's 10-digit NUBAN account number.

narration

string

Description of the transfer, visible to the recipient. Maximum 50 characters.

Request

curl -X POST https://api.paytaara.com/v1/payouts \
  -H "Authorization: Bearer sk_test_12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "bank_code": "058",
    "account_number": "0123456789",
    "narration": "Payment for Q3 Invoice",
    "currency": "NGN"
  }'

Response200 OK

{
  "status": true,
  "message": "Payout initiated successfully",
  "data": {
    "id": "po_928374823",
    "reference": "tx_req_1002938",
    "amount": 500000,
    "fee": 5000,
    "status": "processing",
    "recipient": {
      "name": "JOHN DOE",
      "account_number": "0123456789",
      "bank_name": "Guaranty Trust Bank"
    },
    "created_at": "2023-10-24T12:00:00Z"
  }
}

Create Virtual Account

POST

Provision a dedicated static bank account for your customer to receive inbound transfers.

POST/v1/virtual-accounts

Request Parameters

customer_id

stringRequired

The unique ID of the customer you are provisioning the account for. Must be created prior to this call.

bvn

string

Customer's Bank Verification Number (Increases receiving limits on the account).

Request

{
  "customer_id": "cust_8273948",
  "bvn": "22334455667"
}

Response200 OK

{
  "status": true,
  "message": "Virtual account created",
  "data": {
    "account_number": "9988776655",
    "account_name": "PayTaara / Jane Smith",
    "bank_name": "Providus Bank",
    "currency": "NGN",
    "status": "active"
  }
}