Payment links

Overview

The payment process can also be started through a payment link sent to the customer. This link can be customized and shared as many times as you want on any channel you prefer.

The payment link lifecycle

These are the possible status of a payment link during its lifecycle:

Payment link's lifecycle. — The payment link lifecycle.

Status	Description	Next status	Webhook triggered
`created`	This is the initial status of a recently created payment link. Every time a payment link is created, an associated payment intent is also automatically created.	`succeeded`, `expired`	`payment_link.created`
`succeeded`	This status means the payment provider has accepted the payment method. A succeeded payment link does not mean the payment itself was succeeded.		`payment_link.status_updated`
`expired`	Expired payment links cannot be reactivated. Check payment link expiration for further information.		`payment_link.status_updated`

📘
The payment intent is the object that represents the payment itself and the one that must be used to track the payment.

Receive a payment through a payment link

The steps below describe how to receive a payment through a payment link:

Get the available payment methods (Recommended).
Request the payment link.
Share the payment link.
Track the payment.

1. Get the available payment methods (Recommended)

The payment link object contains the payment methods to be displayed to the payer on the payment page so they can select their preferred one during the payment act.

Learn how to get all available payment methods for a specific entity and check the full list of payment methods Monite supports.

If you know in advance which payment methods to display to the payer, you can directly request the payment link without having to retrieve the whole list of available payment methods first.

📘
This step is not mandatory but highly recommended.
Some payment methods may be rejected by the payment provider, even if you assing all payment methods to the entity and the entity completes onboarding. In these cases, if you request a payment link with rejected/inactive payment methods, an error message will be returned.

2. Request the payment link

The payer must access a specific link to initialize the payment. To get this payment link, call POST /payment_links, which will return you a payment_page_url that can be used to make the payment. The maximum payment link size is 400 characters.

The request body varies depending on whether the partner uses Monite's accounts payable and receivable solutions or only Monite's payment rails:

curl -X POST 'https://api.sandbox.monite.com/v1/payment_links' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "payment_methods": [
         "card",
         "eps",
         "ideal",
         "sepa_debit"
       ], 
       "recipient": {
         "id": "<Recipient ID>",
         "type": "entity|counterpart"
       },
       "return_url": "https://return.url.com",
       "expires_at": "2022-12-03T13:53:49.198Z",
       "object": {
         "id": "<Object ID>",
         "type": "payable|receivable"
       }
     }'

curl -X POST 'https://api.sandbox.monite.com/v1/payment_links' \
     -H 'X-Monite-Version: 2023-02-07' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "payment_methods": [
         "card",
         "eps",
         "ideal",
         "sepa_debit"
       ],
       "recipient": {
         "id": "<Recipient ID>",
         "type": "entity|counterpart"
       },
       "return_url": "https://return.url.com",
       "expires_at": "2022-12-03T13:53:49.198Z",
       "amount": 1000,
       "currency": "EUR",
       "payment_reference": "Inv 102",
       "invoice": {
         "issue_date": "2022-10-17",
         "due_date": "2022-10-17",
         "file": {
           "name": "invoice.pdf",
           "mimetype": "application/pdf",
           "url": "https://bucketname.s3.com/12345/invoice.pdf"
         }
       }
     }'

📘
Notes

With AP/AR: The return_url field is mandatory only if object.type equals to "payable".

For Monite’s payment rails only: The return_url field is optional.

The successful response contains the URL to the payment page (payment_page_url):

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": 1000,
  "currency": "EUR",
  "payment_reference": "REF",
  "payment_methods": [
    "card",
    "eps",
    "ideal",
    "sepa_debit"
  ],
  "recipient": {
    "id": "<Recipient ID>",
    "type": "entity",
    "bank_account": {
      "iban": "9128309180391",
      "bic": "18239012",
      "name": "Omega Bank"
    }
  },
  "payer": { 
    "id": "<Payer ID>",
    "type": "counterpart",
    "bank_account": {
      "iban": "2468387980468",
      "bic": "57239473",
      "name": "Delta Bank"
    }
  },
  "return_url": "https://return.url.com",
  "payment_page_url": "https://payment.page.com",
  "expires_at": "2022-12-03T13:53:49.198Z",
  "payment_intent": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "created",
    "application_fee_amount": 0,
    "selected_payment_method": "card",
    "provider": "Payment provider"
  }
}

Once the payment link is created, an associated payment intent is also automatically created. The payment intent ID returned will be used to track the actual payment.

3. Share the payment link

The URL can then be shared with the payer. By accessing the payment link, the payer will be redirected to the payment page URL address, where they will be able to fill out the payment form and finish the payment.

Example of partner payment screen displaying the available payment methods.

4. Track the payment

Use the payment intent ID obtained in step 2 to watch the payment transition from status to status and get information about the actual payment.

