3. Enhancements

3.1 Custom return URL

If a customer successfully completes the payment, they are redirected back to the paylink URL with a message indicating that the payment was successful.

However, if you include a returnUrl variable when initiating the paylink, the customer will be redirected to that URL after a successful payment instead.

{
  "returnUrl": "https://www.domain.com/return/"
}

This allows you to display your own custom confirmation message or thank-you page.

3.2 Apply look and feel

The default paylink URL is displayed in a clean, standard layout. However, you can customize the paylink to match your own branding, for example, by adjusting the colors or adding a background image and logo.

The guide for configuring a custom look and feel for your paylink can be found here.

3.3 Default language

The paylink payment screen is available in more than 20 different languages. You can set the language when initiating a paylink using the customer.locale variable.

{
  "customer": {
    "locale": "en_GB"
  }
}

The customer.locale variable can contain the following values:

3.4 Free variables

When initiating a paylink transaction, you can use the description and reference variables to provide information shown on the customer’s payment screen and bank statement, as well as to store your internal order ID.

If you need to pass additional internal data, you can use free variables. The variable stats.extra1 is available to all merchants, while stats.extra2 and stats.extra3 depend on your package.

{
  "stats": {
    "extra1": "Free variable value 1",
    "extra2": "Free variable value 2",
    "extra3": "Free variable value 3"
  }
}

These free variables are also included in export files and can be used for searching within the Admin Panel. Each free variable can contain up to 64 characters.

3.5 Payment attempts

You can check the status of a paylink using the status.code variable. If you also want to view the individual payment attempts made by the customer, you can retrieve them through the payments variable.

This variable contains an object for each payment attempt, including details such as the payment method, status, and amount. If the payment was successful and authentication was applied through the Order.Status API, the object will also include available customer data (e.g IBAN or masked/hashed credit card number).

In the example below, the customer made two payment attempts.

1. Payment attempt 1 with order ID 68e679c4-4744-8136-21e5-047601470092 was made via Bancontact (payment option ID: 436) with status: CANCEL (-90).
2. Payment attempt 2 with order ID 68e67c08-4744-858c-2f70-047601470092 was made via iDEAL (payment option ID: 10) with status: PAID (100).

{
  "payments": [
    {
      "id": "68e679c4-4744-8136-21e5-047601470092",
      "paymentMethod": {
        "id": 436
      },
      "customerKey": null,
      "customerId": null,
      "customerName": null,
      "customerMethod": null,
      "ipAddress": "100.101.102.103",
      "status": {
        "code": -90,
        "action": "CANCEL"
      },
      "amount": {
        "value": 150,
        "currency": "EUR"
      }
    },
    {
      "id": "68e67c08-4744-858c-2f70-047601470092",
      "paymentMethod": {
        "id": 10
      },
      "customerKey": "1fe2a644d006b4b18ac515be2209490b",
      "customerId": "NL23REVO1264023850",
      "customerName": "John Doe",
      "customerMethod": {
        "type": "iban",
        "data": {
          "iban": "NL23REVO1264023850",
          "name": "John Doe",
          "bic": "REVONL22"
        }
      },
      "ipAddress": "100.101.102.103",
      "status": {
        "code": 100,
        "action": "PAID"
      },
      "amount": {
        "value": 150,
        "currency": "EUR"
      }
    }
  ]
}

3.6 Offer BNPL

The request shown here works for most payment methods. However, if you want to offer Buy Now, Pay Later (BNPL), you must include additional information; otherwise, the BNPL payment option will not appear in the paylink.

BNPL methods typically require both customer and order data to perform an acceptance check. Here’s an example of what such a request might look like:

{
  "customer": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1999-11-22",
    "gender": "M",
    "phone": "0612345678"
  },
  "order": {
    "deliveryAddress": {
      "street": "P.C. Hooftstraat",
      "streetNumber": "100",
      "zipCode": "3202XA",
      "city": "Amsterdam",
      "country": "NL",
      "firstName": "John",
      "lastName": "Doe"
    },
    "invoiceAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "street": "P.C. Hooftstraat",
      "streetNumber": "100",
      "zipCode": "3202XA",
      "city": "Amsterdam",
      "country": "NL"
    },
    "products": [
      {
        "id": "ART1234",
        "description": "Article 1234",
        "type": "ARTICLE",
        "price": {
          "value": 33350
        },
        "quantity": 1,
        "vatPercentage": 0
      }
    ]
  }
}

We also recommend including customer and order data when processing PayPal transactions, as this information is required to qualify for Seller Protection.

3.7 Paylink QR code

Paylinks are primarily generated to be sent to customers via email or SMS. However, you can also generate a QR code for a paylink.

There are many free libraries available online for most programming languages that can generate QR codes. QR codes are particularly useful for displaying on invoices, allowing customers to quickly scan and complete their payment.

3.8 Testmode

During the development process, you may want to test the paylink without performing an actual payment each time. To make this easier, we’ve developed the sandbox mode.

By setting the integration.test variable while initiating a transaction, you can start the paylink in sandbox mode.

{
  "integration": {
    "test": false
  }
}

When a payment is initiated in sandbox mode, you’ll be redirected to our Sandbox payment screen, where you can easily test any desired payment status.

To verify your test payment, enter the secret in the Sandbox payment screen. You can find this secret in the Admin Panel by going to Settings > Sales locations and clicking the SL-code of the relevant sales location. A popup will appear displaying the secret, a 40-character hash.