Skip to main content

Pay-by-Link

IXOPAY's Pay-by-Link feature empowers you to create a secure URL for your customers to access a payment page. The payment page can be customized to ensure a seamless and branded payment experience. This document provides a comprehensive guide to using the Pay-by-Link feature.

Guide

For a detailed, step-by-step guide on integrating Pay-by-Link, refer to the Pay-by-Link guide in our guides section.

To create a Pay-by-Link, simply create a transaction request as you typically would, while adding the additional parameter payByLink and specifying whether the link should be sent via email with the sendByEmail flag.

Important: The sendByEmail field must be explicitly set to true or false. If this field is omitted, no Pay-by-Link will be created.

Supported transaction types​

A Pay-by-Link can be created using one of the following transaction types at the initial stage:

Email delivery​

Setting sendByEmail to true will automatically send the link to the customer, provided that the email field has been specified for the customer. The email content itself can be customized. For more details, consult the Pay-by-Link article in the User Manual.

Here's an example of a Pay-by-Link request sent via email:

{
  "merchantTransactionId": "your-unique-identifier",
  "amount": "9.99",
  "currency": "EUR",
  "description": "Purchase description shown on credit card statement.",
  "customer": {
    "identification": "616c6578-2e73-6d69-7468-406578616d70",
    "firstName": "Alex",
    "lastName": "Smith",
    "email": "[email protected]"
  },
  "payByLink": {
    "sendByEmail": true
  }
}

Automatic expiration​

Pay-by-Link transactions can be set to expire after a specified number of minutes. For detailed information, see automatic expiration below.

The following fields in the Transaction API response and the callback request body are relevant for Pay-by-Links:

  • redirectUrl (string): This is the Pay-by-Link URL. It provides a direct link to the payment page, which offers a seamless and secure payment experience for customers.
  • payByLinkData.cancelUrl (string): This is the URL used for manual cancellation of a Pay-by-Link. To learn more about canceling Pay-by-Links, refer to Cancellation — Manual cancellation.
  • payByLinkData.sendViaEmail (optional boolean): This field represents the value of sendByEmail set during transaction creation.
  • payByLinkData.expiresAt1 (optional string): This field defines the expiry time using the RFC 3339 Internet Date/Time Format date-time.

Here are examples of a Pay-by-Link response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20241218-d94c0d72f3a36e21f16e",
  "returnType": "REDIRECT",
  "redirectUrl": "https://gateway.ixopay.com/redirect/d94c0d72f3a36e21f16e/ABCDEF01234567890ABCDEF01234567890",
  "paymentMethod": "Creditcard",
  "payByLinkData": {
    "cancelUrl": "https://gateway.ixopay.com/api/v3/payByLink/d94c0d72f3a36e21f16e/cancel"
  }
}

Cancellation​

Pay-by-Links can be cancelled in two ways: automatically through expiration after a specified time period, or manually.

When a transaction is cancelled:

  • The transaction status is updated to cancelled.
  • The Pay-by-Link will redirect to one of the following:
    • cancelUrl if it has been specified.
    • the cancel result template if no URLs have been specified and a result template has been configured.
  • Payments processed directly by IXOPAY platform are prevented if customers have already clicked the link before it was cancelled (customers will be redirected to the cancelUrl or the cancel result page).
  • Payments initiated by customers with a payment service provider (PSP) cannot be prevented in most cases.
Caveats

It's important to note that for technical reasons, cancelling a Pay-by-Link does not guarantee the prevention of customers from completing a transaction in all cases. If a customer was redirected to the PSP's payment page, they could still complete the payment. Depending on your use case, you must have remediation mechanisms in place to prevent double payments.

When using Payment Selection Pages, cancelling the transaction is only possible until the point where the customer has not yet chosen a payment method.

Automatic expiration​

Pay-by-Link transactions can be configured to expire after a specified number of minutes. The basis for the expirationInMinute value is the transaction creation timestamp.

Here's an example of a Pay-by-Link request with automatic expiration:

{
  "merchantTransactionId": "your-unique-identifier",
  "amount": "9.99",
  "currency": "EUR",
  "description": "Purchase description shown on credit card statement.",
  "customer": {
    "identification": "616c6578-2e73-6d69-7468-406578616d70",
    "firstName": "Alex",
    "lastName": "Smith",
    "email": "[email protected]"
  },
  "payByLink": {
    "sendByEmail": false,
    "expirationInMinute": 60
  }
}

Manual cancellation​

Every generated Pay-by-Link transaction will include a payByLinkData.cancelUrl in the response. You can use this cancelUrl to manually cancel uncompleted Pay-by-Link transactions.

For information on authenticating requests and understanding the structure of the response body, please consult the Pay-by-Link API documentation.

info

Manual cancellation of Pay-by-Link transactions is possible only if they are in one of the following states:

  • pending
  • await_redirect
  • redirected

It's important to note that cancelling a transaction is an idempotent operation, meaning that attempting to cancel a transaction that has already been cancelled will return a successful response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20241218-d94c0d72f3a36e21f16e",
  "returnType": "REDIRECT",
  "redirectUrl": "https://gateway.ixopay.com/redirect/d94c0d72f3a36e21f16e/ABCDEF01234567890ABCDEF01234567890",
  "paymentMethod": "Creditcard",
  "expiresAt": "2024-12-19 08:48:25 UTC",
  "payByLinkData": {
    "cancelUrl": "https://gateway.ixopay.com/api/v3/payByLink/d94c0d72f3a36e21f16e/cancel",
  }
}

Footnotes​

  1. Please note that there is also a deprecated field called expiresAt with the format YYYY-MM-DD hh:mm:ss T on the Transaction API response. It is recommended to rely on the newer payByLinkData.expiresAt field. ↩

Last updated on