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

# Quickstart

> Process your first payment in under 5 minutes

# 5-Minute Quickstart Guide

This guide walks you through integrating **Pay with Handle** using our Headless REST API.

## Step 1: Obtain Your API Keys

1. Log in to the [Handle Merchant Dashboard](https://admin.handle.ng/developers).
2. Copy your **Secret Key** (`sk_test_...` for development, `sk_live_...` for production).

<Warning>
  Never expose your Secret Key (`sk_live_...` or `sk_test_...`) in client-side code (browsers, mobile apps). Always make API calls from your secure backend server.
</Warning>

***

## Step 2: Resolve Customer Handle

When the customer enters `@ayodeji` at checkout, make a request from your backend to resolve their profile:

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

  ```javascript Node.js theme={null}
  const response = 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, // ₦15,000 in Kobo
      reference: 'ORD-1092',
    }),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests
  import os

  url = "https://api.handle.ng/v1/charges/resolve-handle"
  headers = {
      "Authorization": f"Bearer {os.getenv('HANDLE_SECRET_KEY')}",
      "Content-Type": "application/json"
  }
  payload = {
      "handle": "ayodeji",
      "amount": 1500000,
      "reference": "ORD-1092"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

***

## Step 3: Dispatch Payment Authorization

Display the customer's linked active banks and dispatch the push prompt:

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

  ```javascript Node.js theme={null}
  const dispatchRes = await fetch('https://api.handle.ng/v1/charges/dispatch', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HANDLE_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      reference: 'ORD-1092',
      bankId: 'bnk_gtb_01',
      authChannel: 'handle_push',
      description: 'Nike Air Max at SneakerHub',
    }),
  });

  const result = await dispatchRes.json();
  ```
</CodeGroup>

***

## Step 4: Listen for Webhooks

Configure your server endpoint to receive real-time payment confirmations:

```javascript Express.js (Node.js) theme={null}
app.post('/handle/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-handle-signature'];
  // Verify HMAC-SHA512 signature
  const event = JSON.parse(req.body);

  if (event.event === 'charge.success') {
    const { reference, amount, customer } = event.data;
    console.log(`✅ Order ${reference} for ₦${amount / 100} paid by ${customer.handle}`);
    // Fulfill customer order
  }

  res.status(200).send({ received: true });
});
```