Quickstart

This walkthrough takes you from a fresh app to a completed transfer. Everything here runs against the sandbox, so no real money moves.

Before you begin

You need an AppId and a sandbox secret key. Both come from Developers → Configuration in the dashboard — see Create an app if you have not made one yet. Keep them out of your source code:

export PILA_APP_ID="<your_app_id>"
export PILA_SECRET_KEY="<your_sandbox_secret_key>"
export PILA_BASE_URL="https://sandbox.trypila.co"

Create a wallet

A wallet is a dedicated Nigerian account number belonging to one of your customers. Anything paid into it credits that wallet’s balance.

curl -X POST "$PILA_BASE_URL/api/v1/wallet/ngn/create" \
  -H "Authorization: $PILA_SECRET_KEY" \
  -H "AppId: $PILA_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Ada",
        "last_name": "Obi",
        "dob": "1990-04-12",
        "phone_number": "08158070522",
        "bvn": "22345678901",
        "route": "PROVIDUS"
      }'

The response carries the wallet_id you will use for every later call, plus the account number to give your customer.

{
  "entity": {
    "wallet_id": "254a14e1-25ac-338a-94ed-9e4041840599",
    "wallet_amount": 0,
    "account_number": "1200335704",
    "phone_number": "08158070522"
  }
}

Full parameter list: Create a wallet.

Subscribe to webhooks

Deposits are asynchronous — nothing in the API tells you money arrived unless you ask to be told. Point Pila at a URL you control.

curl -X POST "$PILA_BASE_URL/api/v1/webhook/subscribe" \
  -H "Authorization: $PILA_SECRET_KEY" \
  -H "AppId: $PILA_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
        "webhook": "https://example.com/hooks/pila",
        "service": "ngn_wallet"
      }'

Verify the x-pila-signature header on everything that arrives before you act on it. See Webhook signatures.

Check the balance

Read the wallet back to confirm it was funded.

curl "$PILA_BASE_URL/api/v1/wallet/ngn/retrieve?wallet_id=$WALLET_ID" \
  -H "Authorization: $PILA_SECRET_KEY" \
  -H "AppId: $PILA_APP_ID"

{
  "entity": {
    "wallet_id": "254a14e1-25ac-338a-94ed-9e4041840599",
    "wallet_amount": 1172,
    "account_number": "1004656370",
    "phone_number": "09032652195",
    "bank_name": "VFD MFB"
  }
}

Send a transfer

Confirm the recipient first, then move the money. Resolving the NUBAN is not required, but it is the difference between a customer complaint and a clean payout.

# 1. Confirm who owns the account
curl "$PILA_BASE_URL/api/v1/general/account?account_number=0129531833&bank_code=058" \
  -H "Authorization: $PILA_SECRET_KEY" \
  -H "AppId: $PILA_APP_ID"

# 2. Send the money
curl -X POST "$PILA_BASE_URL/api/v1/wallet/ngn/transfer" \
  -H "Authorization: $PILA_SECRET_KEY" \
  -H "AppId: $PILA_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
        "wallet_id": "'"$WALLET_ID"'",
        "amount": "5000",
        "recipient_bank_code": "058",
        "recipient_account_number": "0129531833",
        "source": "wallet"
      }'

A transfer comes back as PROCESSING, not COMPLETED. Wait for the webhook, or poll Transaction details with the returned transaction_id.

{
  "entity": {
    "transaction_id": "Pila-6bddb725-2ca9-31c0-b0fb-13f7f11adf90",
    "transaction_status": "PROCESSING",
    "transaction_amount": 5000,
    "transaction_type": "transfer"
  }
}

Going live

Get your account verified

Complete your company information and request verification from Settings. See Create an app.

Fund your Pila wallet

Live payouts settle from your funded balance. See Fund your wallet.

Swap two values

Change PILA_BASE_URL to https://api.trypila.co and PILA_SECRET_KEY to your live key. Every request body stays identical.

Re-subscribe your webhooks in the live environment. Sandbox subscriptions do not carry over.

Get started

Core concepts

API Endpoints

Before you begin

Going live

Where to next

Issue a virtual USD card

Browse every task

​Before you begin

​Going live

​Where to next

Issue a virtual USD card

Browse every task

Before you begin

Going live

Where to next