Hosted Payments API

What is “Hosted Payments”?

It is one of the existing ways to implement a Payment Gateway solution (like MONEI) from any website, CMS, or e-commerce platform.

The procedure is quite simple: the website will prepare an order (or request), and  delegate the very last step (charge) to the payment gateway (MONEI). The user/consumer will enter the payment details (credit card number and so) in our platform, and then they will be redirected back to the merchant’s website, along with some details about the result of the operation (whether it was successful or not).


Requirements

For a merchant/customer to start using MONEI, it will require some previous steps.

Merchant or Webmaster Account

The first step is getting an active account. For that, you will need to register, follow the onboarding process and upload the required documents

Credentials

Once your account is active, you will find a “ Settings” button under your account.

Under this section are specified the credentials you will need to implement our payment platform: an Account ID, and a Password (which you will need to calculate signatures).


Overall process

  1. The customer places an order (or a cart checkout) in your platform. They will enter their email, shipping address, delivery method, and any other information you require.
  2. On the last step, you will need to do a POST request to the Checkout URL, along with the Request Params in the x-www-form-urlencoded format. MONEI will verify the signature value and reply with the HTML that should be shown to a customer.
  3. The customer pays for the order and validates with the bank through the 3D Secure process.
  4. Customers that complete the payment flow will be redirected back to url_complete with all the Response Params as query parameters, including signature (see “How to sign requests”). If a visitor cancels the payment flow before successfully completing the same, it will be redirected back to url_cancel.
  5. For performance and security reasons, we support asynchronous callbacks. This means that after everything is finished, we will notify you about the result using an HTTP POST request to the url_callback, with the same Response Params. This ensures that checkouts can be completed even in cases where the customer's connection is terminated prematurely. Callbacks parameters are in x-www-form-urlencoded format.
    We expect an HTTP 200 response to indicate us the successful receipt of the callback. Otherwise, we will continue with our retrial process, until we reach 10 failed requests.
  6. The order is complete, and you can show a thank-you page to the customer.


Transactions & URLs

We currently support 5 different types of transactions: sale, auth, capture, void and refunds.

Sales & Auths

URL

https://pay.monei.net/checkout

These two operations are quite similar and share all the same Request Params, except for the transaction_type.

The main difference is that a “ Sale” transaction will instantly charge the customer, while an “Auth” operation will only check if the payment information is valid and retain/freeze the amount of money until you decide to capture the payment (or void it).

Captures & Voids

URL

https://api.monei.net/v1/capture

https://api.monei.net/v1/void

In order to finish an “auth” process, you will need to execute either a “Capture” or a “Void” operation. The “capture” action will take the previous auth, and convert it into a charge. Whereas a “void” transaction will cancel the “auth” and release the retained money in the customer’s credit/debit card.

It is important to mention that an authorized transaction can only be captured once, and also that the captured amount can be equal or less than the one previously authorized.

Please refer to the “ Request Params” section to check which values are required in Capture or Void request.

Refunds

URL
https://api.monei.net/v1/refund

After a successful “sale” or “capture”, a charge is placed. At this point, the only way to “go back” is to do a refund.

Calling the refund endpoint will require you to specify which charge you want to refund. This will take that previous charge, and return to the customer the specified amount.

On the very same charge, it is possible to do either a full refund or many partial refunds, until the whole amount is refunded. Please refer to the “Request Params” section to check which values are required in a refund request.


Request Params

Key

Type

Example

account_id Required

Note: This is the account identifier you can find in your credentials.

string

aaaaaaaa-1111-bbbb-2222-cccccccccccc

amount Required

decimal

19.99

currency Required

iso-4217

EUR

order_id Required

Note: Unique reference or identifier of an order assigned by the merchant.

string (1-32)
[a-zA-Z0-9]

X25921

checkout_id Required for captures, voids and refunds

Note: Unique identifier previously provided by monei during an auth or sale operation.

string

a991c3df2afebbbda26d1d72ff8818a0

shop_country Required

iso-3166-1alpha-2

ES

shop_name Required

string

Goods & Stuff Inc

signature Required

Note: See How to sign requests.

hex string, case-insensitive

b9afe0588bc3aed8fee92bb7cf4b4ae94c   

test Required

Note: Indicates whether or not this request should be processed in test mode.

true/false

true

url_callback Required

Note: URL to which a callback notification should be sent asynchronously.

url

https://mysite.com?callback=1

url_cancel Required

Note: URL to which customers must be redirected when they wish to quit payment flow and return to the merchant's site.

url

https://mysite.com?cancel=3

url_complete Required

Note: URL to which customers must be redirected upon successfully completing payment flow. Known as “thank you page”.

url

https://mysite.com?completed=2

transaction_type Required

Note: The valid values are sale, auth, capture, refund and void.

fixed choice

capture

customer_billing_address1

string

5th Avenue

customer_billing_address2

string

customer_billing_city

string

Paris

customer_billing_company

string

acme inc

customer_billing_country

iso-3166-1 alpha-2

FR

customer_billing_phone

string

