InCountry Payment Gateway Documentation

About

Payment Gateway is a part of the InCountry platform. This solution lets you secure payment card data within your application when performing outbound requests or handling incoming payment requests. It enables you to securely collect payment card data and store it on the InCountry platform with the dedicated JavaScript library (Payment Elements). It automates the provision of credit card data in the aliased (redacted) form to third-party payment providers depending on your business requirements. You can easily customize the solution for automated data exchange and integrate it into your application with minimal development efforts.

Solution integration flow

Integration of Payment Gateway into your application includes the following stages:

Secured collection of payment card data in your application interface. At this stage, you need to integrate the JavaScript library into your application frontend. This allows you to securely collect payment card data of your customers through payment forms without processing this data by your systems. Fields on payment forms operate like traditional input fields while they secure access to this sensitive financial data.
Secured saving of payment card data to the InCountry platform and redaction of clear-text data into aliased equivalents. Aliased payment card data is useless for malefactors and hackers even if it is compromised, lost, or stolen. InCountry Border securely processes and saves payment card data to the InCountry platform and generates aliases for it.
Secured provision of payment card data to payment providers on demand. Once the payer creates a first record on the InCountry platform, InCountry Border unredacts the aliased payment card data and provides it to a specific payment provider.

Collecting payment card data

You need to integrate the InCountry’s Payment Elements library into your application frontend. This component adds an IFrame element that renders a payment form loaded from the InCountry domain, so your application has no access to payment card data, which is required by PCI DSS.

Storing payment card data

The payment form is rendered in the browser with the JavaScript library (Payment Elements) that passes the payment card data to InCountry Border.
InCountry Border securely saves the payment card data to the InCountry platform.
InCountry Border redacts this data with provider-agnostic alpha-numeric tokens. This data by itself cannot be used even if it is lost, compromised, or stolen. Then InCountry Border passes redacted data to your application backend to a specifically defined endpoint in your application. Neither InCountry Border nor your application backend stores a CVC code in any form (plain, encrypted, or redacted).
Your application backend generates an identification token (entity id) and saves it to your application database for this card data record and returns an entity id in the response within the x-inc-entity-id field.
InCountry Border updates the record on the InCountry platform with the generated entity id.
InCountry Border returns the created entity id to the browser.

Providing data to payment providers

Your application from the browser sends an entity id and CVV/CVC to its backend.
Your application backend sends a request containing an entity id, CVV/CVC, and authorization credentials through InCountry Border to the payment provider to get a token object that represents the payment card data.
InCountry Border fetches the payment card data by its entity id from the InCountry platform.
InCountry Border fills out the payload with original payment card data in the pre-defined request format that is required by a payment provider and passes this request to the payment provider.
The payment provider returns a token object.
InCountry Border passes this token object to your application backend.
Having the payment provider credentials, token object, and other payment parameters, your application backend creates a payment transaction for the payment provider.
The payment provider returns the result for a created transaction.
Your application backend returns the transaction result to the application frontend.

Processing CVV/CVC codes

The InCountry platform does not store CVV/CVC codes. Payment Gateway passes a CVV/CVC code as plain text over a secure HTTPS connection. This code may go through your application backend through the GET request, that’s why such approach is PCI DSS compliant as the CVV/CVC code is just passed and is not stored. The same approach is also used by InCountry Border.

Integrating the Payment Elements library into the payment workflow

The Payment Elements library includes the two parts:

code that is integrated into your application page to interact with the Payment Elements library.
code that is loaded within an IFrame element (XSS protection) to manage the form elements data, styles, validation, and so on.

Integrating the Payment Elements library with application frontend

The generic workflow includes the following steps:

Include the Payment Elements script on each page of a website. It should always be loaded directly from the InCountry endpoint, rather than included within an application bundle or hosted on your premises.
Add a placeholder for the payment form.
Initialize the library.
Create a payment form.
Submit the payment card data.
Get the card’s entity id and CVV.

A path to the payment page should look like https://your.server.io/payment.

<!--
1. Include the Payment Elements script
-->
<script src="{BORDER_PAYMENT_ELEMENTS_URL}/static/elements.js"></script>

<!--
2. Add a placeholder for the payment form
-->
<span id="placeholder">
 <!--iframe will rendered here-->
</span>

<script>
  /// 3. Initialize the library
  InCountry.initialize({ url: 'BORDER_IFRAME_URL' });

  /// 4. Create a payment form
  var cardForm = InCountry.form('#placeholder');

  /// 5. Submit the payment card data
  cardForm.submit(function(entityId, CVV) {

  /// 6. Get the card entity id and CVV

    fetch('https://your.server.io/buy', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ card: entityId, CVV }),
      })
      .then(response => {
        var data = response.json();

        if (data.message) {
          // some actions here...
          // ...
        }

        // If 3ds flow
        if (data.redirect_url) {
          window.location.href = data.redirect_url;
        }
      });
  })
