FAQs

What is my ProgrammeKey?

The ProgrammeKey is your Access Token to use our APIs. It will be secured in the near future, but at the moment it is made up of your <tenantId>|<programmeId> in plain text. Since each Developer is considered a Tenant, but each Tenant can have more than one Programme, you will have a ProgrammeKey for each Programme you create, however they will all begin with the same numeric value before the | symbol.

An example of a ProgrammeKey is 98227246543536128|98244121150488576, where 98227246543536128 is the Tenant ID and 98244121150488576 is the Programme ID.

Your ProgrammeKey is displayed both at the end of the Programme Create Wizard process, as well as in the View More section of your Manage Staging Programme page, both of which are in the Sandbox UI.

What is a Profile?

Once the Developer develops the Application and publishes it, the Programme Manager can create multiple instances, called Programmes, for each of its clients. The Programme Manager can define client-specific configuration and variations for each of such clients. Infact within a Programme, for each Paylet, a configuration, called a Profile can be created. If the Payment Model defines a Managed Card, then the Programme Manager can define Managed Card configurations (called Profiles) for its clients. For instance, a Profile could specify that cards issued through such a Profile have to be issued under the Visa card scheme and that the maximum balance on the card is GBP500.

One can define multiple Profiles for a single Paylet within a Programme.

Within APIs and REST calls, a Profile is referred through the Profile ID.

How do I deposit funds into the system?

Currently funds can be deposited through bank transfer (bank pay-in). In a real-life Application, the way this would happen is that the corporate user executes a bank transfer transaction – on the Application. This returns a unique identifier (and destination bank account details) that is then quoted when the user is doing the bank transfer from his bank’s portal.

During development, we simulate this process through a two-step process:

  1. First, we simulate the ‘availability’ of funds in the external bank account. As you appreciate this is not applicable on a production system
  2. Second, we execute the actual deposit transaction (the one which we would have executed in a real-life scenario).

First, instantiate an instance of External Account, which represents the external bank account. This can be accomplished by performing a POST request on /external_accounts/_/create, which accepts a request of the following format:

{
  // The ID of the external account profile from which to create the account
  "profileId": "12345",

  // The ID of the corporate identity that will own this external account
  "ownerId": "45678",
  "friendlyName": "My external account",
  "externalAccountInfo": {
    "bankAccountNumber": "31926819",
    "payee": "Mr John Doe",  // The owner of the bank account
    "bankName": "Bank of Europe", // The name of the bank
    "bankCode": "NWBK",
    "branchCode": "601613",
    "accountType": "Savings",
    "checkDigits": "29",
    "ibanCode": "GB29NWBK60161331926819",
    "swiftCode": "ABCDEF12",
    "branchAddress": "Bank of Europe, London, UK",
    "country": "GB",
    "additionalInformation": "Any additional information goes here",
    "currency": "GBP"
  }
}

Once an instance of the External Account has been created, we can simulate availability of funds by performaing a POST request on /payin_simulator/_/payin using the following body:

{
  "amount": {
    "currency": "GBP",
    "amount": "10000" // The payin amount
  },

  // The ID of the external account on which funds should be deposited
  "externalAccountId": "15616498849",
  "additionalInfo": "Any additional information goes here"
}

Once the funds have been credited to the External Account, the next step is to execute a transaction to deposit the funds onto a Managed Account. This can be achieved by performing a POST request on /deposits/_/create_from_external_account, using the following request body:

{
  // The ID of the deposit profile that should be used for this transaction
  "profileId": "12345",

  "amount": {
    "currency": "GBP",
    "amount": "10000"
  },

  // The ID and type of the external account
  "sourceInstrumentId": {
    "type": "external_accounts",
    "id": "4567891802"
  },

  // The ID of the payin returned when creating the payin earlier
  "sourcePayinId": "12345",

  // The ID and type of the managed account on which funds are to be deposited
  "destinationInstrumentId": {
    "type": "managed_accounts",
    "id": "5489468489"
  }
}

After execution of the above you should now have funds loaded onto a Managed Account instance. Make sure to replace the respective IDs in the above calls with the Profile Identifiers defined in the ‘Getting Started’ document.

How do I simulate a purchase happening on a Virtual Card?

The typical process that happens when a card is used to perform a purchase at a merchant consists of two phases. First, when the user presents the card to the merchant (e.g. amazon.com), the merchant sends an Authorisation request across the card scheme of the card (Visa or MasterCard). Such authorisation reserves funds from the card's Available Balance. One or more days later, a separate process, called Settlement completes the Authorisation request and funds are deducted from the card's Actual balance (with a corresponding transaction entry showing the merchant where the funds were spent being generated). OPC provides a mechanism to simulate a Purchase through calling POST on /card_issuing_simulator/purchase, with a request in the below format:

{
  "cardId": "33333",  // The ID of the managed card
  "purchaseAmount": { // The purchase amount, should be negative
    "currency": "GBP",
    "amount": "-2500"
  },
  "merchantName": "Sample Merchant"
}

