Managed Card Paylet

What is a Managed Card?

Managed cards are Virtual or Plastic cards issued to a Corporate Identity that can be used for online purchases or physically at a point of sale. A Managed Card Profile determines limits and restrictions for a card instance.

A Managed Card is owned by the Corporate Identity, but a Managed Card does not own any other Paylet Type. Relations can be created with other Instrument Paylets to allow Transaction Paylets to move funds between related Instruments. Refer to the Managed Cards Swagger documentation for the complete list of APIs that may be invoked in relation to Managed Cards.

Note that currently only Virtual Cards are supported.

Managed Card Paylet API

URL Method Description
/managed_cards/get POST Retrieve a list of Managed Card instances for a Programme
/managed_cards/{id}/get POST Retrieve details of the Managed Card named in the request
/managed_cards/_/create POST Create an instance of a Managed Card using the specified ID and details
/managed_cards/{id}/destroy POST Permanently set the state of the Managed Card to Destroyed to prevent any further purchasing
/managed_cards/{id}/block POST Restrict the Managed Card instance. This will stop fund movements and purchases from being made.
/managed_cards/{id}/unblock POST Remove restrictions on a Managed Card instance
/managed_cards/{id}/update POST Update the friendly name of the Managed Card
/managed_cards/{id}/statement/get POST Retrieve the Managed Card statement (containing all financial transactions)
/managed_cards/{id}/cvv/get POST Retrieve the CVV of the Managed Card instance
/managed_cards/profiles/get POST Retrieve the list of Profiles that can be used to create an instance of a Managed Card
/managed_cards/profiles/{id}/get POST Retrieve the details of the Managed Card Profile specified in the request.

Managed Card Instance Attributes

Attribute Name Description
Id The ID of a Managed Card instance
Programme Id The ID of the Programme of the Managed Card instance
Profile Id The ID of the Profile used to create the Managed Card instance
Owner Id The ID of the Corporate Identity owner of the Managed Card
Type Specifies whether the card is a Virtual card or a Plastic card
Friendly name A user-friendly name for the Managed Card
State The current state of the Managed Card instance (can be active or destroyed)
Currency The base currency the Managed Card instance – balance and statement will be shown in this currency
Issuing provider The Financial Provider underwriting to the Managed Card. This is as determined by the Programme Manager during the setup of a Programme
Processing provider The Payments Processor processing transactions for this Managed Card. This is as determined by the Programme Manager during the setup of a Programme
Balances The actual, the available and the reserved balances of a Managed Card
Card Number The full card number as typically shown on the front of a Virtual or Plastic card
Card Brand The card scheme of the Managed Card e.g. Visa
Name on Card The name of the Managed Card holder e.g. Corporate Prepaid
Start Date The date the Managed Card can be used from
End Date The date the Managed Card expires
Card Level Classification Indicates whether the Managed Card is for Consumer Identities or Corporate Identities Only Corporate Identities are currently supported
Expiry Period Specified in months or years
Renewal Type Determines the card renewal policy – can be set to one of Auto renewal and No Renewal
Max Number of Loads Specifies the number of times funds can be loaded onto the Managed Card. This is set to one for a single-load card. Not currently implemented
Max Number of Spends Specifies the number of purchases for the Managed Card Currently this can only be set to 1
Current Number of Loads Records the number of load/deposit transactions on the Managed Card
Current Number of Spends Records the number of purchases on the Managed Card
Blocks Information about restrictions placed on the Managed Card e.g. whether the block was system triggered or carried out by an operator
Destroy Type Records whether the card was destroyed by a system triggered event or by the Corporate Owner
Creation Timestamp The date and time when the instance was created
Actions Indicates the actions that are possible on the Managed Card in its current state

Simulator Functions

There are three functions relating to the Managed Card Paylet that involve interaction and data flow with external third parties. This interaction cannot be tested in the development environment, so OPC provides a simulator to simulate these functions:

Perform a purchase on a card

This function combines the simulation of an Authorisation and a Settlement request from a Merchant.

  • To access this method, go to the Purchase API call in Swagger.
  • In the Parameters section, specify the parameters as prompted

    • Please note that to simulate a Purchase, the purchase amount should be entered as a negative number. For Expiries, Merchant Voids and Reversals it should be a positive amount. Also, the amount needs to be entered in its lowest denomination e.g. 10 GBP would need to be entered as 1000.

  • At the bottom of the section select ‘Try it out!’

  • A successful response would result in system updates that record the Settlement being received. In the case of a single spend card, it would also trigger an automatic Destroy on the Managed Card to prevent further spends on the Managed Card instance

Perform an authorisation on a card

This function simulates an authorisation at a merchant.

  • To access this method, go to the Authorisation API call in Swagger.

  • In the Parameters section, specify the parameters as prompted

    Please note that to replicate a purchase, the transaction amount should be entered as a negative number. For Expiries, Merchant Voids and Reversals it should be a positive amount. Also, the amount needs to be entered in its lowest denomination e.g. 10 GBP would need to be entered as 1000.

  • At the bottom of the section select ‘Try it out!’ A successful response would result in system updates that record the authorisation being received. In the case of a single spend card, it would also trigger a system block on the card to prevent another authorisation from occurring.

Simulate a settlement on a card

This simulates a Settlement transaction and updates the Managed Card balances and records the corresponding Settlement Transaction in the card’s Transaction History.

  • To access this method, launch the Settlement API call in Swagger.
  • In the Parameters section, Specify the parameters, as prompted. Please note that to replicate a purchase, the transaction amount should be entered as a negative number. For Expiries, Merchant Voids and Reversals it should be a positive amount. Also, the amount needs to be entered in its lowest denomination e.g. 10 GBP would need to be entered as 1000.
  • At the bottom of the section select ‘Try it out!’ A successful response would result in system updates that record the settlement being received. In the case of a single spend card, given that the authorisation is closed fully, it would also trigger a system destroy on the card to prevent it from being used further.

Other Information:

OPC connects to one or more Payment Processor that process Authorisations and Settlements – information from these third-parties is imported in OPC such that appropriate transaction entries and internal balances within OPC reflect such external transactions. Any reconciliation issues are dealt with by the Programme Manager through specialised operational consoles. The lifecycle of a Managed Card instance is such that it can be in an Active or in a Restricted state. Such restrictions can be set manually by an operator (on the basis of activity review) or by the system according to the Managed Card’s profile – for instance when an Authorisation request is received on a Managed Card that has been set up as a single-spend type of card (this is a constraint that can be set in a Managed Card Profile) then the system automatically blocks the Managed Card instance to prevent other transactions. Restrictions can be removed manually by an operator or automatically by the system - for example, if a Settlement is not received and the Authorisation request expires on a single spend Managed card, then the Managed Card is unblocked so that it can be used for other transactions. Purchases and transfers cannot be done while a Managed Card is in a blocked state – there are exceptions, such as in the case when a Merchant Refund is being processed.

While a card is blocked, it is not possible to make a purchase using the card or transfer money from it. However, some processes will allow money to be placed on the card even while it is marked as blocked e.g. a merchant refund – the reason for this is that a refund will first be handled by the provider who is not concerned with the restriction status of the card. The funds that are received on the card however will be blocked until the block is removed.

Once a managed card’s state has changed to ‘destroyed’ it cannot be changed. If any funds are left on a card which has been destroyed, these can be transferred out to another instrument, unless the managed card is blocked.