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

# Dispatch Authorization

> Trigger in-app biometric push notification or generate a dynamic QR code

## Request Body

<ParamField body="reference" type="string" required>
  The unique merchant-generated transaction reference.
</ParamField>

<ParamField body="bankId" type="string" required>
  The `bankId` selected by the customer from `linkedBanks`.
</ParamField>

<ParamField body="authChannel" type="string" required>
  `handle_push` or `handle_qr`.
</ParamField>

<ParamField body="description" type="string">
  Order description displayed on customer's authorization screen.
</ParamField>

<ParamField body="metadata" type="object">
  Custom key-value pairs for internal order tracking.
</ParamField>

## Response

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="reference" type="string">
      Merchant transaction reference.
    </ResponseField>

    <ResponseField name="status" type="string">
      `PENDING_AUTHORIZATION` or `PENDING_SCAN`.
    </ResponseField>

    <ResponseField name="authChannel" type="string">
      `handle_push` or `handle_qr`.
    </ResponseField>

    <ResponseField name="qrCodeUrl" type="string">
      URL of dynamic QR code (if `handle_qr` selected).
    </ResponseField>

    <ResponseField name="expiresAt" type="string">
      ISO-8601 timestamp of prompt expiry.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.handle.ng/v1/charges/dispatch \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "reference": "ORD-1092",
      "bankId": "bnk_gtb_01",
      "authChannel": "handle_push",
      "description": "Nike Air Max at SneakerHub"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Authorization prompt dispatched to customer's phone",
    "data": {
      "reference": "ORD-1092",
      "status": "PENDING_AUTHORIZATION",
      "authChannel": "handle_push",
      "expiresAt": "2026-09-21T08:30:00Z"
    }
  }
  ```
</ResponseExample>