Card payments

Bank card payments taken online, either through a hosted payment form or host-to-host from your own form.

Card payments share a host with the Apple Pay and Google Pay pay-ins in this tab, but they are a separate contract with separate credentials: their own api_key / secret_key, their own request format, their own transaction statuses and their own refund flow. None of it applies to the Apple Pay and Google Pay endpoints, or the reverse.

• Statuses: Transaction statuses — not the Payment statuses used by Apple Pay and Google Pay.
• Refunds: Refunds and discards — not the Refunds used by Apple Pay and Google Pay.
• Operations: API Reference.

Card payments is an API that processes bank transactions from the payment cards online.

Features

✅ Ability to choose between Host-to-Host integration or Ready-to-Go payment form.

✅ Support of various payment methods.

✅ Independent processing of full or partial refunds for point-of-sale operators.

Supported Integration Types

1. Ready-to-Go - iFrame-based solution for non-PCIDSS merchants.

   For the payment, customers are being redirected to service provider's servers (either directly or within an iFrame), where they insert all the card data, and the whole payment is being processed there. Merchant's server only receives a callback of a successful/failed transaction afterwards. For that type of integration, merchant can customize the payment form design in the admin panel. See Payment. Ready-to-Go Method.

2. Host-to-Host - simplified integration for PCIDSS-compliant merchants only.

   The customer remains on merchant's website during payment flow execution. The payment form is designed by merchant. Merchant's website submits only a raw transaction data to service provider's servers. The whole payment flow is being executed on merchant's end. For this integration type, merchant is free to design the payment form. The form in the admin panel has nothing to do with this way of integration (therefore there's no way to download it via a js-file, because it was not designed for that purpose). See Payment. Host-to-Host Integration.

Transactions Handling Modes

There are two modes of transactions handling: single-stage and double-stage.

The single-stage (default) mode means that the transaction will go the following simple way:

1. Customer enters payment data.
2. 3-D Secure procedure is performed.
3. Bank makes funds withdrawal.
4. Customer gets the success screen.

The double-stage mode means the flow will go the following way:

1. Customer enters payment data.
2. 3-D Secure procedure is performed.
3. Bank makes authorization of funds (hold).
4. Customer gets the success screen.
5. If merchant decides to deliver the goods/services to the customer, merchant makes capture of funds via API request from merchant's end.
6. Bank makes funds withdrawal.

Testing

Start with the Test environment to:

• Walk through the scenarios.
• Test endpoints.
• Test the transaction operation.

To access the Test environment:

1. Provide your integration manager with the e-mail to be used as a login to the Test environment.
2. Ask your integration manager to provide you with the credentials for use with the Test environment.

Test environment URL: https://pay.mrcr.io/.

Test Environment Payment Card Details

• Card Number: 4111 1111 1111 1111.
• Expiration Date: any future date.
• Use CVV 123 for successful payments without a redirect to 3-D Secure.
• Use CVV 333 for successful payments with a redirect to 3-D Secure (no password is entered).
• Use CVV 222 for failed payments.
• Cardholder Name: name + surname.

Use of Production URL: once integration is ready, ask your integration manager to provide you with the production URL. Provide your integration manager with the e-mail to be used as a login to the Production environment.

Merchant Identification and Signature Generation

Requests and responses, which are passed between the payment gateway and a merchant, are in JSON format and have two main parameters:

• data - a base64-encoded JSON-document as a string, containing request or response details.
• sign - a request signature used in each request and response to protect integration calls from fraud. It is always required, where data parameter is sent.

The signature is generated based on the encoded data value, using the hash_hmac function and the merchant’s shop secret key. The payment gateway validates all incoming requests using the merchant's key, and the merchant must validate all requests from the payment gateway as well.

For the purpose of a merchant identification, all requests to the payment gateway must contain parameter api_key within the data encoded string. For its part, the payment gateway provides api_key in responses and callbacks, which can be used for additional validation and merchant's shop identification.

To obtain both your api_key and secret_key, navigate to your shop in Admin Panel on the My Shops page, and get the values of the api_key and secret_key parameters.

How to Generate Request Signature

1. Prepare:

• Create a JSON-document with the request parameters.
• Get the secret key from your store. To obtain your secret_key, navigate to your store in Admin Panel on the My Shops page, and get the value of the secret_key parameter.

2. Encode:

• Convert the JSON document to a string.
• Encode the string using MIME base64.

3. Generate signature:

• Invoke the hash_hmac function with the "MD5" algorithm.
• Pass the encoded JSON string as the first parameter.
• Pass the secret key as the second parameter.

4. Form sign:

• The hash_hmac value will be the signature.
• Transmit the signature as the sign parameter in your request.

Parameters Validation Rules

The table below describes parameters and allowed values which then form the data string of a payment request:

Example of a source JSON-data for generating the data parameter:

{
  "api_key": "You're api_key",
  "expiration": "2023-09-11 00:00",
  "amount": 333,
  "currency": "EUR",
  "description": "You're description",
  "reference": "123aA",
  "success_url": "http://test.net/success",
  "failure_url": "http://test.net/failure",
  "lang": "en",
  "params": {
    "flag_get_url": 1,
    "pay_token_flag": 1,
    "user_id": "test_user",
    "user_email": "test@gmail.com",
    "af_platform": "The platform from which the order was sent",
    "customer": {
      "address": {
        "city": "San Diego",
        "country_code": "US",
        "line1": "123 Main Street, apt 4A",
        "line2": "San Diego CA, 91911",
        "state_code": "CA",
        "zip_code": "91911"
      },
      "kyc_status": "true",
      "date_of_first_deposit": "2025-01-01",
      "deposits_amount": "30",
      "withdrawals_amount": "3000",
      "deposits_cnt": "999",
      "withdrawals_cnt": "1",
      "firstname": "JACK",
      "lastname": "REACHER",
      "birth_date": "1990-10-10"
    }
  }
}

As a result, the base64-encoded JSON-document and signature (the signature password is "123") get the following variables:

See also Additional Parameters Validation Rules.

Callbacks

Callback messages are sent from the payment gateway to merchant’s website to notify on an order status updates and payment results. The messages are passed as HTTP POST-requests, where two parameters are passed in the body:

• data - a base64-encoded string containing JSON-document;
• sign - a signature which is formed on the basis of the data string using the hash_hmac function to confirm the validity of data.

Example:

Sample below represents content of the data parameter value as a base64-decoded JSON-document:

{
  "transaction_id": "197",
  "reference": "1234567891113",
  "api_key": "c84f1ac0-e4f0-0131-5298-70921c57c2a2",
  "amount": "327.78",
  "currency": "EUR",
  "status": "99",
  "system_amount": "372.48",
  "system_currency": "EUR",
  "commission": "44.7",
  "payment_system_id": "9",
  "payment_system_name": "Citibank EN",
  "card_number": "411111******1111",
  "processing_error_msg": "Wrong auth"
}

Callback Parameters Description

As a response to the callback message from the merchant's website, the following string must be returned: OK. If the merchant's website does not send back the OK string, the payment gateway will regenerate and resend the callback message.

For a single payment order, several transactions can be generated by the payment gateway. As an example: several unsuccessful attempts to pay is made, when the customer makes a mistake while entering card details, or the cardholder has a restriction from the issuing bank. The customer can contact their bank to release the operation restrictions and retry the payment on the payment gateway’s side avoiding redirection back to the merchant's site. Thus, one order can produce several transactions with the error status and, at the end, one with the successful payment status.

Payment. Ready-to-Go Method

This payment method enables for a merchant getting payment form or unique link to it from the service provider's payment gateway. By this, the merchant does not store or process payment card data of a user.

To initiate payment transaction, POST-request for an endpoint [/pay] is sent, and two parameters are passed in the body:

• data - a base64-encoded string containing JSON-document (see details in Parameters Validation Rules and Additional Parameters Validation Rules);

• sign - a signature which is formed on the basis of the data string using the hash_hmac function to confirm the validity of data.

By setting of corresponding parameters, payment flow might differ. Default system behaviour is to provide a payment form where a customer specifies payment card details. By using the flag_get_url parameter, it is possible to get unique URL, which can be then opened in an iFrame, or a customer can be redirected there. See Redirection to a Unique URL.

In case when 3-D Secure verification is required, the response for transaction status request will return the url parameter where the customer must be redirected to.

Additional (Optional) Parameters Validation Rules

The following JSON-parameters and their values can be added to request, to form the data string:

Example of a source JSON-data for generating the data parameter:

{
  "api_key": "c84f1ac0-e4f0-0131-5298-70921c57c2a2",
  "expiration": "2014-01-01 00:00",
  "amount": 327.78,
  "currency": "EUR",
  "description": "test",
  "reference": "123456789",
  "success_url": "http://test.net/success",
  "failure_url": "http://test.net/failure",
  "lang": "en",
  "params": {
    "flag_get_url": 0,
    "user_id": "test_user",
    "user_email": "test@gmail.com"
  }
}

As a result, the base64-encoded JSON-document and signature (the signature password is "123") get the following variables:

Redirection to a Unique URL

It can be requested that a unique URL is needed for redirecting customer without generating a payment page.

Response example when using the flag_get_url = 1 parameter value:

{
  "data": "eyJzZXNzaW9uX2lkIjoiMzA2LWJjZDM2ZjczYmIyMzExYzc0OTkzNjRjYzkxZGNhNTBkYTY5MGZhZDE3OGY1NGRiOWJhMjY3NDYzNWI3MCIsInVybCI6Imh0dHBzOi8vZnAua2ktdGVjaG5vbG9neS5ydS9wYXkvMzA2LWJjZDM2ZjczYmIyMzExYzc0OTkzNjRjYzkxZGNhNTBkYTY5MGZhZDE3OGY1NGRiOWJhMjY3NDYzNWI3MCIsImZsYWdfZ2V0X3VybCI6MSwic2hvcF9hcGlfa2V5IjoiMGE0ZGNhYzAtODUzZS0wMTMyLTkxZmEtMDAxYzE0MDExZGVjIn0=",
  "sign": "2218c4266c183e8448e7ebc500daa23d",
  "success": true,
  "time_proc": "0.0sec."
}

After base64-decoding of the data parameter, there is the following structure:

{
    "session_id":"306-bcd36f73bb2311c7499364cc91dca50da690fad178f54db9ba2674635b70",
    "url":"*/pay/306-bcd36f73bb2311c7499364cc91dca50da690fad178f54db9ba2674635b70",
    "flag_get_url":1,
    "shop_api_key":"0a4dcac0-853e-0132-91fa-001c14011dec"
}

To redirect the customer, the url parameter is used. It renders the payment form. This URL may be redirected to or opened within an iFrame, so that the customer doesn't leave merchant's website.

Note: Before decoding the request, it is recommended to verify the signature.

Payment. Host-to-Host Integration

This integration approach relies collection of cardholder data to the merchant’s side, and for that, merchant must have a PCI DSS certificate.

Payment card details, along with basic parameters, are sent as a POST-request to an endpoint /pay/direct, and two parameters are passed in the body:

• data - a base64-encoded string containing JSON-document;
• sign - a signature which is formed on the basis of the data string using the hash_hmac function to confirm the validity of data.

In case when 3-D Secure verification is required, the response for transaction status request will return the url parameter where the customer must be redirected to.

To form a POST-request for an endpoint /pay/direct, parameters described in Parameters Validation Rules are used, as well as the following cardholder data:

Example of source JSON-data for generating the data parameter:

{
  "api_key": "c84f1ac0-e4f0-0131-5298-70921c57c2a2",
  "expiration": "2014-01-01 00:00",
  "amount": 327.78,
  "currency": "EUR",
  "description": "test",
  "reference": "123456789",
  "success_url": "http://test.net/success",
  "failure_url": "http://test.net/failure",
  "lang": "en",
  "params": {
    "auth_token": "194c7453-9104-4273-a39f-3a055a29a22e",
    "flag_get_url": 1,
    "user_id": "test_user",
    "user_email": "test@gmail.com",
    "ip": "192.168.1.1"
  },
  "card_data": {
    "pan": "4111111111111111",
    "cvv": 123,
    "exp_month": 12,
    "exp_year": 2018,
    "cardholder": "John Doe"
  }
}

As a result, the base64-encoded JSON-document and signature (the signature password is "123") get the following variables:

Example of a decoded response in case of successful payment (without 3-D Secure verification):

{
  "order": {
    "amount": "1.0",
    "api_key": "a696f360-21ee-0135-ccb8-4c32759179bf",
    "authorization_code": "123456",
    "card_number": "555555******5599",
    "card_type": "MASTERCARD",
    "cardholder": "test",
    "commission": "0.0",
    "currency": "EUR",
    "external_reference": "a1ec7d00-4bea-7584-a1ec-7d0000002924",
    "failure_url": "http://localhost:3000/pay",
    "payment_system_id": 18,
    "payment_system_name": "Citibank REST",
    "processing_error_msg": null,
    "reference": "test",
    "status": 3,
    "status_name": "success",
    "success_url": "http://test.com",
    "system_amount": "1.0",
    "system_currency": "EUR",
    "transaction_id": 40850
  },
  "request_id": "9563185958",
  "success": "true",
  "time_proc": "14.78 sec."
}

Example of a decoded response in case of unsuccessful payment (without 3-D Secure verification):

{
  "order": {
    "transaction_id": 40853,
    "reference": "test123",
    "external_reference": "92ecbe1a-dbc9-7459-92ec-be1a00002924",
    "api_key": "a696f360-21ee-0135-ccb8-4c32759179bf",
    "amount": "1.0",
    "currency": "EUR",
    "status": 99,
    "status_name": "error",
    "system_amount": "1.0",
    "commission": "0.0",
    "system_currency": "EUR",
    "payment_system_id": 18,
    "payment_system_name": "Citibank REST",
    "card_number": "555555******5599",
    "cardholder": "test",
    "processing_error_msg": "Operation declined. Please check the data and available balance of the card.",
    "authorization_code": null,
    "card_type": "MASTERCARD",
    "success_url": "http://test.com",
    "failure_url": "http://localhost:3000/pay",
    "processing_error_group_reference": null,
    "processing_error_kind": 0
  },
  "success": false,
  "error": "Operation declined. Please check the data and available balance of the card.",
  "time_proc": "9.74 sec.",
  "request_id": "9563185958",
  "error_msg": "Operation declined. Please check the data and available balance of the card."
}

Example of a decoded response, if it is necessary to redirect payer to the URL for 3-D Secure verification:

{
    "order": {
        "transaction_id": 40854,
        "reference": "test123",
        "external_reference": "c16cf438-6092-7bee-c16c-f43800002924",
        "api_key": "a696f360-21ee-0135-ccb8-4c32759179bf",
        "amount": "1.0",
        "currency": "EUR",
        "status": 0,
        "status_name": "created",
        "system_amount": "1.0",
        "commission": "0.0",
        "system_currency": "EUR",
        "payment_system_id": 18,
        "payment_system_name": "Citibank REST",
        "card_number": "411111******1111",
        "cardholder": "test",
        "processing_error_msg": null,
        "authorization_code": null,
        "card_type": "VISA",
        "success_url": "http://test.com",
        "failure_url": "http://localhost:3000/pay"
    },
    "success": true,
    "url": "http://localhost:3010/redirect/?link_reference=2118437f5e317d505f5b76d09415edf5",
    "time_proc": "7.7 sec.",
    "request_id": "9563185958"
}

If 3-D Secure verification is required, the response will return the url parameter where the customer should be redirected to.

Auth Token for Payment Form

auth_token is a one-time token obtained by means of the script that collects user's fingerprint according to the requirements of higher-level payment systems. auth_token is used for the transaction to identify the merchant/user context. The token lifetime is 10 minutes.

To obtain auth_token, do the following:

1. Add the following script on the page with the payment form (of the merchant or its customer/chain of customers) where card details are entered: <script src="https://gateway-provider.com/./auth_token?token=6f785274-186f-4318-a680-512bebb3d37c"></script>

   • As the token parameter, specify the unique identity token of the store. It can be found in your shop settings of the Admin Panel, where the values of the api_key and secret_key parameters are. It is non-editable and is created automatically for each shop.

As the result of the script invocation, a hidden DIV-element with ID “authToken” will be added to the HTML body of the page.

Example:

<div id=”authToken” style=”display: none;”>027521b9-7f6e-4625-a7e8-12c03f4fd92a</div>

Content of the DIV-element with ID “authToken” must be passed with other parameters to the /pay/direct request. In case of an error, content of the DIV-element will be “false”. New auth_token must be requested for each request, even if an error was caused by some issue from our side.

Additional Parameters. Riskified Integration

To apply additional security measures, it is possible to enable integration with our Antifraud solution. It can be activated only for the merchants who use its own payment form (and send payment requests to /pay/direct). To perform the integration with the Antifraud solution, do the following:

1. Use the JavaScript code below as a template, replace placeholders with actual values:

<script type="text/javascript">
//<![CDATA[
(function() {
  function riskifiedBeaconLoad() {
    var store_domain = '<YOUR DOMAIN>';
    var session_id = 'SESSION ID GOES HERE - as passed to params.af_cart_token';
    var url = ('https:' == document.location.protocol ? 'https://' : 'http://')
      + "beacon.riskified.com?shop=" + store_domain + "&sid=" + session_id;
    var s = document.createElement('script');
    s.type = 'text/javascript';
    s.async = true;
    s.src = url;
    var x = document.getElementsByTagName('script')[0];
    x.parentNode.insertBefore(s, x);
  }
  if (window.attachEvent)
    window.attachEvent('onload', riskifiedBeaconLoad)
  else
    window.addEventListener('load', riskifiedBeaconLoad, false);
})();
//]]>
</script>

where:  store_domain - merchant’s domain; session_id - unique transaction_id in merchant’s web store.

2. Add modified JavaScript code with actual values in merchant’s payment form (HTML).
3. Send the following additional parameters in the request body for /pay/direct.

Example of a source JSON-data for generating the data parameter:

{
  "api_key": "Your api_key",
  "expiration": "2023-09-11 00:00",
  "amount": 333,
  "currency": "EUR",
  "description": "Your description",
  "reference": "123aA",
  "success_url": "http://test.com/success",
  "failure_url": "http://test.com/failure",
  "lang": "en",
  "card_data": {
    "pan": "4111111111111111",
    "cvv": 123,
    "exp_month": 12,
    "exp_year": 25,
    "cardholder": "JOHN DOE"
  },
  "params": {
    "flag_get_url": "1",
    "verification_flag": "0",
    "af_cart_token": "Your af_cart_token",
    "af_platform": "The platform from which the order was sent",
    "user_email": "test@gmail.com"
  }
}

Withdrawal

Withdrawal of funds which were put on hold.

This operation is possible for transactions with status = 1 (authorize (lock amount)).

POST-request for an endpoint /pay/complete where two parameters are passed in the body:

• data - a base64-encoded string containing JSON-document;
• sign - a signature which is formed on the basis of the data string using the hash_hmac function to confirm the validity of data.

The following JSON-parameters and their values form the data string:

Example of an initial JSON-data to form the data parameter:

{
  "api_key": "318dacc0-c571-0132-d48f-448a5b8820f8",
  "transaction_id": "2299"
}

Example of a decoded JSON-response:

{
  "order": {
    "transaction_id": 2299,
    "reference": "1473747103",
    "api_key": "318dacc0-c571-0132-d48f-448a5b8820f8",
    "amount": "327.78",
    "currency": "EUR",
    "status": 3,
    "status_name": "success",
    "system_amount": "327.78",
    "commission": "0.0",
    "system_currency": "EUR",
    "payment_system_id": 1,
    "payment_system_name": "CitibankB2b (TEST)",
    "card_number": "411111******1111",
    "processing_error_msg": null
  },
  "success": true,
  "time_proc": "1.2sec."
}

Customization

In case of an "iFrame" integration, there are two ways of how to configure the payment form display:

1. (Preferrable) Prepare a CSS file, which may slightly alter colors, elements positioning, etc. Once the CSS file is ready, supply the admin-panel-generated webform with the CSS file. Service provider's server binds it to your form via its backend admin panel.

2. Prepare custom HTML layout via parsing the admin-panel-generated form and customizing it. After that, service provider's server is able to upload it there on backend. Any customization via admin panel will become unavailable then.

It is not possible to customize the 3-D Secure verification form view, because it is generated on the bank issuer side.