Integration Reference

HTTP Headers

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

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

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:

{
  "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": "[email protected]",
    "name": "John Doe",
    "metadata": {
      "order_id": "12345",
      "payment_id": "pay_abcdefghijk"
    }
  },
  "merchant": {
    "id": "mrc_xyz123",
    "name": "Your Store Name"
  }
}

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