# Integration Reference

#### HTTP Headers

Every webhook request includes the following headers for authentication and tracking:

{% code expandable="true" %}

```http
POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Paymento-Signature: 9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b
X-Paymento-Timestamp: 1699564800
X-Paymento-Event-Id: evt_a1b2c3d4e5f6g7h8i9j0
X-Paymento-Event-Type: payment_link.paid
```

{% endcode %}

#### **Header Descriptions**

| Header Name             | Type      | Description                                            |
| ----------------------- | --------- | ------------------------------------------------------ |
| `X-Paymento-Signature`  | `string`  | HMAC-SHA256 signature of the request body (hex string) |
| `X-Paymento-Timestamp`  | `integer` | Unix timestamp when the webhook was sent               |
| `X-Paymento-Event-Id`   | `string`  | Unique identifier for this webhook event               |
| `X-Paymento-Event-Type` | `string`  | Type of event (see Event Types section)                |

#### Request Body

The webhook request body is a JSON object with the following structure:

{% code expandable="true" %}

```json
{
  "event": {
    "id": "evt_a1b2c3d4e5f6g7h8i9j0",
    "type": "payment_link.paid",
    "createdAt": "2024-11-09T14:30:00Z",
    "apiVersion": "v1"
  },
  "paymentLink": {
    "id": "pl_9z8y7x6w5v4u3t2s1r0q",
    "title": "Monthly Subscription",
    "description": "Premium Plan - November 2024",
    "status": "paid",
    "type": "scheduled",
    "createdAt": "2024-10-01T10:00:00Z",
    "paidAt": "2024-11-09T14:30:00Z",
    "url": "https://app.paymento.com/pl_9z8y7x6w5v4u3t2s1r0q"
  },
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe",
    "metadata": {
      "order_id": "12345",
      "payment_id": "pay_abcdefghijk"
    }
  },
  "merchant": {
    "id": "mrc_xyz123",
    "name": "Your Store Name"
  }
}
```

{% endcode %}

#### **Object Descriptions**

**`event` Object**

| Field        | Type     | Description                                        |
| ------------ | -------- | -------------------------------------------------- |
| `id`         | `string` | Unique identifier for this event (format: `evt_*`) |
| `type`       | `string` | Event type (see Event Types)                       |
| `createdAt`  | `string` | ISO 8601 timestamp when the event was created      |
| `apiVersion` | `string` | Paymento API version used                          |

**`paymentLink` Object**

| Field                 | Type      | Description                                                                      |
| --------------------- | --------- | -------------------------------------------------------------------------------- |
| `id`                  | `string`  | Unique payment link identifier                                                   |
| `title`               | `string`  | Payment link title                                                               |
| `description`         | `string`  | Payment link description                                                         |
| `status`              | `string`  | Current status: `"paid"`, `"deferred"`, or `"scheduled"`                         |
| `type`                | `string`  | Payment type: `"one_time"` or `"scheduled"`                                      |
| `createdAt`           | `string`  | ISO 8601 timestamp when payment link was created                                 |
| `paidAt`              | `string?` | ISO 8601 timestamp when payment was completed (null if not paid)                 |
| `url`                 | `string`  | Public URL of the payment link                                                   |
| `integrationMetadata` | `object`  | Integration metadata for external platforms (Telegram, Discord, etc.) - optional |

**`customer` Object**

| Field                        | Type      | Description                                                  |
| ---------------------------- | --------- | ------------------------------------------------------------ |
| `email`                      | `string`  | Customer email address                                       |
| `name`                       | `string`  | Customer name                                                |
| `metadata`                   | `object`  | Additional customer metadata (optional)                      |
| `metadata.order_id`          | `string?` | Order ID if available                                        |
| `metadata.payment_id`        | `string?` | Payment transaction ID if available                          |
| `metadata.scheduled_token`   | `string?` | Scheduled payment token (for reminder/deferred events)       |
| `metadata.payment_link_url`  | `string?` | Payment link URL (for reminder events)                       |
| `metadata.due_date`          | `string?` | Due date in YYYY-MM-DD format (for scheduled payments)       |
| `metadata.grace_date`        | `string?` | Grace period end date in YYYY-MM-DD format (if applicable)   |
| `metadata.telegram_username` | `string?` | Customer's Telegram username (if available)                  |
| `metadata.telegram_user_id`  | `string?` | Customer's Telegram user ID (only for Telegram integrations) |

**`merchant` Object**

| Field  | Type     | Description            |
| ------ | -------- | ---------------------- |
| `id`   | `string` | Your merchant/store ID |
| `name` | `string` | Your store name        |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paymento.io/payment-links/webhooks-for-payment-links/integration-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.