Integration via API

By using the API, you will be able to generate a payment order and obtain a payment URL to redirect your clients to your checkout page.

Using our API you'll be able to:

obtain a payment URL that will load one of your already created checkouts
decide on real time the rendered payment methods
modify the checkout customization

1. Generate the payment order on your server

Caution: Before proceeding, make sure you have a checkout created in your Paylands account. If you do not know how to do this, please refer to the section Create a checkout.

When generating the payment order, the extra_data field you'll send in the request must include the checkout field, which is an object that supports the following fields:

Checkout
uuid	Checkout uuid, you can grab it from our dashboard	Required
customization	Customization object	Optional
payment_methods	List of the payment methods the checkout will show	Optional
default_payment_method	Payment method that will be selected by default	Optional

customization
theme_type	Background color (light or dark)	Optional
description	Text that will be displayed in the summary section	Optional
font	Font type	Opcional
accent_color	Color that will applied to buttons and icons	Optional
language	Checkout language	Optional
logo	Top image URL	Optional
footer_logo	Bottom image URL	Optional
footer_terms_and_conditions	URL to the terms and conditions in your website	Optional
payment_details	A key-value list that will be displayed in the summary section	Optional

payment_methods
PAYMENT_CARD	SPEI	PIX	SERVIPAG	COFIDIS
GOOGLEPAY	PAYSAFECARD	CRYPTO	KHIPU	FLOA
APPLEPAY	PAGO_FACIL	GIROPAY	FLOWPAY	VIACASH
BIZUM	EFECTY	TRANSFER	CASH	MBWAY
IDEAL	BOLETO	PSE	PICPAY	KLARNA
SOFORT	LOTERICA	PAYPAL	WEBPAY	MULTIBANCO

{
    "signature": "341f7de8e6fc49da8d8736473af6b03a",
    "amount": 100,
    "operative": "AUTHORIZATION",
    "secure": false,
    "customer_ext_id": "test",
    "description": "Payment #1",
    "additional": null,
    "url_post": "https://my.website.com/process",
    "url_ok": "https://my.website.com/ok",
    "url_ko": "https://my.website.com/ko",
    "reference": "50620",
    "currency": "EUR",
    "extra_data": {
        "checkout": {
            "uuid": "9A1BDCC8-DB30-4ED2-8523-62B330A67873",
            "customization": {
                "theme_type": "DARK",
                "font": "Roboto",
                "accent_color": "#FF0000",
                "footer_logo": "https://my.website.com/footer_logo.png",
                "footer_terms_and_conditions": "https://my.website.com/terms",
                "payment_details": {
                    "Reservation ID": "ABCD1234X",
                    "Guests": 3
                }
            },
            "payment_methods": ["PAYMENT_CARD", "GOOGLEPAY", "APPLEPAY"],
            "default_payment_method": "PAYMENT_CARD"
        }
    }
}

The full specification for Generate payment order can be found in the API Reference.

2. Redirect the customer to the checkout

The order generation response will contain the TOKEN you need to redirect the user to the checkout.

{
    "message": "OK",
    "code": 200,
    "current_time": "2025-01-08T13:10:20+0100",
    "order": {
        "uuid": "8809C546-29C1-433D-AE7F-C13FFCCC0403",
        "created": "2025-01-08T13:10:20+0100",
        "created_from_client_timezone": "2025-01-08T13:10:20+0100",
        "amount": 100,
        "currency": "978",
        "paid": false,
        "status": "CREATED",
        "safe": false,
        "refunded": 0,
        "additional": null,
        "service": null,
        "service_uuid": null,
        "customer": "test",
        "cof_txnid": null,
        "transactions": [],
        "token": "679b3958c82a0415cfedeff1a5404d2ddc02b4046ecad8980d4a1b9f1b443a8d0ad877024e309866d7b294dffd4e232375aa32a1a000fb16898c6013db839c42",
        "ip": null,
        "reference": "50620",
        "threeds_data": null
    },
    "client": {
        "uuid": "692221A4-8090-4088-BB84-C267B9981D0A"
    },
    "extra_data": {
        "checkout": {
            "uuid": "9A1BDCC8-DB30-4ED2-8523-62B330A67873",
            "customization": {
                "title": null,
                "description": null,
                "background_color": null,
                "accent_color": "#FF0000",
                "text_color": null,
                "font": "Roboto",
                "language": null,
                "theme_type": "DARK",
                "payment_details": {
                    "Reservation ID": "ABCD1234X",
                    "Guests": 3
                },
                "logo": null,
                "footer_logo": "https:\/\/my.website.com\/footer_logo.png",
                "footer_terms_and_conditions": "https:\/\/my.website.com\/terms"
            },
            "payment_methods": [
                "PAYMENT_CARD",
                "GOOGLEPAY",
                "APPLEPAY"
            ],
            "default_payment_method": "PAYMENT_CARD"
        }
    },
    "validation_hash": "c39f00c8f790af98923372a2a0cf464987e73de6fd451aefcf1e8cd630f1e794"
}

The URL to redirect the customer is /payment/process/{TOKEN} and looks like this:

https://api.paylands.com/v1/payment/process/dd27da7cc018f5daf85d426e2d72bb3207173a057ac0f5164a8bec9dd2286d1f64e25eb50ec68e7c37d4bf54236a014e7f2aa65834b42678bde5d882b2217fd0

Implementation inside an iframe

Our checkout communicates with the container page (parent window) through JavaScript events (window.postMessage), which you must subscribe to in order to manage the different payment states.

Events sent by the iframe

The iframe will send messages to window.top (or parent) using the following structure:

{
  "redirect": "https://..."
}

{
  "render": "<html>...</html>"
}

{
  "error": "error message"
}

Recommended implementation

window.addEventListener("message", function (event) {

    const allowedOrigin = "https://api.paylands.com";

    if (event.origin !== allowedOrigin) {
        return;
    }

    const data = event.data;

    if (data.redirect) {
      /* The payment has finished and returns the url_ok or url_ko */
      /* Your code should apply the strategy you need: */
      /* - load the URL in your page */
      /* - replace it inside the iframe */
      return;
    }

    if (data.render) {
      /* Get the iframe element and replace its srcdoc */
      iframe.srcdoc = data.render;
      return;
    }

    if (data.error) {
      /* In case of error, you can display it as needed */
      console.error("Payment error:", data.error);
    }
});

3. The customer completes the payment and your server is notified.

When the customer enters the payment details depending on the payment method they choose and the payment process is completed, Paylands sends a callback notification to the merchant at the url specified in the url_post field.

To learn more about how to validate the notification you can go to the Notification validation section.

4. The client is redirected back to your server.

Paylands then redirects the user to the corresponding url according to the result of the operation:

If the payment was successful the user is redirected to the url specified in the url_ok field.
In any other case, the user is redirected to the url specified in the url_ko field.

Integration via API

1. Generate the payment order on your server​

2. Redirect the customer to the checkout​

3. The customer completes the payment and your server is notified.​

4. The client is redirected back to your server.​

1. Generate the payment order on your server

2. Redirect the customer to the checkout

3. The customer completes the payment and your server is notified.

4. The client is redirected back to your server.