Process a payment

Learn how to provide a variety of payment methods and initiate payments.

Overview

When the payment process is initiated, Monite allows the partner's platform to control the available payment methods to be displayed, so that payers can choose their preferred one and proceed with the payment.

The steps below describe the full payment process:

  1. Get all available payment methods (Optional).

  2. Request a payment link.

  3. The payer fills the payment form.

  4. Track the payment status changes.

1. Get all available payment methods (Optional)

To get the list of all the payment methods available for a particular entity, call GET /entities/{entity_id}/payment_methods:

curl -X GET 'https://api.sandbox.monite.com/v1/entities/3fa85f64...3f66afa6/payment_methods' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' 

The successful response returns the list of payment methods available for the particular payment. The example below lists all payment methods Monite supports:

{
  "data": [
    {
      "name": "Afterpay (Clearpay)",
      "type": "afterpay_clearpay",
      "status": "active"
    },
    {
      "name": "Alipay",
      "type": "alipay",
      "status": "inactive"
    },
    {
      "name": "BLIK",
      "type": "blik",
      "status": "active"
    },
    {
      "name": "Bancontact",
      "type": "bancontact",
      "status": "inactive"
    },
    {
      "name": "Card payments",
      "type": "card",
      "status": "active"
    },
    {
      "name": "Electronic Payment Standard",
      "type": "eps",
      "status": "active"
    },
    {
      "name": "Giropay",
      "type": "giropay",
      "status": "inactive"
    },
    {
      "name": "iDEAL",
      "type": "ideal",
      "status": "active"
    },
    {
      "name": "Przelewy24",
      "type": "p24",
      "status": "active"
    },
    {
      "name": "Multibanco",
      "type": "multibanco",
      "status": "active"
    },
    {
      "name": "SEPA Payments",
      "type": "sepa_credit"
    },
    {
      "name": "SEPA Direct Debit",
      "type": "sepa_debit"
    },
    {
      "name": "SOFORT",
      "type": "sofort",
      "status": "active"
    },
    {
      "name": "WeChat Pay",
      "type": "wechat_pay",
      "status": "active"
    }
  ]
}

With all the available payment methods in hand, you can select which ones must be presented to the payer.

πŸ“˜

Alternatively, if you know in advance which payment methods to display to the payer, it is possible to directly initiate the payment request through the provided method without having to retrieve the whole list of available payment methods first.

2. Request a payment link

The payer must access a specific link to initialize its 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 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-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-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"
      }
    }
  }'

πŸ“˜

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

πŸ“˜

A payment_intent is created simultaneously with the payment_link. It represents the actual payment and its ID will be used to track the payment status on step 4.2.

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-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.

3. The payer fills the payment form

After 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.

Example of partner payment screen displaying the available payment methods.

4. Track the payment status changes

You can watch the payment transition from status to status in different ways:

4.1. Webhook

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

curl -X 'POST https://api.sandbox.monite.com/v1/webhook_settings' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "object_type": "payment_intent",
       "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_intent",
  "action": "payment_intent.status_updated",
  "name": "payment_intent_status_updated",
  "entity_id": "3087f89a-a708-49ef-b0bd-3b88245bca38"
}

πŸ“˜

There are also webhooks to keep track of payment links. See Webhooks for further information.

4.2. Get information about the payment

The payment intent ID received from the webhook can be used to check the progress of the actual payment, by calling GET /payment_intents/{payment_intent_id}. The payment_intent_id can also be obtained during the payment link creation:

curl -X GET 'https://api.sandbox.monite.com/v1/payment_intents/3fa85f6...f66afa6' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
  -H 'accept: application/json' \

The successful response contains information about the payment intent:

{
  "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",
  "status": "created",
  "amount": 11781,
  "payment_methods": [
    "card"
  ],
  "selected_payment_method": "card",
  "payment_link_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "currency": "EUR",
  "payment_reference": "Inv 158",
  "provider": "Payment provider",
  "application_fee_amount": 0,
  "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"
    }
  }
}

πŸ“˜

It is also possible to keep track of the generated payment link by calling GET /payment_links/{payment_link_id}.