Getting Started

The aim of this section is to get you, the Application Developer up and running as quickly as possible. Here we will develop and then test a simple application, as per following steps:

  • Register as a developer
  • Create an application, using the featured payment model
  • Create a programme for the application and test it in the sandbox environment
  • Create a corporate identity instance
  • Create a virtual card instance owned by the corporate identity

Concepts

OPC uses the concept of a Payment Model to determine various aspects of the Application.
The Payment Model determines the type of entities and the interactions across such entities within an Application. Ixaris has provided a sample Payment Model as follows:

Payment Application Model

The Payment Model above is such that Applications using it can enable a Corporate to issue Virtual Cards and load these cards with funds from a Corporate Balance funded via Bank Transfer. The Payment Model itself restricts you in the type of functionality that you can access or use for your Application (for instance you cannot issue Virtual Cards to a User Identity).

The various elements that make up a Payment Model, such as Corporate Identity, Managed Card etc. are referred to as Paylets – as you can see, Paylets are categorized as Identities, Instruments or Transactions. Relationships can be defined across these Paylets – for instance you can note that in the proposed Payment Model the Payment Instrument Paylets (External Account, Managed Account and Managed Card) are owned by the Corporate (Identity); also only specific Transactions can be applied across specific Instrument types.

So we can say that the Payment Model determines the overall static structure of an Application.

Once the Developer develops the Application and publishes it, the Programme Manager can create multiple instances, called Programmes, for each of its clients. The structure of each of such Programmes is the same for all clients as determined by the Payment Model. However there can be a 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.

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

Setting Up

The first step that is required is to register a new user on the developer portal. Once registered as a developer, you will then be able to log in and create your application.

In order to simplify this process, we have featured a simple application model which you can use. Follow through on the creation of an application in the following link: Create Application

Once an application is created, the next step is to test this new application by creating a programme from the sandbox accessible through the developer portal. The following URL takes you through creating a test programme on the sandbox: Create Programme in Sandbox. This will result in a draft programme being made available, complete with configured appropriate profiles.

Making your first calls

Follow up on calling APIs by accessing our Swagger API documentation here. Swagger can be used to call all of our APIs in order to facilitate your integration and also for testing purposes. However this does not restrict you to use only swagger, you can use any other tool you think is appropriate.

Create Corporate Identity

We can now actually create a corporate identity on this draft programme, followed by creation of a virtual card which it will own.

In order to be able to create a corporate identity, you will need the programme Id and the profile Id, both of which you created in the previous step. Perform a POST request on the /corporates/_/create in order to create a corporate identity.

Create Password

Perform a POST request on the [/passwords/{credential_id}/create] in order to create a password for the root of the corporate identity. This will enable you to log in using the root credential of the corporate identity.

Get Authorisation Token

Performing a login bascially requires you to get an authorisation token. You do this by performing a POST request on /auth/login.

The following headers need to be supplied:

  • 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

Additionally, the request body needs to contain the following information. Make sure you replace these with your own details:

{
  "programmeId": "3749203750",
  "credentialCode": "username",
  "password": "password"
}

This should return a response containing an authorisation token, as follows:

{
  "token": "5749465942632969"
}

Once you’re logged in, you can use this token to perform authenticated calls, by passing the token as the Authorization header.

Create a Virtual Card

Once you have an authorisation token for the corporate identity, you can create an instance of a Virtual Card. This can be achieved by performing a POST call on /managed_cards/_/create.

Once again, you will need to supply the X-callref and the X-programmeKey headers, as described earlier. In addition to those, you will also need to supply the Authorization header containing the Authorisation Token as shown above.

Creating a Virtual Card requires the following request body. Sample values have been filled in here, but you will need to replace parameters with your own values (as described below).

{
  "profileId": "5743105732",  // The ID of your managed card profile
  "ownerId": "2483290572",  // The ID of the corporate that will own this card
  "friendlyName": "My first card",
  "currency": "GBP",
  "issuingProvider": "IssuingProvider", // The card issuer
  "processingProvider": "ProcessingProvider", // The card processor
  "nameOnCard": "John Doe"
}

A successful response will return the details of your newly created Virtual card:

{  
  "id":{"id":"5984256922", "type":"managed_cards"},  
  "programmeId": "3749203750",  
  "profileId": "5743105732",  
  "ownerId": "2483290572",  
  "type": "VIRTUAL",  
  "friendlyName": "My first card",  
  "state": "ACTIVE",  
  "currency": "GBP",  
  "issuingProvider": "IssuingProvider",  
  "processingProvider": "ProcessingProvider",  
  "balances": {  
    "currency": "GBP",  
    "available": "0",  
    "reserved": "0",  
    "actual": "0"  
  },  
  "cardNumber": "4111111111111111",  
  "cardBrand": "VISA",  
  "nameOnCard": "John Doe",  
  "startDate": "03/17",  
  "endDate": "03/19",  
  "cardLevelClassification": "CORPORATE",  
  "expiryPeriod": {  
    "periodLength": "2",  
    "timeUnit": "YEARS"  
  },  
  "renewalType": "AUTO_RENEW",  
  "maxNumberOfLoads": {  
    "value": "0",  
    "hasValue": false
  },  
  "maxNumberOfSpends": {  
    "value": "0",  
    "hasValue": false
  },  
  "currentNumberOfLoads": "0",  
  "currentNumberOfSpends": "0",  
  "blocks": [],  
  "destroyType": "NOT_DESTROYED",  
  "creationTimestamp": "1490274197",  
  "actions": ["UPDATE"]  
}

Check your Virtual Card details on the OPC Sandbox

All entities that you create via the various APIs can be viewed from within the OPC Sandbox. The OPC Sandbox is an environment that the Developer can use to manage Programmes that the Developer uses to test the Application. The Developer can choose to create one or more Programmes against which to test the Application. You have already accessed the Sandbox when creating the programme. Once you access it:

  1. Click on the Programme
  2. Click on View Profiles
  3. Click on the Managed Card Profile
  4. Click on View instances from the action menu on the right

You should be able to see the Virtual Card, the details of which were returned to you through your API call.

The profile list in the OPC Sandbox

The details of the managed card

Next Steps

Now that you have successfully interacted with the APIs, here’s what you can do next:

  1. Explore the rest of the OPC APIs
  2. Check out another example using more APIs and Paylet entities
  3. Check out the Cheat Sheet
  4. View the API's overview
  5. Checkout the FAQs

Explore the rest of the OPC APIs

Swagger is an open source API framework used to describe OPC’s REST APIs. It offers many features designed to help developers work with the OPC APIs more efficiently. Most importantly it can be used to generate Client Code (in a wide variety of programming languages) required to interact with the APIs..

The Swagger documentation for the OPC APIs is available here.

Alternatively, you can download a Postman collection describing the APIs available here. If you are not familiar with Postman you can get more information here on Collections and Environments.

Check out another example using more APIs and Paylet entities

If you would like to see other OPC APIs in action, take a look at this sample application, which covers other Paylet entities and operations for your Application including depositing of funds into the system, creating instruments other than the Virtual Card and simulating purchases on a Virtual card.

Check out the Cheat Sheet

For a concise overview of the key features offered by the OPC APIs, here is a cheat sheet that describes the main Paylet entities for your Application.

View our API Overview

If you would like more details on a specific API method, the API reference is a comprehensive guide that covers all APIs.

Frequently Asked Questions

We have also compiled together a list of frequently asked questions

Get Support

If you need further assistance, we'll be glad to help.

You can get in touch with us via Slack.