</script>

Submitting payment card data

When the cardFrom.submit() function is called the request with payment card data goes through InCountry Border that redacts this data. Then the request with redacted payment card data comes to your server to the POST /cards endpoint. On your server, the redacted payment card data can be linked to a specific user, etc. The POST /cards method should return a unique entity id in the JSON response.

Then an entity id and CVV can be passed to the server. In the example above, a request is performed tohttps://your.server.io/buy.

CVV is passed in the plain text form from the cardForm function.

cardForm.submit(function(entityId, CVV) {
  // ...
});

Creating an IFrame with Payment Elements

The IFrame path should look like: ${BORDER_URL}/x-inc-${customerName}/${????}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Form</title>
  </head>
  <body
    data-submit-url="<%= submitURL %>"
    data-entity-id-prop="<%= entityIdProp %>"
  >
    <script src="/static/elements-internal.js"></script>

    <!-- This HTML is generated -->
    <form>
      <input> </input>
      ...
    </form>
    <!--/ This HTML is generated -->
  </body>
</html>

Client-side validation

The client-side validation is implemented on the basis of the https://github.com/medipass/react-payment-inputs JavaScript library.

This library validates the following:

card number:
1. payment card number
2. Luhn algorithm
3. length of the payment card number
expiry date:
1. date format
2. validity of the card (non-expired date)
card’s СVС code:
1. number format
2. code length up to 4 digits

Server-side validation

Each payment provider has its own payment data validation. As InCountry Border only passes requests to the payment provider and in some cases may store, redact, and unredact the payment card data, all backend validation is implemented by the payment provider.

Upon the passed client-side validation, the payment provider’s backend may return a payment data error. By knowing the entity id, InCountry Border can update the invalid payment card data on the InCountry platform by itself as of the moment of redacting/unredacting data.

Integrating Stripe with Payment Gateway

This section provides instructions on how to integrate Payment Gateway with Stripe.

Without InCountry Payment Gateway

Stripe Elements in your application frontend collect the payment card data.
Stripe Elements send the payment card data to the Stripe’s /tokens endpoint to get the token object that represents a payment card. For the details, please see the create card token article in the Stripe documentation.
With the token object, the application frontend fetches data from its backend, gets the Stripe credentials, and initiates a payment.
Stripe returns the result of the payment transaction.
The application backend returns the transaction result to the application frontend.

With InCountry Payment Gateway

To make a payment transaction in Stripe, you need to create a token object through the Stripe’s /tokens endpoint that represents the payment card data. To create it, you need to pass an entity id to the /tokens endpoint through InCountry Border that will fill out the request payload with payment card data in the pre-defined format,. Then Stripe will create a token and return it back. With that token object, you can charge money from your customers, create recurrent payments, or make direct requests to Stripe.

The following diagram shows the payment flow when using Payment Gateway with Stripe:

With InCountry Payment Gateway

Example of using Stripe API with InCountry Payment Gateway

Below you can find an example of how to create a token object (with payment card data) for your application backend (the POST /buy endpoint) at InCountry Border. For example with Node.js using axios:

const axios = require('axios');
const querystring = require('querystring');

app.post('/buy', async function(req, res) {
  const entityId = req.body['x-inc-entity-id']
  const cardCvc = req.body.cardCvc

  const a = axios.create({
    baseURL: `${INCOUNTRY_BORDER_URL}`,
    headers: {
      'Authorization': `Bearer ${STRIPE_SECRET_KEY}`,
      'Content-Type': 'application/x-www-form-urlencoded',
    }
  });

  // Here the request to Stripe will go through InCountry Border and empty strings will be filled out by Border.
  const token = await a.post('tokens', querystring.stringify({
    entityId,
    'card[number]': '',
    'card[exp_month]': '',
    'card[exp_year]': '',
    'card[cvc]': cardCvc,
  }));


  // some more actions
  // ...

});

The request to the Stripe’s /tokens endpoint will go through InCountry Border which will unredact the redacted payment card data and pass it to Stripe for performing a payment transaction.

Moving from one payment provider to another

You may want to add support for another payment provider besides Stripe. InCountry Border provides provider-agnostic aliases which enable the routing of payment traffic to any number of payment providers you work with. You do not need to use your own credentials and secure the sensitive data yourself.

Data retention and deletion

Records with payment card data can be removed on demand and according to our data retention policy (pt. 9.3).