Paymend API documentation

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.

Event	Description	Payment status
PAYMENT_CREATED	The payment has been created but not yet processed.	`PENDING`
PAYMENT_AUTHORIZED	The 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_CAPTURED	The payment has been successfully captured. Funds have been debited from the consumer’s account.	`CAPTURED`
PAYMENT_REFUNDED	The payment has been successfully refunded. Previously captured funds have been returned to the consumer’s account.	`REFUNDED`
PAYMENT_VOIDED	The payment has been successfully voided. Previously authorized funds have been unfrozen and are available to the consumer again.	`VOIDED`
PAYMENT_FAILED	The 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:

Field	Type	Description
`eventId`	`string`	Webhook event unique id. Any events with an id that was already received can be considered a duplicate.
`eventType`	`string`	The type of webhook event
`createdAt`	`string`	Timestamp when the webhook was created
`data`	`object`	Object containing the PaymentResponse

Example PAYMENT_CREATED webhook:

{
    "eventId": "EVNT_1234567890abcdef",
    "eventType": "PAYMENT_CREATED",
    "version": "1.0",
    "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:

Field	Type	Description
`eventId`	`string`	Webhook event unique id. Any events with an id that was already received can be considered a duplicate.
`eventType`	`string`	The type of webhook event
`createdAt`	`string`	Timestamp when the webhook was created
`data`	`object`	Object containing basic payment information

Example PAYMENT_AUTHORIZED webhook:

{
    "eventId": "EVNT_1234567890abcdef",
    "event": "PAYMENT_AUTHORIZED",
    "version": "1.0",
    "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"
        }
    }
}

​Webhook events

​How to use webhooks with Paymend

​Endpoint requirements

​Responding to webhooks

​Retrying webhooks

​Verifying webhooks

​Webhook payload

​Payment creation

​Payment status update