Simple integration

The Paylands redirection payment card is the simplest and safest way to collect payments from your customers. They are shown a screen with a form for them to enter their card details. This can be done through a redirect or by showing them the form embedded in a iframe on your website.

This method will allow you to easily build a unique payment experience:

• Designed to eliminate friction: Real-time card validation with built-in error messages.
• Mobile-ready: Fully responsive design.
• Multiple payment methods: Supports multiple payment methods.
• 3D Secure: Supports 3D Secure. SCA verification process.
• Fraud and compliance: Simplified PCI compliance and SCA ready.
• International: Support for 14 languages.
• Customization and branding: Customizable logo, buttons and background color.

You can customize the appearance of the payment letter in Paylands Backend → Customization → Templates. By clicking the create new button, you will be able to select the Payment Letter type template where it will allow you to fully modify the aesthetics of the checkout form. If you wish you can consult our Guide on how to customize the payment letter.

Integration

1. Generate the payment order on your server

The merchant must send the payment characteristics to the /payment endpoint (amount, service, urls, ...) to generate the order. Paylands returns an order object together with an order TOKEN that will be used to redirect to the payment letter to finalize the payment.

curl --request POST 'https://api.paylands.com/v1/sandbox/payment' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
  "signature": "341f7de8e6fc49da8d8736473af6b03a",
  "amount": 100,
  "operative": "AUTHORIZATION",
  "secure": false,
  "customer_ext_id": "test",
  "service": "9A1BDCC8-DB30-4ED2-8523-62B330A67873",
  "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",
  "template_uuid": "6412549E-933E-4DFE-A225-2E87FBF7623E",
  "dcc_template_uuid": "BF418CA6-7043-4864-B36F-F02C2CF2B76B",
  "source_uuid": null,
  "save_card": true,
  "reference": "50620",
  "dynamic_descriptor": "PNP*MerchantName",
  "expires_in": 3600
}'

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

2. Redirect the customer to the payment letter form.

In the response of the previous call to /payment we have the TOKEN we need to redirect the user to the payment letter form.

{
  "message": "OK",
  "code": 200,
  "current_time": "2021-12-28T15:29:49+0100",
  "order": {
    "uuid": "96A59A8B-2FCC-4306-92D8-7EA8712BAE5C",
    "created": "2021-12-28T15:29:49+0100",
    "created_from_client_timezone": "2021-12-28T16:29:49+0200",
    "amount": 100,
    "currency": "978",
    "paid": false,
    "status": "CREATED",
    "safe": false,
    "refunded": 0,
    "additional": "",
    "service": "CREDORAX",
    "service_uuid": "9A1BDCC8-DB30-4ED2-8523-62B330A67873",
    "customer": "test",
    "cof_txnid": null,
    "transactions": [],
    "token": "dd27da7cc018f5daf85d426e2d72bb3207173a057ac0f5164a8bec9dd2286d1f64e25eb50ec68e7c37d4bf54236a014e7f2aa65834b42678bde5d882b2217fd0",
    "ip": null,
    "urls": {
            "payment_card": "https:\/\/api.paylands.com\/v1\/sandbox\/payment\/process\/dd27da7cc018f5daf85d426e2d72bb3207173a057ac0f5164a8bec9dd2286d1f64e25eb50ec68e7c37d4bf54236a014e7f2aa65834b42678bde5d882b2217fd0",
            "bizum": "https:\/\/api.paylands.com\/v1\/sandbox\/payment\/bizum\/dd27da7cc018f5daf85d426e2d72bb3207173a057ac0f5164a8bec9dd2286d1f64e25eb50ec68e7c37d4bf54236a014e7f2aa65834b42678bde5d882b2217fd0",
            "3ds_tokenized": "https:\/\/api.paylands.com\/v1\/sandbox\/payment\/tokenized\/dd27da7cc018f5daf85d426e2d72bb3207173a057ac0f5164a8bec9dd2286d1f64e25eb50ec68e7c37d4bf54236a014e7f2aa65834b42678bde5d882b2217fd0"
        },
    "reference": null,
    "dynamic_descriptor": null,
    "threeds_data": null
  },
  "client": {
    "uuid": "42B8CF56-A7D7-4D4A-8349-4E27263CB2D5"
  }
}

