Charges API

What is “Charges API”?

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

This approach requires some development on the merchant’s side. Once the customer is ready to pay for an order, the website will show the payment form using the “MONEI Widget”. Please refer to our website for more information about it.

Our widget will capture the customer payment details (credit card number, expiration...), and return a payment token. The merchant will then perform an HTTP request with this token and all the information about the order/purchase against our “Charges API”.

The result will be: success, failed or challenge (3D Secure)


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 to have your production account fully verified.

Credentials

Once your account is active, you will find a “Settings” link in the dropdown under your account.

This section has the specifc credentials you need to implement MONEI's payment platform: an Account ID, and a Password (which you will need to calculate signatures).


Overall process

Depending on the type of merchant configuration, there are two (or three) possible flows:

3D Secure 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. Then, you will need to render the MONEI Widget to capture the payment details (credit card number and so). The widget works in the customer's browser, and it will generate a “payment token”.
  3. You will then need to perform a POST request (from your server or the browser) to the Charges URL, sending the returned token along with the Request Params.
  4. MONEI will verify the request data and the signature value (see “How to sign requests”). Please make sure you generate the signature in the backend, without exposing your account credentials.
  5. For 3D Secure operations, we will provide a redirect URL to the challenge. If the request was done by browser (form) instead of server-to-server, we will automatically redirect the user to this challenge.
  6. You will need to send the user to the provided URL, either performing an HTTP 302 redirection, or executing a GET request from the browser (by changing the window.href attribute).
    You will need to send the user to the provided URL, executing a POST request from the browser, along with the provided parameters.
  7. The user will complete the 3D Secure challenge by entering some verification data.
  8. The challenge is completed (successfully or not).
  9. If the challenge was successful, the customer will be redirected 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 it, or if something fails, it will be redirected back to url_cancel.
  10. 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 orders 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.
  11. The order is complete, and you can show a thank-you page to the customer.

Non Secure 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. Then, you will need to render our MONEI Widget to capture the payment details (credit card number and so). The widget works in the user’s browser, and it will generate a “payment token”.
  3. You will then need to perform a POST request (from your server or the browser) to the Charges URL, sending the returned token along with the Request Params.
  4. MONEI will process the payment and verify the request data along with the signature value (see “How to sign requests”). Please make sure you generated the signature in the backend, without exposing your account credentials.
  5. If everything went successfully, the next step will depend on the request content-type header.
    For browser form requests, the customer will be redirected 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 it, or if something fails, it will be redirected back to url_cancel.
    For json requests, the synchronous response will include all the Response Params as a JSON document, including signature (see “How to sign requests”).
  6. 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 orders 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.
  7. The order is complete, and you can show a thank-you page to the customer.

Tokenized 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. Since you already have a payment token for the customer (returned within a previous charge response), you will then need to perform a POST request (from your server or the browser) to the Charges URL, sending this token along with the Request Params.
  3. MONEI will process the payment and verify the request data along with the signature value (see “How to sign requests”). Please make sure you generated the signature in the backend, without exposing your account credentials.
  4. If everything went successfully, the next step will depend on the request content-type header.
    For browser form requests, the customer will be redirected 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 it, or if something fails, it will be redirected back to url_cancel.
    For json requests, the synchronous response will include all the Response Params as a JSON document, including signature (see “How to sign requests”).
  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 orders 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:  saleauthcapturevoid and refunds.

Sales & Auths

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

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

This url takes both server-to-server (using JSON) and frontend/browser (x-www-form-urlencoded) requests. The response will depend on the request’s content-type header.

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 (for Sale & Auth)

For server-to-server JSON requests of a sale or auth operation, the request needs to be done using the same parameters as the rest of the operations (capture/refund/void), but those params will go inside an object called “charge”.

This is because we also need a “ context” parameter with some information about the user, like its IP address and the user agent.

Putting all together (with the Request Params you will find in the next section), your request body will look something like this:

{
  "charge": {
    "payment_token": "7cc38b08ff471ccd313ad62b23b9f362b107560b",
    "transaction_type": "auth",
    "order_id": "aaaa123456",
    "account_id": "c03303a7-8a24-4298-a3a3-545c3205c548",
    "amount": "10.25",
    "currency": "EUR",
     ...
    "signature": "dc09a03fe85a216ad084557aacc154c0382bfe4e0ab96ab958534b98eb2dcdc6"
  },
  "context": {
    "ip": "181.164.214.150",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36"
  }
}

Please keep in mind that you need to generate the signature only using all the parameters that are inside the “charge” object.


Request Params (capture/refund/void)

Key Type Example

account_id Required

Note
: This is the account identifier you can find in your credentials.
string aaaaaaaa-1111-bbbb-2222-cccccccccccc
payment_token Required

Note
: This is the token generated by MONEI Widget (or replied in a previous charge).
string 7cc38b08ff471ccd313b107560b
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 b9afe0588bc3aed8fee92bb7cf6c2d1e1205
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 customer 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 customer 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

Challenge-required response

For server-to-server JSON requests, if a challenge is required, the response will look like:

{
  "redirect_url": "https://pay.monei.net/checkout/321242/challenge"
}

You will then need to redirect the user to the specified URL, using an HTTP 302 redirection or just changing the window.href attribute in the browser.


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 b9afe0588bc3aed8feebaa10b66c2d1e1205
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 either with a JSON request, or using a 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>

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