+34-655-12-21-33

customer_billing_state

string

Soho

customer_billing_zip

string

AFT123

customer_email

string

john.doe@example.com

customer_first_name

string

John

customer_last_name

string

Doe

customer_phone

string

+34-655-12-21-33

customer_shipping_address1

string

Avenida Prueba 123

customer_shipping_address2

string

customer_shipping_city

string

Madrid

customer_shipping_company

string

acme inc

customer_shipping_country

iso-3166-1 alpha-2

FR

customer_shipping_first_name

string

John

customer_shipping_last_name

string

Doe

customer_shipping_phone

string

+34-655-12-21-33

customer_shipping_state

string

Madrid

customer_shipping_zip

string

AFT123

description

string

Order #123

invoice

string

#123


Response Params

Key

Type

Example

account_id

Note: Echo request's account_id

string

aaaaaaaa-1111-bbbb-2222-cccccccccccc

amount

Note: Echo request's amount

decimal

19.99

currency

Note: Echo request's currency

iso-4217

EUR

checkout_id

Note: Unique identifier for each response.

string

a991c3df2afebbbda26d1d72ff8818a0

order_id

Note: Echo request's order_id

string

X25921

result

Note: Valid values: completed, failed and pending.

fixed choice

completed

signature

Note: See How to sign requests.

hex string, case-insensitive

b9afe0588bc3aed8fee92bb7cf4b4ae94c

message Optional

Note: A custom error message displayed to the customer.

string

Incorrect payment details.


If more information about the checkout is required, please refer to the “Checkout Details” API.


How to sign requests

To ensure security in the whole process, all requests and responses must and will be signed/verified using the HMAC-SHA256 algorithm.

This means that we expect to find in the params/body of every request a “ signature” field, which we will validate against our own. And we will also send signed requests/responses to our customers, which they should also validate.

Calculation

To calculate this “signature” field, you will require the “ password” you got along with your “Account ID” (this value is known by both MONEI and you).

First, we will generate a “message”, which is a  string of all key-value pairs of the request/response params (besides signature), sorted alphabetically and concatenated without separators.

You will then pass this “ message” to the HMAC algorithm, along with the “password”.

The resulting code must be hex-encoded and passed as the value of the “signature” parameter. Make sure to use case-insensitive comparison when verifying the provided signature values.

Example

In this example we assume you want to perform an “auth” operation, and that your password is “asd123fgh”. The signing mechanism would look like this:

const request_data = {
  transaction_type: 'auth',
  order_id: '1234',
  account_id: 'aaaaaaaa-1111-bbbb-2222-cccccccccccc',
  amount: '1.20',
  currency: 'EUR',
  url_callback: 'https://mysite.com?callback=1',
  url_complete: 'https://mysite.com?completed=2',
  url_cancel: 'https://mysite.com?cancel=3'
};

const message = Object.keys(request_data)
  .sort()
  .reduce((final, key) => {
    final += `${key}${request_data[key]}`;
    return final;
  }, '');

// message will look like
// account_idaaaaaaaa-1111-bbbb-2222-ccccccccccccamount1.20currencyEURorder_id1234testtruetransaction_typeauthurl_callbackhttps://mysite.com?callback=1url_cancelhttps://mysite.com?cancel=3url_completehttps://mysite.com?completed=2

const password = 'asd123fgh';

const signature = crypto
  .createHmac('SHA256', password)
  .update(message)
  .digest('hex');

 
// signature will be
// 4451903f1c037e18dd53b8b8e2a759b3673f5c076ab9cb88ab652d31d1950b6a

Then you can submit your request using simple HTML form like this: 

<form action="https://pay.monei.net/checkout" method="POST">
      <input type="text" name="transaction_type" value="auth" hidden>
      <input type="text" name="order_id" value="1234" hidden>
      <input type="text" name="account_id" value="aaaaaaaa-1111-bbbb-2222-cccccccccccc" hidden>
      <input type="text" name="amount" value="1.20" hidden>
      <input type="text" name="currency" value="EUR" hidden>
      <input type="text" name="url_callback" value="https://mysite.com?callback=1" hidden>
      <input type="text" name="url_complete" value="https://monei.net/complete" hidden>
      <input type="text" name="url_cancel" value="https://monei.net/cancel" hidden>
      <input type="text" name="signature" value="4451903f1c037e18dd53b8b8e2a759b3673f5c076ab9cb88ab652d31d1950b6a" hidden>
      <button type="submit">Submit</button>
</form><br>

When a customer submits the form he will be redirected to a payment page.

Testing

Make sure that you are using test account credentials.

Accepted card:

  • Number:  4548 8120 4940 0004
  • Expiration: 12/20
  • CVV2 code: 123
  • In 3d mode (CES), in which buyer authentication is required, the personal identification code (CIP) is: 123456

Rejected card:

  • Number:  5576 4400 2278 8500
  • Expiration: 12/20
  • CVV2 code: 123
  • In 3d mode (CES), in which buyer authentication is required, the personal identification code (CIP) is: 123456
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us