Payment Notifications
What this product does
Payment Notification Links allow you to request a payment from a customer by creating a secure, EveryPay-hosted payment page and sharing it with them.
This guide explains how to integrate Payment Notification Links using the EveryPay API. It focuses on how the feature works, what choices you have, and how to handle real-world scenarios.
For endpoint definitions, request parameters, and error codes, see the API Reference.
Core concepts
A Payment Notification represents a single payment request.
When you create a notification:
- EveryPay generates a hosted payment page
- The page is associated with a unique notification token
- The customer completes payment using that page
Your system is responsible for:
- Creating the notification
- Distributing the link (or letting EveryPay do it)
- Tracking the result
- Reconciling the payment
End-to-end flow
At a high level, the integration follows this flow:
- You create a payment notification via the API
- The payment link is delivered to the customer
- The customer completes payment on an EveryPay-hosted page
- You track the outcome via API queries or webhooks
This flow is asynchronous by design.
Integration choices
Creating a payment notification
You create a Payment Notification Link using the Notifications API.
When creating a notification, you define:
- who is paying (customer details)
- what is being paid (amount, description)
- how the link is delivered
- optional payment constraints (expiration, installments)
Choosing how the link is delivered
When creating a notification, you choose how the customer receives the payment link.
EveryPay sends the email
In this model:
- EveryPay emails the customer automatically
- The email contains a payment button linking to the hosted page
You distribute the payment link
In this model:
- You disable email delivery (
skip_notify=1) - You distribute the link yourself (email, SMS, chat, invoice, CRM)
Installments and max_installments
If your merchant account supports installments, you can optionally control installment availability per notification.
- Use the
max_installmentsfield when creating a notification - This limits the maximum number of installments the customer can select
- If not provided, the default installment configuration of your account applies
Customer-facing experience
When the customer opens the payment link:
- They are redirected to a secure, EveryPay-hosted payment page
- The page automatically reflects your account configuration
- Only payment methods enabled on your account are shown
(for example cards, Apple Pay, Google Pay, IRIS) - The page language follows the notification locale
No checkout integration or card handling is required on your side.
State, lifecycle, and timing
Each payment notification follows a simple lifecycle:
| Status | Description |
|---|---|
| pending | The notification has been created and is awaiting customer action. |
| paid | The customer completed payment. |
| expired | The notification expired before payment was completed. |
| canceled | The payment notification was canceled. |
Status transitions are asynchronous and should be handled via webhooks or API polling.
Observability and reconciliation
You can track the status of a payment notification using webhooks or by querying the API.
Tracking payment status
You can track notification status in two ways:
Webhooks (recommended)
EveryPay can send webhook events when a payment notification status changes, including:
- when a notification becomes
paid - when a notification becomes
expired(only if an expiration date is set)
Use these events to update your internal invoice/order state and drive reconciliation.
See the Webhooks for event names and payload details.
API queries
You can fetch a payment notification using its token to check the current status.
Webhooks should be your primary mechanism for updating internal state.
Metadata and reconciliation
You can attach a metadata object to each payment notification.
Use metadata to store internal references such as:
- invoice ID
- order ID
- customer reference
- reconciliation keys
When the payment is completed:
- The Payment object includes the associated payment notification token
- The Successful Payment webhook includes:
- the notification token
- the metadata from the payment notification
This allows you to reconcile payments without additional API calls.
Best practice:
Always include a stable internal identifier in metadata.
Failure modes and recovery
Error handling
This section complements the API Reference error codes by explaining how your integration should react to common Payment Notification errors.
| Error code | Meaning | Recommended action |
|---|---|---|
| 40002 | Invalid amount (minimum 1 cent) | Ensure amount is a positive integer in cents before calling the API. |
| 40008 | Description empty, too long (max 200 chars), or not UTF-8 | Validate description client-side: non-empty, UTF-8, max 200 characters. |
| 40021 | Invalid email | Validate email format before creating the notification. |
| 40022 | Invalid phone | Validate phone format before creating the notification. |
| 40044 | Invalid payee name | Ensure the name contains valid characters only. |
| 40045 | Missing or invalid locale | Send locale as el or en, or omit it to use the default. |
| 40046 | Invalid expiration date | Ensure the expiration date is a valid ISO 8601 datetime. |
| 40047 | Expiration time lower than 5 minutes | Set expiration_date at least 5 minutes after creation. |
| 40048 | Notification not found | Verify the notification token and environment. |
| 40032 | Notification already paid | Treat as completed. Do not resend or cancel. |
| 40094 | Notification expired | Create a new notification and send a new link. |
| 40096 | Notification not in pending status or expired | Fetch status; reconcile if paid, recreate if expired. |
Where to go next
- Review the API Reference for endpoint and parameter details
- Configure and test webhooks
- Test the full flow in a non-production environment