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

# Disbursement Authorization Mode

> Configure secure authorization for disbursement requests using PIN mode or Authorization URL mode.

# Disbursement Authorization Mode

Payfonte supports two authorization modes for disbursement requests:

* PIN Authorization
* Authorization URL

## Mode Comparison

| Mode              | How it works                                                                                 | Recommended for                                                    |
| ----------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| PIN Authorization | You send `pin` in each disbursement request                                                  | Teams with strict backend-controlled disbursement flows            |
| Authorization URL | Payfonte calls your approval endpoint per request; disbursement continues only on HTTP `200` | Platforms that require policy/risk checks before each disbursement |

## 1) PIN Authorization

PIN mode requires a disbursement PIN on disbursement requests.

### Setup

<Steps>
  <Step title="Set PIN in dashboard">
    Open any Disbursements page in dashboard and complete PIN setup when prompted.
  </Step>

  <Step title="Store PIN securely">
    Keep PIN in backend secret storage only. Never expose in frontend/mobile clients.
  </Step>

  <Step title="Send PIN per disbursement request">
    Include `pin` field in `POST /billing/v1/disbursements`.
  </Step>
</Steps>

PIN request example:

```json theme={null}
{
  "transferRecipientId": "6659692f019f6a143f7f90db",
  "amount": 100000,
  "reference": "disbursement-1001",
  "narration": "Vendor settlement",
  "pin": "1234"
}
```

## 2) Authorization URL

Authorization URL mode lets your system approve or reject each disbursement attempt dynamically.

### Setup

<Steps>
  <Step title="Configure authorization URL">
    Set your endpoint under `Disbursements -> Settings` in dashboard.
  </Step>

  <Step title="Implement request validation">
    Validate incoming request authenticity (hash/signature verification) before responding.
  </Step>

  <Step title="Return strict decision">
    Return HTTP `200` to approve; non-`200` to block the disbursement.
  </Step>
</Steps>

<Warning>
  Authorization URL mode is strict: if your endpoint is unavailable or returns non-`200`, the disbursement is not processed.
</Warning>

### Authorization Request Payload

When Authorization URL mode is enabled, Payfonte sends a JSON payload like this to your configured authorization URL:

```json theme={null}
{
  "clientId": "client_123456789",
  "type": "disbursement",
  "externalReference": "EXT-DISB-000001",
  "reference": "DISB-000001",
  "provider": "paystack",
  "channel": "bank-transfer",
  "finalAmount": 500000,
  "amount": 500000,
  "transferRecipientLabel": "Paystack | Zenith Bank | Ada Lovelace | 0123456789",
  "transferRecipient": {
    "accountNumber": "0123456789",
    "bankCode": "057",
    "bankName": "Zenith Bank",
    "accountName": "Ada Lovelace"
  },
  "recipient": {
    "accountNumber": "0123456789",
    "bankCode": "057",
    "bankName": "Zenith Bank",
    "accountName": "Ada Lovelace"
  },
  "transferRecipientId": "trf_recipient_123456789",
  "charge": 15000,
  "chargesApplied": [],
  "fees": {},
  "status": "queued",
  "country": "NG",
  "currency": "NGN",
  "narration": "Vendor payout for invoice INV-2026-0001",
  "webhookURL": "https://example.com/webhooks/disbursements"
}
```

## Recommended Validation Checks (Authorization URL)

When Payfonte calls your authorization URL, validate:

* Request authenticity (signature/hash verification)
* Amount and currency match expected business rules
* Recipient is eligible for disbursement
* Sender/account has enough balance (if you enforce internal wallet rules)
* Daily limits, AML/risk policies, and velocity thresholds

## Security Checklist

<AccordionGroup>
  <Accordion title="Keep secrets server-side" icon="lock" defaultOpen>
    Never expose disbursement PIN or authorization secrets in browser/mobile code.
  </Accordion>

  <Accordion title="Use HTTPS endpoints" icon="shield-halved">
    Authorization URL must be publicly reachable over HTTPS.
  </Accordion>

  <Accordion title="Fail closed on verification errors" icon="triangle-exclamation">
    If signature/hash checks fail, reject the authorization request.
  </Accordion>

  <Accordion title="Audit every disbursement decision" icon="database">
    Log both approved and rejected decisions with reasons for compliance and troubleshooting.
  </Accordion>
</AccordionGroup>

## Related Docs

<CardGroup cols={3}>
  <Card title="Disbursements Overview" icon="money-bill-transfer" href="/en/guides/disbursements/overview">
    End-to-end disbursement flow and endpoint usage.
  </Card>

  <Card title="Disbursement Webhooks" icon="bell" href="/en/guides/disbursements/webhook">
    Handle asynchronous disbursement status updates.
  </Card>

  <Card title="Disbursement Examples" icon="code" href="/en/guides/disbursements/examples">
    Copy-ready request and response payloads.
  </Card>
</CardGroup>