Skip to main content

Payments

Table of сontents

The Payments service utilizes the Payment Vault component which is a part of the InCountry Data Residency-as-a-Service. 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.

Creating a new Payments service​

note

You can create one Payments service per each activated country within an environment.

  1. On the menu, select Environments.

  2. On the opened list with environments or on the sidebar, select the environment where you want to create the Payments service.

  3. On the opened list with countries or on the sidebar, select the country where you want to create the Payments service.

  4. On the list with services, click Add service.

  5. At the Select service step, select Payments.

  6. Click Next.

  7. At the Payment Provider step, define the following parameters:

    1. Payment Provider - select the payment provider from the list (for example, Stripe or Braintree).

    2. Request - leave this parameter as-is, the POST request type is used by default.

    3. Application payment endpoint - enter the path to the endpoint which payment card data is submitted to.

  8. Click Next.

  9. At the Review step, review the configuration of a new Payments service.

  10. Enter the verification code and click Save.

  11. At the Embed Code step, copy the embed code of the payment form that will save payment card data to the InCountry Vault.

  12. When complete, click Close.

Solution integration flow​

Integration of the Payments service into your application includes the following stages:

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

  2. 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. Payment Vault securely processes and saves payment card data to the InCountry platform and generates aliases for it.

  3. Secured provision of payment card data to payment providers on demand. Once the payer creates a first record on the InCountry platform, Payment Vault unredacts the aliased payment card data and provides it to a specific payment provider.

Collecting payment card data​

You need to integrate 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​

  1. The payment form is rendered in the browser with the JavaScript library (Payment Elements) that passes the payment card data to Payment Vault.

  2. Payment Vault securely saves the payment card data to the InCountry platform.

  3. Payment Vault 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 Payment Vault passes redacted data to your application backend to a specifically defined endpoint in your application. Neither Payment Vault nor your application backend stores a CVC code in any form (plain, encrypted, or redacted).

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

  5. Payment Vault updates the record on the InCountry platform with the generated entity id.

  6. Payment Vault returns the created entity id to the browser.

Providing data to payment providers​

  1. Your application from the browser sends an entity id and CVV/CVC to its backend.

  2. Your application backend sends a request containing an entity id, CVV/CVC, and authorization credentials through Payment Vault to the payment provider to get a token object that represents the payment card data.

  3. Payment Vault fetches the payment card data by its entity id from the InCountry platform.

  4. Payment Vault 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.

  5. The payment provider returns a token object.

  6. Payment Vault passes this token object to your application backend.

  7. Having the payment provider credentials, token object, and other payment parameters, your application backend creates a payment transaction for the payment provider.

  8. The payment provider returns the result for a created transaction.

  9. 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 Vault 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 Payment Vault.

Integrating the Payment Elements library into the payment workflow​

The Payment Elements library includes the two parts:

  1. code that is integrated into your application page to interact with the Payment Elements library.

  2. 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:

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

  2. Add a placeholder for the payment form.

  3. Initialize the library.

  4. Create a payment form.

  5. Submit the payment card data.

  6. 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 Payment Vault 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:

  1. card number:

    1. payment card number

    2. Luhn algorithm

    3. length of the payment card number

  2. expiry date:

    1. date format

    2. validity of the card (non-expired date)

  3. 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 Payment Vault 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, Payment Vault 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 Vault​

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

Without InCountry Payment Vault​

  1. Stripe Elements in your application frontend collect the payment card data.

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

  3. With the token object, the application frontend fetches data from its backend, gets the Stripe credentials, and initiates a payment.

  4. Stripe returns the result of the payment transaction.

  5. The application backend returns the transaction result to the application frontend.

With InCountry Payment Vault​

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 Payment Vault 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 Vault with Stripe:

Example of using Stripe API with InCountry Payment Vault​

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