Application Management for Reseller & Merchants (sub-application)

Background

Within the Yapily ecosystem, all interactions with our API are governed and managed via an association with a customer’s application. Currently, the only way to create an application is through the Console.

Among our clients, we have seen a growing use case of our clients operating AIS and PIS activity on behalf of a given merchant.

Sub-applications

A sub-application is a pseudo-application which operates under the “root” application. The root application stores all bank registrations that can be used by any sub-application that is subordinate to it in the hierarchy. The credentials of the root application are used, along with the sub-application ID in the "sub-application" header, to allow the platform to recognize that the API calls are being made on behalf of the sub-application.

The benefits of operating in this model are:

• Enabling a sub-app to automatically share bank registration and product API scopes without needing to duplicate the configuration across each merchant application
• Provides a mechanism to restrict traffic at a merchant level

Merchant information

As part of the sub-application implementation, we have also introduced additional attributes that can be added to a sub-application. These attributes aim to provide our customers with a mechanism to provide extra information relating to the merchant they are onboarding and using the sub-application for the AIS/PIS activities. These attributes will be:

• Merchant’s full legal entity name
• The Merchant Category Code (MCC) of the merchant
• The Payment Purpose Code user group
• Indicate whether they have conducted KYB on the merchant they are onboarding (also known as the Contract Present Indicator )

Further information about this attribute can be found below:

Payment Purpose Code & User Groups

In October 2021, the Bank of England and Pay.UK issued a joint publication recommending Purpose Codes for use across CHAPS and the New Payments Architecture (NPA). Purpose Codes are four-letter codes which are carried across the payment chain, providing information to all users in the payment chain to indicate the reason a payment is being made. Purpose Codes are one of the policy areas of Enhanced Data that can deliver the benefits of the ISO 20022 payment messaging standard.

Given there are many payment purpose codes that apply to a single merchant, we have opted to initially go a level up and look at the Payment Purpose Code User Groups within this article - Payment Purpose Code & User Groups

Payment Purpose Code user group

• Wholesale / FI-FI
• Commercial
• Consumer / Goods & Services
• Finance
• Salaries & Incomes
• Government
• Insurance
• Property
• Foreign Exchange
• Investments
• Medical
• Benefit payments
• Pensions
• Tax
• Utilities

Merchant Category Code (MCC)

Merchant category codes (MCCs) are four-digit numbers that a credit card issuer uses to categorise the transactions consumers complete using a particular card. Payment brands use merchant category codes to classify merchants and businesses by the type of goods or services provided in order to track and restrict transactions.

Payment brands use merchant category codes (MCCs) to classify merchants and businesses by the type of goods or services provided. Payment brands, issuers and acquirers can use MCCs

to categorise, track and restrict transactions. MCCs can be used for tax reporting, interchange promotion and gathering information about cardholder purchasing behaviour.

Often, MCCs are recognised by all payment brands; however, not all codes are recognised by all brands. Payment brands frequently add, eliminate or change the codes with regularly scheduled enhancements.

Here’s a list of the code ranges for different industries:

• 0001–1499: Agricultural services
• 1500–2999: Contracted services
• 4000–4799: Transportation services
• 4800–4999: Utility services
• 5000–5599: Retail outlet services
• 5600–5699: Clothing stores
• 5700–7299: Miscellaneous stores
• 7300–7999: Business services
• 8000–8999: Professional services and membership organisations
• 9000–9999: Government services

Contract Present Indicator

The Contract Present Indicator indicates whether the PISP has a contractual relationship with the merchant and has undertaken both validation of the recipient account and due diligence on the merchant

Possible values are True or False

A more granular definition:

Setting up a sub-application

Creating a sub-application

• To enable users to manage their applications via an API

Prerequisite

1. Create an application in the Console for which you will associate all of your bank registrations (Yapily Connect or Direct). This will be your Root Application
2. Save the application API credentials (application UUID and secret)

API Flow

1. Call the POST /applications endpoint , using your Root Application credentials.
   1. Provide the following attributes
      1. Merchant Legal Entity Name → “name”
      2. Merchant Category Code → “merchantCategoryCode”
      3. Payment Purpose User Group → “ppcUserGroup”
      4. Contract Present Indicator → “isContractPresent”
      5. Root Application UUID → “rootApplicationId”
2. The response to this call will provide you with a new sub-application ID to be used in the header of all proceeding calls, where the “id” is the sub-application UUID.

Example Request:

{
  "name": "Sub-Application Name",
  "merchantCategoryCode": 7995,
  "ppcUserGroup": "Wholesale / FI-FI",
  "callbackUrls": [
    "https://www.callback-service.com"
  ],
  "isContractPresent": true,
  "rootApplicationId": "eb25e1ee-f6af-4131-92fe-748e177bf950"
}

Example Response:

{
  "name": "Merchant Uno",
  "merchantCategoryCode": 7995,
  "ppcUserGroup": "Wholesale / FI-FI",
  "callbackUrls": [
    "https://www.callback-service.com"
  ],
  "isContractPresent": true,
  "rootApplicationId": "eb25e1ee-f6af-4131-92fe-748e177bf950",
  "id": "84b5a72f-e86c-4fca-9993-aebaa9f92edb"
}

Console Flow

1. Open the Yapily Console
2. Click on Applications
3. Select the application under which you would like to create the sub-application
4. In the application settings page, click on the sub-application tab
5. Click on “ + Create sub-application ”
6. Complete sub-application form, including filling all required merchant information. Once completed, click “ Create ”
7. Once the sub-application has been created successfully, you will see the new sub-application listed in the sub-app table

PLEASE NOTE: If you need to make changes to an existing sub-application, please click on the edit button on the right side of the sub-application table.

Using a sub-application on the Yapily AIS / PIS-related flows

Now that the sub-application has been created, it is available to use for any API functions (as you would for a “normal” application). To enable the platform to be aware that the actions are being carried out on behalf of a sub-application, the following steps must be taken

1. To authenticate, the token must use the application UUID and secret of the Root Application (i.e. the application that the sub-application has been created under)
2. Include a “sub-application” header for all calls, and include the sub-application UUID

The API Specification can be found here - https://docs.yapily.com/api/reference/#tag/Application-Management