Payment intents

Overview

Monite aggregates the most popular payment methods and providers and allows you to define the right payment method for each transaction. This enables bill pay, invoice payment links, and other payments for the entity's customers.

📘
The entity must be onboarded in order to accept payments.

Payment intent

The payment intent is the intention of a customer to execute a payment. In our system, a payment intent is an object that represents the payment itself. It is used to track the lifecycle of the payment flow. This gives you full control over the payment journey.

A new payment intent is created every time a payment process is initiated. Also, an associated payment intent is automatically created every time a payment link is created.

The payment intent object can also be used to see the history of a specific payment.

Payment intent lifecycle

Each payment intent is allocated with a status that indicates its progress throughout the payment lifecycle, from its creation until its conclusion.

Status	Description	Next status	Webhook triggered
`created`	This is the initial status for all payments. At this status, the payment intent is created.	`pending`	`payment_intent.create`
`pending`	This status indicates the payer had accomplished the required actions for the payment on their side and the payment is being processed. Some payment methods, e.g. cards, can be processed very quickly, while other payment methods can take even a few days.	`succeeded`, `canceled`, `failed`	`payment_intent.status_update`
`canceled`	Only `pending` payments can be canceled. A canceled payment cannot be used for future payment attempts. This action cannot be undone.		`payment_intent.status_update`
`succeeded`	This status means the payment was successfully authorized and is ready to be settled (i.e. the bank transfer can be initiated by the bank or the payout can be triggered to the recipient's bank account).	`settled`, `failed`, `disputed`	`payment_intent.status_update`
`failed`	If for any reason, e.g. a bank declines the transaction, the payment attempt fails and its status becomes `failed`.		`payment_intent.status_update`
`settled`	It means the recipient has the funds in their account.	`disputed`	`payment_intent.status_update`
`disputed`	Occurs when a payer contests your charge with their bank for any reason. This status is only available for certain providers.		`payment_intent.status_update`

Watch the payment intent

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

Webhook

You can be notified of every change in the status of the payment intent 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 'X-Monite-Version: 2023-03-14' \
     -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"
}

Get information about the payment intent

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}:

curl -X GET 'https://api.sandbox.monite.com/v1/payment_intents/3fa85f6...f66afa6' \
     -H 'X-Monite-Version: 2023-03-14' \
     -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"
    }
  }
}

Get the payment intent history

You can check the full status transition history of a specific payment intent by calling GET /payment_intents/{payment_intent_id}/history:

curl -X GET 'https://api.sandbox.monite.com/v1/payment_intents/3fa85f...f66afa6/history' \
     -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'

The successful response returns one data item for each change in the payment intent status:

{
  "data": [
    {
      "id": "3fa85f64-4626-8255-b5dd-2c963f649fcd5",
      "payment_intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "created",
      "created_at": "2023-01-30T15:46:41.106Z",
      "updated_at": "2023-01-30T15:46:41.106Z"
    },
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "payment_intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "succeeded",
      "created_at": "2023-01-30T18:27:30.115Z",
      "updated_at": "2023-01-30T18:27:30.115Z"
    }
  ]
}

Payment methods

When the payment process is initiated, Monite allows the partner's platform to control the available payment methods to be displayed to the payer on the payment page so they can select their preferred one during the payment act. Check the full list of payment methods Monite supports.

Payment links

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.