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

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"]
        }
    }
}

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"
            ]
        }
    },
    "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

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.