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

# Resolve Handle

> Look up customer by @handle and retrieve active mandate banks

## Request Body

<ParamField body="handle" type="string" required>
  The customer's Handle (e.g. `ayodeji` or `@ayodeji`) or registered phone number.
</ParamField>

<ParamField body="amount" type="integer" required>
  The charge amount in **Kobo** (e.g. `1500000` = ₦15,000).
</ParamField>

<ParamField body="reference" type="string" required>
  A unique merchant-generated order reference to prevent duplicate billing.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Returns `success` or `error`.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="customer" type="object">
      Contains customer `handle`, `name`, and `avatarUrl`.
    </ResponseField>

    <ResponseField name="availableAuthChannels" type="array">
      List of supported auth channels (`handle_push`, `handle_qr`).
    </ResponseField>

    <ResponseField name="linkedBanks" type="array">
      List of bank accounts with `mandateStatus: 'ACTIVE'`.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.handle.ng/v1/charges/resolve-handle \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "handle": "ayodeji",
      "amount": 1500000,
      "reference": "ORD-1092"
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.handle.ng/v1/charges/resolve-handle', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HANDLE_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      handle: 'ayodeji',
      amount: 1500000,
      reference: 'ORD-1092',
    }),
  });
  const data = await res.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Handle resolved successfully",
    "data": {
      "customer": {
        "handle": "@ayodeji",
        "name": "Ayodeji P.",
        "avatarUrl": "https://cdn.handle.ng/avatars/ayodeji.png"
      },
      "availableAuthChannels": [
        { "id": "handle_push", "name": "Handle App Push Notification", "isRecommended": true },
        { "id": "handle_qr", "name": "Scan Dynamic QR Code" }
      ],
      "linkedBanks": [
        {
          "bankId": "bnk_gtb_01",
          "bankName": "Guaranty Trust Bank",
          "bankCode": "058",
          "accountNumberMasked": "******4819",
          "mandateStatus": "ACTIVE"
        }
      ]
    }
  }
  ```
</ResponseExample>