> For the complete documentation index, see [llms.txt](https://roqqu-api-services.gitbook.io/ras/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://roqqu-api-services.gitbook.io/ras/webhooks/payment-link-webhook-events.md).

# Payment Link Webhook Events

When a payment link transaction is processed, you will receive webhook notifications at your configured webhook URL. The webhook payload contains detailed information about the payment status, transaction details, and customer information.

### Webhook Event Types <a href="#webhook-event-types" id="webhook-event-types"></a>

1. **payment\_link\_completed** - Triggered when payment is successfully completed with exact amount
2. **payment\_link\_completed\_overpaid** - Triggered when payment is completed but customer paid more than required
3. **payment\_link\_failed** - Triggered when payment fails or customer underpaid

### Webhook Payload Structure <a href="#webhook-payload-structure" id="webhook-payload-structure"></a>

All webhook events follow the same structure with different `event_type` and `meta_data` fields. The webhook body is encrypted and must be decrypted using your API key. See the "Decrypt Webhook Body" section for decryption instructions.

### Webhook Payload Fields <a href="#webhook-payload-fields" id="webhook-payload-fields"></a>

* `event_id`: Unique identifier for this webhook event
* `event_type`: Type of event (payment\_link\_completed, payment\_link\_completed\_overpaid, payment\_link\_failed)
* `meta_data`: Object containing payment details
  * `payment_link_refid`: Unique reference ID of the payment link
  * `payment_reference`: Your payment reference
  * `amount_required`: Required payment amount
  * `amount_currency`: Currency code (e.g., 'ngn')
  * `amount_received`: Amount received in token value
  * `amount_received_usd`: Amount received in USD equivalent
  * `overpaid_amount`: Overpaid amount in token value (0 if not overpaid)
  * `overpaid_amount_usd`: Overpaid amount in USD (0 if not overpaid)
  * `underpaid_amount`: Underpaid amount in token value (0 if not underpaid)
  * `underpaid_amount_usd`: Underpaid amount in USD (0 if not underpaid)
  * `token`: Token symbol (BTC or USDT)
  * `value`: Transaction value as string
  * `hash`: Blockchain transaction hash
  * `status`: Payment status ('completed' or 'failed')
  * `customer`: Customer details object
  * `address`: Wallet address that received the payment
  * `network`: Blockchain network (bitcoin, trc20, bep20)
  * `metadata`: Your custom metadata (if provided)
* `datetime`: ISO 8601 timestamp of when the event occurred

### Sample Webhook Payloads <a href="#sample-webhook-payloads" id="sample-webhook-payloads"></a>

#### payment\_link\_completed (Success State) <a href="#payment_link_completed-success-state" id="payment_link_completed-success-state"></a>

```
{
  "event_id": "evt_1234567890",
  "event_type": "payment_link_completed",
  "meta_data": {
    "payment_link_refid": "abc123def456ghi789",
    "payment_reference": "ORDER123ABC",
    "amount_required": 1000,
    "amount_currency": "ngn",
    "amount_received": "0.0001",
    "amount_received_usd": 1000,
    "overpaid_amount": "0",
    "overpaid_amount_usd": 0,
    "underpaid_amount": "0",
    "underpaid_amount_usd": 0,
    "token": "BTC",
    "value": "0.0001",
    "hash": "abc123...",
    "status": "completed",
    "customer": {
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "network": "bitcoin",
    "metadata": {}
  },
  "datetime": "2024-01-01T12:00:00Z"
}

```

#### payment\_link\_completed\_overpaid (Overpaid State) <a href="#payment_link_completed_overpaid-overpaid-state" id="payment_link_completed_overpaid-overpaid-state"></a>

```
{
  "event_id": "evt_1234567891",
  "event_type": "payment_link_completed_overpaid",
  "meta_data": {
    "payment_link_refid": "abc123def456ghi789",
    "payment_reference": "ORDER123ABC",
    "amount_required": 1000,
    "amount_currency": "ngn",
    "amount_received": "0.00015",
    "amount_received_usd": 1500,
    "overpaid_amount": "0.00005",
    "overpaid_amount_usd": 500,
    "underpaid_amount": "0",
    "underpaid_amount_usd": 0,
    "token": "BTC",
    "value": "0.00015",
    "hash": "abc123...",
    "status": "completed",
    "customer": {
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "network": "bitcoin",
    "metadata": {}
  },
  "datetime": "2024-01-01T12:00:00Z"
}
```

#### payment\_link\_failed (Failed/Underpaid State) <a href="#payment_link_failed-failedunderpaid-state" id="payment_link_failed-failedunderpaid-state"></a>

```
{
  "event_id": "evt_1234567892",
  "event_type": "payment_link_failed",
  "meta_data": {
    "payment_link_refid": "abc123def456ghi789",
    "payment_reference": "ORDER123ABC",
    "amount_required": 1000,
    "amount_currency": "ngn",
    "amount_received": "0.00005",
    "amount_received_usd": 500,
    "overpaid_amount": "0",
    "overpaid_amount_usd": 0,
    "underpaid_amount": "0.00005",
    "underpaid_amount_usd": 500,
    "token": "BTC",
    "value": "0.00005",
    "hash": "abc123...",
    "status": "failed",
    "customer": {
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "network": "bitcoin",
    "metadata": {}
  },
  "datetime": "2024-01-01T12:00:00Z"
}
```

### Important Notes <a href="#important-notes" id="important-notes"></a>

* Webhooks are sent asynchronously and may have delays
* Always verify the webhook signature/decryption before processing
* For overpaid transactions, you can request a refund for the overpaid amount
* For failed/underpaid transactions, the received amount is refund-eligible