> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.trypila.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Response format

> Every Pila endpoint returns its payload inside an entity key. Here is how to read it and how to tell success from failure.

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

```json theme={null}
{
  "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.

<Tabs>
  <Tab title="Object">
    Most endpoints return a single record.

    ```json theme={null}
    {
      "entity": {
        "transaction_id": "Pila-6bddb725-2ca9-31c0-b0fb-13f7f11adf90",
        "transaction_status": "PROCESSING",
        "transaction_amount": 5000,
        "transaction_type": "transfer"
      }
    }
    ```
  </Tab>

  <Tab title="Array">
    List endpoints — banks, transactions, states — return an array.

    ```json theme={null}
    {
      "entity": [
        { "name": "Access Bank", "code": "044" },
        { "name": "Citibank Nigeria", "code": "023" }
      ]
    }
    ```
  </Tab>

  <Tab title="Scalar">
    A few endpoints return a plain value or a short confirmation.

    ```json theme={null}
    {
      "entity": "Card blocked successfully"
    }
    ```
  </Tab>
</Tabs>

<Info>
  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.
</Info>

## 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 |

<Warning>
  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](#transaction-statuses) below.
</Warning>

## 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](/api-reference/webhooks/subscribe), or poll [Transaction details](/api-reference/wallets/transaction-details) with the `transaction_id` you received. Do not assume a `PROCESSING` transfer succeeded.

## Handling responses well

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Amounts and currency

<Columns cols={2}>
  <Card title="NGN" icon="naira-sign">
    Wallet and transfer amounts are in naira.
  </Card>

  <Card title="USD" icon="dollar-sign">
    Card amounts are in dollars.
  </Card>
</Columns>

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.