Response format

Pila responses are JSON, and successful ones wrap the payload in a single top-level key: entity.

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

The shape of entity depends on the endpoint.

Object
Array
Scalar

Most endpoints return a single record.

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

List endpoints — banks, transactions, states — return an array.

{
  "entity": [
    { "name": "Access Bank", "code": "044" },
    { "name": "Citibank Nigeria", "code": "023" }
  ]
}

A few endpoints return a plain value or a short confirmation.

{
  "entity": "Card blocked successfully"
}

Always read your data from entity, never from the root of the response. Endpoints gain fields over time; parsing defensively means a new field never breaks your integration.

Success and failure

The HTTP status code is the authoritative signal.

Code	Meaning	What to do
`200`	The request succeeded	Read `entity`
`400`	Something in your request was invalid	Fix the request — retrying will not help
`401`	Missing or wrong credentials	Check your `Authorization` and `AppId` headers
`403`	Not permitted for this app or environment	Check verification status and environment
`404`	The resource does not exist	Check the identifier you sent
`429`	Too many requests	Back off and retry with exponential delay
`5xx`	A problem on Pila’s side or an upstream provider’s	Safe to retry with backoff

Do not treat “not a 5xx” as “money moved”. A 200 on a transfer means the instruction was accepted, not that it settled. See Transaction statuses below.

Transaction statuses

Money movement is asynchronous. Transfers, card loads and withdrawals come back before they have completed.

Status	Meaning
`PROCESSING`	Accepted and in flight. Not final.
`COMPLETED`	Settled successfully.
`FAILED`	Did not go through. Funds are not debited.

Wait for the webhook, or poll Transaction details with the transaction_id you received. Do not assume a PROCESSING transfer succeeded.

Handling responses well

Set explicit timeouts

Pila calls out to banks and card processors on your behalf. Use a connect timeout of around 5 seconds and a read timeout of 30 seconds — never an infinite default.

Retry only what is retryable

Retry 429 and 5xx responses with exponential backoff, up to three attempts. Never retry a 4xx — the request itself is the problem, and a retried transfer can become a double payment.

Be idempotent on your side

Record the transaction_id and key your ledger on it, so a retry or a repeated webhook cannot credit a customer twice.

Log carefully

Log the endpoint, status code and response time. Do not log request or response bodies — they contain names, BVNs, phone numbers and account details.

Never surface raw errors to your users

Map failures to your own messages. Passing a provider’s error text straight through leaks implementation detail and confuses customers.

Amounts and currency

NGN

Wallet and transfer amounts are in naira.

USD

Card amounts are in dollars.

Some endpoints accept an amount as a string and return it as a number. Parse defensively, and store money as a fixed-precision type rather than a float.

Get started

Core concepts

API Endpoints

Response format

Success and failure

Transaction statuses

Handling responses well

Amounts and currency

NGN

USD

​Success and failure

​Transaction statuses

​Handling responses well

​Amounts and currency

NGN

USD

Success and failure

Transaction statuses

Handling responses well

Amounts and currency