Build a custom checkout
Build you custom checkout using MONEI UI components to securely collect payments using different payment methods.
MONEI UI components:
- generate a one time
paymentToken
that can be used to securely process a payment. - are available in plain JavaScript, React, Vue and Angular.
- support different styles, languages and customizations.
- do not require PCI compliance
Check the detailed guides for each payment method in our Payment Methods section.
#
Before you beginThis page explains how to add different payment methods to your custom payment page. If you don't need a custom checkout experience we recommend using our prebuilt payment page. It already supports all available payment methods and does not require coding.
To test your integration:
- Use your test mode Account ID and API Key.
- Make sure you have all payment methods configured. Check Payment Methods section for more details about each payment method.
- You can check the status of a test payment in your MONEI Dashboard → Payments (in test mode).
#
IntegrationServer-side
#
1. Create a Payment Create a Payment on your server with an amount and currency. Always decide how much to charge on the server side, a trusted environment, as opposed to the client. This prevents malicious customers from being able to choose their own prices.
- cURL
- Node.js
- PHP
The following parameters are required:
- amount
positive integer
- Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD) - currency
string
- Three-letter ISO currency code, in uppercase. Must be a supported currency. - orderId
string
- An order ID from your system. A unique identifier that can be used to reconcile the payment with your internal system. - callbackUrl
string
- The URL to which a payment result should be sent asynchronously.
Check all available request parameters.
Included in the returned Payment object is a payment id
, which is used on the client side to securely complete the payment process instead of passing the entire Payment object.
Client-side
#
2. Add UI Component to your payment page Include monei.js
on your checkout page by adding the script tag to the head
of your HTML file.
Create empty DOM nodes (containers) with unique IDs in your checkout page.
Initialize UI component
If you have a checkout flow where you need to generate payment token before you create a payment on your server you can initialise MONEI UI Components providing following parameters:
- accountId
string
- Your MONEI account ID. Instead of passing paymentId you can initialize a card input with the accountId and sessionId (optional). Generate a payment token before you create the payment itself. - sessionId
string
- Unique session ID in your system. Provide a different sessionId for each customer. Use this parameter to ensure that the customer who generated the token is the same as the one doing the payment. Only required if you pass a token to your server. If you provide a sessionId when initializing MONEI component you will need to provide the same value when you create a payment on your server. - amount
positive integer
(not required for CardInput) - Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD). You'll need to pass the same value when creating the payment. - currency
string
(not required for CardInput) - Three-letter ISO currency code, in uppercase. Must be a supported currency. You'll need to pass the same value when creating the payment.
Check Payment Methods section for more details about how to initialize components for each payment method.
Client-side
#
3. Confirm the payment To complete the payment you need to confirm it using monei.js confirmPayment function
You need to provide a paymentId
(obtained in step 1) and paymentToken
generated with UI Component. Check Payment Methods section for more details about how to generate paymentToken
for each payment method.
You can also provide additional parameters like customer.email
. Check all available parameters.
After you confirm the payment MONEI will automatically show a popup window with 3d secure confirmation screen (if needed, depending on the payment method)
note
As an alternative process you can submit generated paymentToken
to your sever and then confirm payment on the server-side.
#
4. An asynchronous request is sent to your server.MONEI will notify you about a payment status by sending an HTTP POST request to the callbackUrl
. The request body will contain full payment object in JSON format.
This ensures that you get the payment status even when customer closed the browser window or lost internet connection.
The request also contains a MONEI-Signature
header. Verify this signature to confirm that received request is sent from MONEI.
To acknowledge receipt of the request, your endpoint must return a 200
HTTP status code to MONEI. All other response codes, including 3xx
codes, indicate to MONEI that you did not receive the event.
If MONEI does not receive a 200
HTTP status code, the notification attempt is repeated. After multiple failures to send the notification over multiple days, MONEI marks the request as failed and stops trying to send it to your endpoint.
#
Before you go live- Make sure that you are using live (production) mode Account ID and API Key.
- Make sure that you have a payment method configured and enabled in live mode.