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

# Quickstart

> Create a wallet, check its balance and send your first transfer — four calls against the Pila sandbox.

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](/dashboard-guide/getting-started/create-an-app) if you have not made one yet.

Keep them out of your source code:

```bash theme={null}
export PILA_APP_ID="<your_app_id>"
export PILA_SECRET_KEY="<your_sandbox_secret_key>"
export PILA_BASE_URL="https://sandbox.trypila.co"
```

<Steps>
  <Step title="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.

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

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

    Full parameter list: [Create a wallet](/api-reference/wallets/create-wallet).
  </Step>

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

    ```bash theme={null}
    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](/api-reference/core-concepts/webhook-signatures).
  </Step>

  <Step title="Check the balance">
    Read the wallet back to confirm it was funded.

    ```bash theme={null}
    curl "$PILA_BASE_URL/api/v1/wallet/ngn/retrieve?wallet_id=$WALLET_ID" \
      -H "Authorization: $PILA_SECRET_KEY" \
      -H "AppId: $PILA_APP_ID"
    ```

    ```json theme={null}
    {
      "entity": {
        "wallet_id": "254a14e1-25ac-338a-94ed-9e4041840599",
        "wallet_amount": 1172,
        "account_number": "1004656370",
        "phone_number": "09032652195",
        "bank_name": "VFD MFB"
      }
    }
    ```
  </Step>

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

    ```bash theme={null}
    # 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](/api-reference/wallets/transaction-details) with the returned `transaction_id`.

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

## Going live

<Steps>
  <Step title="Get your account verified">
    Complete your company information and request verification from **Settings**. See [Create an app](/dashboard-guide/getting-started/create-an-app#getting-verified).
  </Step>

  <Step title="Fund your Pila wallet">
    Live payouts settle from your funded balance. See [Fund your wallet](/dashboard-guide/getting-started/fund-your-wallet).
  </Step>

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

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

## Where to next

<CardGroup cols={2}>
  <Card title="Issue a virtual USD card" icon="credit-card" href="/api-reference/cards/create-virtual-card">
    Add dollar spend on top of the NGN wallet you just created.
  </Card>

  <Card title="Browse every task" icon="compass" href="/get-started">
    Search the docs by what you are trying to do.
  </Card>
</CardGroup>


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