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.

Payment link lifecycle

These are the possible status of a payment link during its 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.

Roles and permissions

If you create payment links with an entity user token, this user must have a role with the following permissions:

To create payment links for receivable invoices: read permission for entity_bank_account and receivable.
To create payment links for payables: read permission for counterpart and payable.

When using a partner-level token, no extra permissions are required.

1. Get the available payment methods (Recommended)

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

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.

2. Create the payment link

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

The request body varies depending on whether the payment link is created for an invoice stored in Monite platform (as a payable or receivable), or for an arbitrary external invoice.

The common fields for all payment links are:

return_url - The URL where the user will be redirected after the payment is complete. It is required for payment links that are created for payables (object.type="payable") and optional for other types of payment links.
expires_at - Optional. The date and time when the payment link will expire. For more information, see Payment link expiration.
payment_methods - Required. A list of payment methods to show on the payment page. These payment methods must be enabled for the entity that will make or accept the payment.
- Payables can currently be paid using:
  - SEPA Credit (sepa_credit) - in case of European entities and counterparts in the SEPA zone.
  - ACH Direct Debit (ach) - in case of US-based entities and counterparts. Note: ACH payment option is not available on Monite payment page. Instead, these payments can be initiated by calling POST /batch_payments. Refer to our ACH guide to learn how to integrate ACH payments into your application.
- Receivables can be paid using any payment method with direction=receive.
- External invoices can be paid using the same payment methods as payables (in case an entity pays to its counterpart) or receivables (in case an entity accepts a payment from its counterpart).

Other required fields and values depend on the use case and are explained below:

Payment link for a payable
Payment link for a receivable
Payment link for an external invoice

The successful response contains the URL to the payment page (payment_page_url). This URL can be up to 400 characters long.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": 1000,
  "currency": "EUR",
  "payment_reference": "REF",
  "payment_methods": [
    "card",
    "eps",
    "ideal",
    "sepa_debit"
  ],
  "recipient": {
    "id": "24e4ccc9-b8af-4298-9f5c-aa1a76f3d6c0",
    "type": "entity",
    "bank_account": {
      "iban": "9128309180391",
      "bic": "18239012",
      "name": "Omega Bank"
    }
  },
  "payer": { 
    "id": "50465b06-a4be-460a-a04d-be57e350270a",
    "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.

2.1. Payment link for a payable

Payment links can be created only for payables in the waiting_to_be_paid status. To create a payment link, specify the following data in the request body for POST /payment_links:

object.type - Must be "payable".
object.id - Required. Payable ID.
recipient.type - Must be "counterpart".
recipient.id - Required. ID of the counterpart that issued the payable. The value must be the same as the counterpart ID in the payable data.
payment_methods - This list must contain a single item, "sepa_credit".
return_url - Required. The URL where the entity user who will make the payment will be redirected after the payment is successfully initiated.
Other fields as necessary.

curl -X POST 'https://api.sandbox.monite.com/v1/payment_links' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "object": {
         "type": "payable",
         "id": "PAYABLE_ID"
       }
       "recipient": {
         "type": "counterpart",
         "id": "COUNTERPART_ID"
       },
       "payment_methods": [
         "sepa_credit"
       ],
       "return_url": "https://return.url.com",
       "expires_at": "2023-12-03T13:53:49.198Z",
     }'

2.2. Payment link for a receivable

Payment links can be created only for receivable invoices in the issued and partially_paid statuses. To create a payment link, specify the following data in the request body for POST /payment_links:

object.type - Must be "receivable".
object.id - Required. ID of the receivable invoice.
recipient.type - Must be "entity".
recipient.id - Required. ID of the entity that issued the receivable. The value must be the same as specified in X-Monite-Entity-Id request header.
Other fields as necessary.

curl -X POST 'https://api.sandbox.monite.com/v1/payment_links' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "object": {
         "type": "receivable",
         "id": "RECEIVABLE_INVOICE_ID"
       }
       "recipient": {
         "type": "entity",
         "id": "ENTITY_ID"
       },
       "payment_methods": [
         "card",
         "eps",
         "ideal",
         "sepa_credit",
         "sepa_debit"
       ],
       "return_url": "https://return.url.com",
       "expires_at": "2023-12-03T13:53:49.198Z",
     }'

2.3. Payment link for an external invoice

This example shows how to create a payment link for an arbitrary invoice (stored outside of Monite platform) or arbitrary payment amount. You need to call POST /payment_links and provide the following data in the request body:

currency - Required. The payment currency. See the list of currencies supported by Monite.
amount - Required. The amount to be paid, in minor units.
payment_reference - Required. Invoice number or payment reference number.
invoice - Optional. An object containing information about the invoice, such as the issue date, due date, URL of the invoice file. If provided, this information will be displayed on the payment page. If invoice file URL is provided, the payment page will also display the invoice file. For a list of invoice object fields, see the description of the POST /payment_links endpoint.
Other fields as necessary.

curl -X POST 'https://api.sandbox.monite.com/v1/payment_links' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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_credit",
         "sepa_debit"
       ],
       "recipient": {
         "id": "<Recipient ID>",
         "type": "entity|counterpart"
       },
       "return_url": "https://return.url.com",
       "expires_at": "2023-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"
         }
       }
     }'

3. Share the payment link

After a payment link is created, you can share its URL (payment_page_url) with the payer. When a payer navigates to this URL, they will see the payment page displaying information about the invoice and payment amount. The payer can select their preferred payment method and enter their payment information to initialize 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

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_subscriptions with the following request body, replacing the url with the URL of your webhook listener endpoint:

curl -X POST 'https://api.sandbox.monite.com/v1/webhook_subscriptions' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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:

{
  "id": "06c003f1-6b05-415f-be6d-39ecacdddbd3",
  "created_at": "2024-03-04T20:06:48.593225+00:00",
  "action": "payment_link.status_updated",
  "api_version": "2024-01-31",
  "entity_id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0",
  "description": "payment_link_status_updated",
  "object": {
    "id": "f7dcd6bc-2cc9-4cb9-be9c-d7bf2404acd7"
  },
  "object_type": "payment_link",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}

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: 2024-01-31' \
     -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

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: 2024-01-31' \
     -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

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: 2024-01-31' \
     -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.