The URL of the payment letter the merchant should redirect to is /payment/process/{TOKEN} looking like this:

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

The merchant can simply redirect the navigation to this URL or embed in an iframe the URL to simulate that the navigation continues on your site.

<iframe id="paylands"
    title="Paylands"
    width="600"
    height="800"
    src="https://api.paylands.com/v1/payment/process/dd27da7cc018f5daf85d426e2d72bb3207173a057ac0f5164a8bec9dd2286d1f64e25eb50ec68e7c37d4bf54236a014e7f2aa65834b42678bde5d882b2217fd0">
</iframe>

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

Customer enters credit card information (and other payment information depending on the selected payment method) and goes through the 3D secure verification process (is redirected to the page provided by the credit card issuing bank for transaction confirmation) if necessary.

Paylands then receives the data, processes it and issues a notification to the merchant at the url specified in the url_post field along with the updated order object with the result of the transaction.

{
  "message": "OK",
  "code": 200,
  "current_time": "2021-12-28T13:24:26+0100",
  "order": {
    "uuid": "495BEE1F-7D00-4E4B-9511-F1665118932F",
    "created": "2021-12-28T13:24:22+0100",
    "created_from_client_timezone": "2021-12-28T14:24:22+0200",
    "amount": 100,
    "currency": "978",
    "paid": true,
    "status": "SUCCESS",
    "safe": false,
    "refunded": 0,
    "additional": "",
    "service": "CREDORAX",
    "service_uuid": "9A1BDCC8-DB30-4ED2-8523-62B330A67873",
    "customer": "test",
    "cof_txnid": null,
    "transactions": [
      {
        "uuid": "595E1818-A4E3-4A16-92A5-1DC6988162CC",
        "created": "2021-12-28T13:24:22+0100",
        "created_from_client_timezone": "2021-12-28T14:24:22+0200",
        "operative": "AUTHORIZATION",
        "amount": 100,
        "authorization": "810551",
        "processor_id": "XZZ7281d1a563df2A6ADSYOOMDF6FGPP",
        "status": "SUCCESS",
        "error": "NONE",
        "source": {
          "object": "CARD",
          "uuid": "6C5D535E-1B5B-4665-8A32-08ADF2A680B7",
          "type": "",
          "token": "f41fdb5764efad821b2527aeaaf236e29d010771ea5a73ba26044526ec934f1100d8fc6930910ccd634ecc81c0aa7a1b3b721a739f2bac8aa4eedc0d529806d8",
          "brand": "VISA",
          "country": "US",
          "holder": "Jose",
          "bin": 476173,
          "last4": "0016",
          "is_saved": true,
          "expire_month": "12",
          "expire_year": "21",
          "additional": "Card additional",
          "bank": "",
          "prepaid": "",
          "validation_date": "2021-12-28 13:24:25",
          "creation_date": "2021-12-28 13:24:21",
          "brand_description": null,
          "origin": "PAYMENT_CARD",
          "cof": {
            "is_available": true
          }
        },
        "antifraud": null,
        "device": null,
        "error_details":null
      }
    ],
    "token": "dd27da7cc018f5daf85d426e2d72bb3207173a057ac0f5164a8bec9dd2286d1f64e25eb50ec68e7c37d4bf54236a014e7f2aa65834b42678bde5d882b2217fd0",
    "ip": "127.0.0.1",
    "reference": null,
    "dynamic_descriptor": null,
    "threeds_data": null
  },
  "client": {
    "uuid": "42B8CF56-A7D7-4D4A-8349-4E27263CB2D5"
  },
  "validation_hash" : "2db16932777640d5a9d2aa60b5308a70aba29a3a4ee410d103f0b8a3b7e0cc5f",
}

In the processed order, a source object containing the token of the card used in the payment is included in the transaction. This payment method token will from now on be linked to the customer, so that in new transactions it will be possible to confirm payments for this user without the need to request the card again. Find out how to do this in our guide Save and use of cards.

To learn more about how to validate the notification, please refer to the section. Notification validation

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.