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

# Quickstart

> Create a sandbox key, quote a rate, send a payout and receive the webhook.

This walk-through uses the sandbox. No real money moves.

**1. Create a sandbox key**

Sign in to the [dashboard](https://app.payvehq.com) and switch the environment toggle to **Sandbox**. Open **Settings → API keys**, select **Create API key**, give it a name and tick the `payouts:write` scope.

Copy the key when it appears. It starts with `sk_test_`.

> [!WARNING]
>
> The key is shown once. Payve stores only a hash of it and cannot show it again. If you lose it, revoke it and create a new one.

Put the key and the sandbox base URL in your environment. [Environments](/get-started/environments.md) explains the two base URLs.

```bash
export PAYVE_API_URL="https://sandbox.api.payvehq.com"
export PAYVE_API_KEY="sk_test_..."
```

**2. Add a webhook endpoint**

In **Settings → Webhooks**, add the HTTPS URL of your server and choose **All events**. Copy the signing secret. It starts with `whsec_` and is also shown once.

Your server must answer with a `2xx` status. [Verify signatures](/webhooks/verify-signatures.md) has working code.

**3. Quote the payout**

A quote tells you the rate, the fee and what the recipient gets. It holds for five minutes by default.

```bash cURL
curl -X POST "$PAYVE_API_URL/v1/quotes" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCurrency": "NGN",
    "destinationCurrency": "GHS",
    "amount": 5000000
  }'
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/quotes`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAYVE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sourceCurrency: 'NGN',
    destinationCurrency: 'GHS',
    amount: 5000000,
  }),
});
const { data: quote } = await res.json();
```

```python Python
import os, requests

res = requests.post(
    f"{os.environ['PAYVE_API_URL']}/v1/quotes",
    headers={"x-api-key": os.environ["PAYVE_API_KEY"]},
    json={
        "sourceCurrency": "NGN",
        "destinationCurrency": "GHS",
        "amount": 5000000,
    },
)
quote = res.json()["data"]
```

```json Response · 201
{
  "data": {
    "id": "qte_4b1f0c9d2e7a6835",
    "sourceCurrency": "NGN",
    "sourceAmount": "5000000",
    "destinationCurrency": "GHS",
    "destinationAmount": "46500",
    "rate": "0.0093",
    "fee": { "amount": "25000", "currency": "NGN" },
    "expiresAt": "2026-11-18T10:05:00.000Z",
    "createdAt": "2026-11-18T10:00:00.000Z"
  }
}
```

**4. Send the payout**

Send the same currencies and amount, plus the `quoteId`. Generate one `Idempotency-Key` for this payout and keep it. If the request times out, send it again with the same key.

```bash cURL
curl -X POST "$PAYVE_API_URL/v1/payouts" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Idempotency-Key: 7f3d2b1a-0c4e-4f8a-9b6d-5e2a1c3f4b70" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCurrency": "NGN",
    "destinationCurrency": "GHS",
    "amount": 5000000,
    "method": "bank_transfer",
    "quoteId": "qte_4b1f0c9d2e7a6835",
    "merchantReference": "invoice-1042",
    "narration": "Invoice 1042",
    "beneficiary": {
      "type": "bank_account",
      "accountNumber": "0123456789",
      "bankCode": "<a bankCode from /v1/payouts/institutions>",
      "holderName": "Ama Asante",
      "country": "GH"
    }
  }'
```

```javascript Node
import { randomUUID } from 'node:crypto';

const idempotencyKey = randomUUID(); // store this with your order

const res = await fetch(`${process.env.PAYVE_API_URL}/v1/payouts`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAYVE_API_KEY,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sourceCurrency: 'NGN',
    destinationCurrency: 'GHS',
    amount: 5000000,
    method: 'bank_transfer',
    quoteId: quote.id,
    merchantReference: 'invoice-1042',
    narration: 'Invoice 1042',
    beneficiary: {
      type: 'bank_account',
      accountNumber: '0123456789',
      bankCode: bankCode, // from GET /v1/payouts/institutions?country=GH&type=bank
      holderName: 'Ama Asante',
      country: 'GH',
    },
  }),
});
const { data: payout } = await res.json();
```

```python Python
import os, uuid, requests

idempotency_key = str(uuid.uuid4())  # store this with your order

res = requests.post(
    f"{os.environ['PAYVE_API_URL']}/v1/payouts",
    headers={
        "x-api-key": os.environ["PAYVE_API_KEY"],
        "Idempotency-Key": idempotency_key,
    },
    json={
        "sourceCurrency": "NGN",
        "destinationCurrency": "GHS",
        "amount": 5000000,
        "method": "bank_transfer",
        "quoteId": quote["id"],
        "merchantReference": "invoice-1042",
        "narration": "Invoice 1042",
        "beneficiary": {
            "type": "bank_account",
            "accountNumber": "0123456789",
            "bankCode": bank_code,  # from GET /v1/payouts/institutions?country=GH&type=bank
            "holderName": "Ama Asante",
            "country": "GH",
        },
    },
)
payout = res.json()["data"]
```

```json Response · 202
{
  "data": {
    "id": 1842,
    "publicId": "pyt_9c2e41b7a05d3f68",
    "status": "pending",
    "subStatus": null,
    "sourceCurrency": "NGN",
    "destinationCurrency": "GHS",
    "sourceAmount": "5000000",
    "destinationAmount": "46500",
    "feeAmount": "25000",
    "feeCurrency": "NGN",
    "merchantReference": "invoice-1042",
    "quoteId": "qte_4b1f0c9d2e7a6835",
    "createdAt": "2026-11-18T10:00:12.000Z"
  }
}
```

`202` means Payve accepted the payout. It has not arrived yet.

> [!NOTE]
>
> Your sandbox wallet needs a balance first. Fund it from the dashboard's payment simulator. See [Test in the sandbox](/testing/sandbox.md).

**5. Receive the webhook**

When the payout finishes, Payve posts `payout.successful` or `payout.failed` to your endpoint. In the sandbox this takes about five seconds.

```json
{
  "id": "evt_5d0a7c3e9b1f42866e0d1a2b3c4d5e6f",
  "type": "payout.successful",
  "merchantId": "318",
  "data": {
    "id": "1842",
    "public_id": "pyt_9c2e41b7a05d3f68",
    "kind": "payout",
    "status": "successful",
    "source_currency": "NGN",
    "source_amount": "5000000",
    "destination_currency": "GHS",
    "destination_amount": "46500",
    "merchant_reference": "invoice-1042"
  },
  "createdAt": "2026-11-18T10:00:17.000Z"
}
```

Verify the signature, record the event `id` so you process it once, and answer `200`. [Webhook event object](/webhooks/event-samples.md) shows every event in full.

## Next

> [card] [Idempotency](/essentials/idempotency.md)
>
> The rules that stop a retry paying twice.

> [card] [Going live](/get-started/going-live.md)
>
> What changes when you move from sandbox to live.
