Skip to main content
This feature is under development and will be available soon.
Paymend supports webhooks to notify you about changes in payment status. Webhooks provide a reliable, asynchronous mechanism to receive real-time updates about payments, helping you to automate reconciliation and customer notifications without the need for constant polling. We strongly encourage merchants to use webhooks as the primary method for tracking payment status, as they enable frictionless asynchronous processing. Our platform is designed to schedule retries in case immediate payment recovery is not possible. By enabling webhooks, you will benefit from the full spectrum of recovery options that Paymend offers.

​
Webhook events

Paymend webhooks notify you about payment status changes. Each webhook event includes details about the payment and its current status.
EventDescriptionPayment status
PAYMENT_CREATEDThe payment has been created but not yet processed.PENDING
PAYMENT_AUTHORIZEDThe payment has been successfully authorized, freezing funds in the consumer’s account. A capture request is required to debit the funds from the account.AUTHORIZED
PAYMENT_CAPTUREDThe payment has been successfully captured. Funds have been debited from the consumer’s account.CAPTURED
PAYMENT_REFUNDEDThe payment has been successfully refunded. Previously captured funds have been returned to the consumer’s account.REFUNDED
PAYMENT_VOIDEDThe payment has been successfully voided. Previously authorized funds have been unfrozen and are available to the consumer again.VOIDED
PAYMENT_FAILEDThe payment failed to be authorized. A new payment should be created to reattempt authorization.FAILED

​
How to use webhooks with Paymend

​
Endpoint requirements

In order to receive webhooks from Paymend, you must provide a URL that Paymend can use for the delivery. The URL must use the https scheme, using either TLS 1.3 or 1.2 with a server certificate signed by a well-known certificate authority, which may include a custom path and query parameters. When an event occurs, Paymend will send a POST request to the configured URL.

​
Responding to webhooks

To acknowledge successful delivery of a webhook, you must respond with an HTTP “2xx” success status in less than 500ms. If your system needs more time to process an event, we recommend you store the payload for later access and acknowledge the webhook immediately. You may receive the same webhook event more than once (due to connectivity issues). The eventId field in the payload uniquely identifies each event. If you receive a webhook containing an eventId value that has already been processed, it can be ignored, however, even in this case you should still respond with an HTTP “2xx” success status to prevent further attempts.

​
Retrying webhooks

If Paymend is unable to reach the configured URL, does not receive a response in time, or receives an HTTP “5xx” server error or a “429 Too Many Requests” error, then delivery will be retried. For other HTTP “4xx” client errors, delivery will not be retried. Delivery will be retried shortly after an initial failure. If additional failures occur, then the interval between retries will increase exponentially (up to 1 hour between retries). This is meant to allow receivers more time to recover from potential issues, but can cause webhook delivery to take longer than usual. In any case, delivery will be cancelled if a maximum number of retries is exceeded.

​
Verifying webhooks

Every HTTP request from Paymend will contain an Authorization header using the Bearer authentication scheme. To guarantee that requests you receive are legitimate webhooks from Paymend, you must validate the bearer token and discard any request that does not match your merchant-specific webhook secret.

​
Webhook payload

​
Payment creation

PAYMENT_CREATED webhooks will always have a PENDING status. Each webhook will contain the following fields:
FieldTypeDescription
eventIdstringWebhook event unique id. Any events with an id that was already received can be considered a duplicate.
eventTypestringThe type of webhook event
createdAtstringTimestamp when the webhook was created
dataobjectObject containing the PaymentResponse
Example PAYMENT_CREATED webhook: 
{
    "eventId": "EVNT_1234567890abcdef",
    "eventType": "PAYMENT_CREATED",
    "timestamp": "2026-01-27T12:00:00Z",
 	"data": {
        "paymentId": "pay_1234567890abcdef",
        "merchantReference": "ORDER-12345",
        "amount": 12997,
        "currency": "USD",
        "status": "PENDING",
        "paymentMethod": {
            "type": "CARD",
            "card": {
            "bin": "41111111",
            "holderName": "John Doe",
            "expiryMonth": "12",
            "expiryYear": "2025",
            "last4": "1111",
            "cvvPresentDuringAttempt": true,
            "brand": "VISA"
            }
        },
        "captureNow": true,
        "descriptor": "MyStore Online",
        "goodsType": "MIXED",
        "productItems": [
            {
            "id": "PROD-001",
            "name": "Wireless Keyboard",
            "quantity": 2,
            "unitPrice": 4999,
            "goodsType": "PHYSICAL"
            },
            {
            "id": "PROD-002",
            "name": "E-Book Subscription",
            "quantity": 1,
            "unitPrice": 2999,
            "goodsType": "DIGITAL"
            }
        ],
        "consumer": {
            "firstName": "John",
            "email": "john.doe@example.com",
            "lastName": "Doe",
            "phone": "+1234567890",
            "ip": "192.168.1.1"
        },
        "billing": {
            "address": {
            "street": "123 Main Street",
            "city": "San Francisco",
            "country": "US",
            "state": "CA",
            "zip": "94105"
            }
        },
        "shipping": {
            "address": {
            "street": "123 Main Street",
            "city": "San Francisco",
            "country": "US",
            "state": "CA",
            "zip": "94105"
            },
            "firstName": "Jane",
            "lastName": "Smith"
        },
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T11:00:00Z"
    }
}

​
Payment status update

Webhooks related to changes in payment status will contain the following fields:
FieldTypeDescription
eventIdstringWebhook event unique id. Any events with an id that was already received can be considered a duplicate.
eventTypestringThe type of webhook event
createdAtstringTimestamp when the webhook was created
dataobjectObject containing basic payment information
Example PAYMENT_AUTHORIZED webhook: 
{
    "eventId": "EVNT_1234567890abcdef",
    "event": "PAYMENT_AUTHORIZED",
    "timestamp": "2026-01-27T12:00:00Z",
    "data": {
        "paymentId": "pay_1234567890abcdef",
        "merchantReference": "ORDER-12345",
        "amount": 12997,
        "currency": "USD",
        "status": "AUTHORIZED",
        "captureNow": true,
        "descriptor": "MyStore Online",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T11:00:00Z"
        "links": {
            "capturePayment": "/api/v1/payments/pay_1234567890abcdef/capture",
            "voidPayment": "/api/v1/payments/pay_1234567890abcdef/void",
            "getPayment": "/api/v1/payments/pay_1234567890abcdef"
        }
    }
}