For the developers that want to provide an enhanced user experience (distinguishing between available and actual card balance) OPC provides separate simulation of the Authorisation and Settlement requests by POST calls on the following URLs:

  • /card_issuing_simulator/authorisation - simulates an Authorisation request

    {
    "details": {
      "providerAuthorisationEntryId": "11111",
      "providerTransactionId": "22222",
      "authorisationType": "PURCHASE",
      "transactionType": "SALE_OR_PURCHASE",
      "transactionTimestamp": "1490265534121",
      "providerProcessingTimestamp": "1490265510822",
      "instrumentId": "33333",  // The ID of the managed card
    
      // The transaction amount - should be negative in a purchase
      "transactionAmount": {
        "currency": "GBP",
        "amount": "-2500"
      },
    
      // The amount billed to the card - should be negative in a purchase
      "billingAmount": {
        "currency": "GBP",
        "amount": "-2500"
      },
      "merchantId": "75031",
      "merchantName": "Sample Merchant",
      "merchantCategoryCode": "123"
    },
    
    // The key of the provider that processed the authorisation
    "providerKey": "CardProvider"
    }
    
  • /card_issuing_simulator/settlement - simulates a Settlement request

    {
    "details": {
      "providerSettlementEntryId": "44444",
      "transactionTimestamp": "1490265534121",
      "providerProcessingTimestamp": "1490265534100",
      "instrumentId": "33333",  // The ID of the managed card
    
      // The transaction amount - should be negative in a purchase
      "transactionAmount": {
        "currency": "GBP",
        "amount": "-2500"
      },
    
      // The amount billed to the card - should be negative in a purchase
      "billingAmount": {
        "currency": "GBP",
        "amount": "-2500"
      },
      "merchantSettlement": {
        "transactionType": "SALE_PURCHASE",
        "providerTransactionId": "55555",
    
        // Should match the provider authorisation entry ID of the auth
        "relatedProviderAuthorisationEntryId": "11111",
    
        // Should match the provider transaction ID of the auth
        "relatedProviderAuthorisationTransactionId": "22222",
    
        "merchantId": "75031",
        "merchantName": "Sample Merchant",
        "merchantCategoryCode": "123"
      }
    },
    "providerKey": "CardProvider"
    }
    

What are the type keys for the various instrument types?

When executing a transaction to move funds (e.g. Deposit, Withdraw or Transfer), the developer is required to enter the ‘type’ for the source and destination instruments. The ‘type’ keys for the different types of instruments are as follows:

  • external_accounts - this refers to an External Account (external bank account) instrument
  • managed_accounts - this refers to a Managed Account instrument
  • managed_cards - this refers to a Managed Card instrument

These types must be passed as is when trying to reference an instrument of the respective type.

What are the headers required for API calls?

The headers required with every request in the APIs are the following:

  • X-callref - A unique call reference you generate to track API calls. Make sure you use a different reference every time as otherwise the request will not be processed.
  • X-programmeKey - See What is my ProgrammeKey? section in FAQs
  • Authorization/token - This is the authorisation token that you receive after logging into the API with your credentials. To login, you need to perform a POST call on /auth/login with your credentials.

What's the format of dates returned by the APIs?

The OPC APIs returns timestamps that are similar to standard UNIX epoch timestamps, but they use millisecond precision instead of seconds, unless otherwise stated in the API itself.

What's the difference between a 200 and a 201 response from an API?

Most of the OPC APIs are designed to be idempotent - this means that when performing an action with the same intent multiple times, the action is only carried out once. For example, when creating a Virtual Card with the same ID multiple times, it is only created on the first call. Subsequent calls will return the card created in the first request. This allows operations to be retried easily in case the outcome of the call is unknown. In order to indicate whether the action requested in the call was carried out during a specific request or a previous request, the OPC APIs make use of the 200 and 201 response codes. When the request causes some entity to be created or updated in this specific call, the API returns a response code of 201 OK_PERSISTED. If instead the request was already processed before (and thus no changes have been applied for this call) then the response code 200 OK is returned.

In order to indicate whether the action requested in the call was carried out in this particular request, or whether it was done previously, the OPC APIs make use of the 200 and 201 response codes. When the request causes some entity to be created or updated in this specific call, the API returns a response code of 201 OK_PERSISTED. On the other hand, if the request was already processed beforehand, and this particular call caused no changes, then the response code 200 OK is returned.

What is the UX framework and do I need to use the Ixaris UX Framework to develop my application?

The UX framework is a library based on REACT that provides various interesting capabilities to a UI developer. The use of the UX framework is recommended:

  1. when the Application needs to embed pages within the OPC interfaces itself (such as the Programme Manager portal)
  2. when the application needs to show sensitive information, such as card numbers and CVV2, throughout any of its interfaces.

The use of the UX framework is optional first because the capability to extend the Programme Manager portal is not available and secondly because the Virtual Card details are being used on a staging environment only.

How do I retrieve the count of entities matching certain criteria?

The OPC API resources define a GET that accepts a filter which returns a paged list of entities from that resource that match the given criteria. In order to obtain the total count of entities that match the criteria, the filter accepts a 'count' boolean in the 'paging' field of the request. If this is set to 'true', then the count all entities that match the given filter is returned. If the 'count' boolean is not set, the count will also be returned, but it will always be zero.

What is Swagger?

Swagger is an open source API framework that allows us to describe the REST APIs offered by the OPC platform. Swagger offers a number of features designed to help developers work with the OPC APIs more efficiently. This includes generation of client code in a wide variety of languages, which should help kick start any application that integrates with the OPC APIs, by generating the boilerplate code required to interact with the APIs.

Using Swagger Codegen is quite simple. Download the built JAR file from Maven, and execute the JAR file as follows:

$ java -jar swagger-codegen-cli-2.2.2.jar generate -i <path_or_url_to_swagger> -l <language> -o <path_to_output>

This should generate the API client bindings in the specified language in the requested output directory.