Payments

Payment Flow

In principle, the Checkout Session flow has 5 steps (as shown in the diagram below):

1. Your customer click a "Pay by Bank" button. It trigger a request to your backend to create a Checkout Session

2. On your backend side, create a Checkout Session using your API Key.

3. Mentium API will return you the Checkout Session with a Checkout URL

4. Redirect your customer to this Checkout URL

5. Customer complete the payment

6. Once payment is complete, the customer is redirected to the Success URL you provided.

Creating a Checkout Session

In order to accept a payment through your website or using a Mentium Link, you need to start by creating a Checkout Session.

Request parameters

You must provide either a valid customerId or customerDetails. If customerDetails is specified it will create a customer or use the existing customer if the email is already used.

Parameter	Required	Type	Description
amount	yes	number	A positive number. The amount charged to your customer
customerId	no (customerDetails must be provided)	string	A valid Customer ID
customerDetails	no (customerId must be provided)	object	A JSON object that contains your customer information: email, firstName, lastName
successURL	no	string	The URL the customer will be directed to after the payment or subscription creation is successful. e.g. http://example.com/order/success?session_id={CHECKOUT_SESSION_ID}
errorURL	no	string	The URL the customer will be directed to after the payment failed. http://example.com/order/error.html
cancelURL	no	string	If set, a back button will be displayed and customers will be directed to this URL if they decide to cancel payment and return to your website. http://example.com/order/cancel.html

Note: To create a checkout session, your seller must be VERIFIED. Otherwise you will get an error.

Creates a new checkout session

POST/v1/checkout

Body

application/json

The CreateCheckoutSessionRequest message represents a request to create a new checkout session.

amountThe amount charged to the customer (in USD)

successUrlstring

The URL the customer will be directed to after the payment or subscription creation is successful.

errorUrlstring

The URL the customer will be directed to after the payment failed.

cancelUrlstring

The URL the customer will be directed to if they decide to cancel payment and return to your website.

customerDetailsv1CustomerDetails (object)

The customer_details message represents details of a customer.

customerIdThe ID of the customer

onBehalfOfThe Mentium account ID you want to share the payment with

onBehalfOfAmountThe amount you want to give to the account

Response

200default

A successful response.

Body

application/json

checkoutSessionmentiumpublicapicheckoutv1CheckoutSession (object)

The checkout_session message represents a session for a checkout process.

checkoutUrlThe URL the customer will complete checkout

Request

JavaScriptCurl

const response = await fetch('/v1/checkout', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "checkoutSession": {
    "id": "text",
    "amount": 0,
    "customerId": "text",
    "customerDetails": {
      "firstName": "text",
      "lastName": "text",
      "email": "text",
      "phone": "text"
    },
    "status": "text",
    "paymentStatus": "text",
    "successUrl": "text",
    "errorUrl": "text",
    "cancelUrl": "text",
    "onBehalfOf": "text",
    "onBehalfOfAmount": 0,
    "createdAt": "2024-05-07T00:06:58.236Z",
    "expiresAt": "2024-05-07T00:06:58.236Z"
  },
  "checkoutUrl": "text"
}

Lists all the checkout sessions

GET/v1/checkout

Query parameters

Response

200default

A successful response.

Body

application/json

sessionsList of sessions

nextPageTokeninteger (int32)

Token to retrieve the next page of results, or empty if there are no more results in the list.

Request

JavaScriptCurl

const response = await fetch('/v1/checkout', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "sessions": [
    {
      "id": "text",
      "amount": 0,
      "customerId": "text",
      "customerDetails": {
        "firstName": "text",
        "lastName": "text",
        "email": "text",
        "phone": "text"
      },
      "status": "text",
      "paymentStatus": "text",
      "successUrl": "text",
      "errorUrl": "text",
      "cancelUrl": "text",
      "onBehalfOf": "text",
      "onBehalfOfAmount": 0,
      "createdAt": "2024-05-07T00:06:58.236Z",
      "expiresAt": "2024-05-07T00:06:58.236Z"
    }
  ]
}

Gets a checkout session by ID

GET/v1/checkout/{id}

Path parameters

id*string

ID of the checkout session

Response

200default

A successful response.

Body

application/json

idID of the checkout session

amountThe amount charged to the customer (in USD)

customerIdstring

The ID of the customer. If not provided, the customer will be automatically created.

customerDetailsv1CustomerDetails (object)

The customer_details message represents details of a customer.

statusStatus of the checkout session. NOT_OPENED, OPENED, CANCELLED

paymentStatusStatus of the payment. PAID or UNPAID

successUrlstring

The URL the customer will be directed to after the payment or subscription creation is successful.

errorUrlstring

The URL the customer will be directed to after the payment failed.

cancelUrlstring

The URL the customer will be directed to if they decide to cancel payment and return to your website.

onBehalfOfThe Mentium account ID you want to share the payment with

onBehalfOfAmountThe amount you want to give to the account

createdAtTimestamp when the session was created

expiresAtTimestamp when the session will expire

Request

JavaScriptCurl

const response = await fetch('/v1/checkout/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "id": "text",
  "amount": 0,
  "customerId": "text",
  "customerDetails": {
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "phone": "text"
  },
  "status": "text",
  "paymentStatus": "text",
  "successUrl": "text",
  "errorUrl": "text",
  "cancelUrl": "text",
  "onBehalfOf": "text",
  "onBehalfOfAmount": 0,
  "createdAt": "2024-05-07T00:06:58.236Z",
  "expiresAt": "2024-05-07T00:06:58.236Z"
}

Checkout Session Object

Property	Description
id	The unique CheckoutSession ID
amount	The amount of charged to the customer (in USD)
customer_id	The customer details (first name, last name, email and phone). Required unless customer_id is provided
customer_details	The customer details (first name, last name, email and phone). Required unless customer_id is provided
payment_status	PAID or UNPAID
on_behalf_of	The account ID of the person who will receive the payment
on_behalf_of_amount	The amount that will be paid to the account ID provided in on_behalf_of
success_url	The URL the customer will be directed to after the payment or subscription creation is successful. e.g. http://example.com/order/success?session_id={CHECKOUT_SESSION_ID}
error_url	The URL the customer will be directed to after the payment failed. http://example.com/order/error.html
cancel_url	If set, a back button will be displayed and customers will be directed to this URL if they decide to cancel payment and return to your website. http://example.com/order/cancel.html

Error codes

When the user confirms the payment it is possible that the payment fails. An error code is passed to the onError callback function. Error code is a short string with a brief explanation.

Error Type	Description	Next steps
BANK_ACCOUNT_CLOSED	The customer bank account has been closed	The customer must use a different bank account
BALANCE_UNAVAILABLE	The balance of the charged bank account is not available.	The customer must use a different bank account You can also contact Mentium support at [e-mail]
NON_SUFFICIENT_FUNDS	The balance of the charged bank account is not enough to cover the transaction. Note: It's required to have at least twice the transaction amount on the bank account	The customer must use a different bank account
DUPLICATE_TRANSACTION	A payment with the same informations has been submitted in the last 5min	Verify the provided orderID
UNKNOWN_ERROR	An unexpected error occurred during the transaction.	Contact Mentium support at [e-mail]

As the payments are created, processed, and finalised, they go through a number of states that you will get as an API response, through webhook notifications, and in the Dashboard.

Don't hesitate to reach out with any questions or feedback. You can email Mentium directly at [e-mail], or join our discord server.