Watch the payment link

Watch the payment link

You can track the payment link transition from status to status in two different ways:

1. Webhook

You can be notified of every change in the status of the payment by subscribing to the payment_link.status_updated webhook. Call POST /webhook_settings passing the object_type as payment_link and the URL of your endpoint:

curl -X POST 'https://api.sandbox.monite.com/v1/webhook_settings' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "object_type": "payment_link",
       "url": "https://yourendpointurl.com"
     }'

The event sent by Monite contains entity_id, object_type, and object_id, which can be used to identify the affected payment intent:

{
  "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object_type": "payment_link",
  "action": "payment_link.status_updated",
  "name": "payment_link_status_updated",
  "entity_id": "3087f89a-a708-49ef-b0bd-3b88245bca38"
}

2. Get information about the payment link

The payment link ID received from the webhook can be used to check the status of the payment link, by calling GET /payment_links/{payment_link_id}:

curl -X GET 'https://api.sandbox.monite.com/v1/payment_links/3fa85f6...f66afa6' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

The successful response contains information about the payment link:

{
  "payer": {
    "id": "deaef523-cfd7-48ce-9de9-6d280dca1d6c",
    "type": "entity",
    "bank_accounts": [
      {
        "id": "6d280dca1d6c-5717-4562-b3fc-3fa85f64",
        "iban": "DE36442345678904488881",
        "bic": "GETT48ENOD8",
        "name": "Testbank Fiducia",
        "is_default": true
      }
    ]
  },
  "recipient": {
    "id": "deaef523-cfd7-48ce-9de9-6d280dca1d6c",
    "type": "entity",
    "bank_accounts": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "iban": "DE36444488881234567890",
        "bic": "GENODETT488",
        "name": "Testbank Fiducia",
        "is_default": true
      }
    ],
    "name": "Alayna Corkery"
  },
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "currency": "EUR",
  "status": "created",
  "payment_reference": "Inv 158",
  "amount": 11781,
  "payment_methods": [
    "card"
  ],
  "return_url": "https:/monite.pay/return",
  "invoice": {
    "issue_date": "2023-01-18",
    "due_date": "2023-01-18",
    "file": {
      "name": "test",
      "mimetype": "application/pdf",
      "url": "https://monite-file-saver-payables-eu-central-1-dev.s3.amazonaws.com/0d02290c689c.pdf"
    }
  },
  "expires_at": "2023-03-01T10:52:45.785Z",
  "payment_page_url": "https:/monite.pay/payment",
  "payment_intent": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "string",
    "application_fee_amount": 0,
    "selected_payment_method": "card",
    "provider": "Payment provider"
  }
}

Payment link customization

Payment link customization

You can customize the generated payment links with your own domain (e.g. pay.yourcompanyname.com) at the partner's settings. A CNAME pointing to this domain must be already registered in the partner’s DNS provider.

To customize your payment link, call PATCH /settings and updating the payment_page_domain field:

curl -X PATCH 'https://api.sandbox.monite.com/v1/settings' \
     -H 'X-Monite-Version: 2023-02-07' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
          "payments": {
            "payment_page_domain": "pay.yourcompanyname.com"
          }
        }'

The default value for the field payment_page_domain is null. In this case, the payment pages are served from Monite’s domain (pay.monite.com).

Once the payment_page_domain is set, please contact us in order to complete the setup on our side.

Payment link expiration

Payment link expiration

By default, payment links expire within 24 hours from when they are created. You can specify a custom expires_at timestamp (up to 70 days) when creating a payment link. Once set, the expiration time cannot be changed.

After a payment link expires, visiting its payment_page_url in a browser will show an expiration message instead of a payment page. Expired payment links cannot be reactivated, but you can create a new payment link if needed.

You can also force the expiration of a payment link by calling POST /payment_links/{payment_link_id}/expire. This may be needed, for example, if the related invoice was updated or canceled, making the original payment link outdated.

curl -X POST 'https://api.sandbox.monite.com/v1/payment_links/{payment_link_id}/expire' \
     -H 'X-Monite-Version: 2023-02-07' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: YOUR_PARTNER_TOKEN'

This changes the payment link's status to "expired". The response returns the payment link details with the updated status:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": 1000,
  "currency": "EUR",
  ...
  "status": "expired"
}

ℹ️
When a payment link expires (whether automatically or upon request), a payment_link.status_updated webhook is triggered.

Overview

The payment link lifecycle

📘

Receive a payment through a payment link

1. Get the available payment methods (Recommended)

📘

2. Request the payment link

📘Notes

3. Share the payment link

4. Track the payment

Watch the payment link

1. Webhook

2. Get information about the payment link

Payment link customization

Payment link expiration

ℹ️

📘
Notes