Virtual Card

Virtual Card API v2

Confidentiality Statement
The information in this document is strictly confidential to the persons to whom it is addressed
and should not be disclosed to any other person. It may not be reproduced in whole, or in part,
nor may any of the information contained therein be disclosed without the prior consent of the
directors of Dataflexnet Limited (‘the Company’). A recipient may not solicit, directly or
indirectly (whether through an agent or otherwise) the participation of another institution or
person without the prior approval of the directors of the Company.

The contents of this document have not been independently verified and they do not purport to
be comprehensive, or to contain all the information that a prospective interest may need. No
representation, warranty or undertaking, expressed or implied is or will be made or given and
no responsibility or liability is or will be accepted by the Company or by any of its directors,
employees or advisors in relation to the accuracy or completeness of this document or any other
written or oral information made available in connection with the Company.

Any form of reproduction, dissemination, copying, disclosure, modification, distribution and or

publication of this material is strictly prohibited.

Copyright © Dataflexnet 2021

Platform Version: r9.1

Last Updated: 11/11/2021 08:56

Table of Contents
Document Control ................................................................................................................................ 4
1 Introduction................................................................................................................................... 7
1.1 Overview ............................................................................................................................................ 7
1.2 Scope.................................................................................................................................................. 7
1.3 Audience ............................................................................................................................................ 7
1.4 Breaking Changes ................................................................................................................................ 7
2 API ................................................................................................................................................ 8
2.1 Overview ............................................................................................................................................ 8
2.2 URLs ................................................................................................................................................... 8
2.3 Versioning .......................................................................................................................................... 8
2.4 Open API ............................................................................................................................................ 8
2.5 General Definitions ............................................................................................................................. 9
2.5.1 Request Body ...............................................................................................................................................................9
2.5.2 Request Methods ........................................................................................................................................................9
2.5.3 Request Headers .........................................................................................................................................................9
2.5.4 Response Body ............................................................................................................................................................9
2.5.5 Response status .........................................................................................................................................................10
2.5.6 Response Encodings ..................................................................................................................................................10
2.6 API Call Tracing (Diagnostics) ............................................................................................................. 10
2.7 Model Definitions ............................................................................................................................. 10
2.7.1 Account Object ..........................................................................................................................................................11
2.7.2 RealCardAccount Object ............................................................................................................................................11
2.7.3 RealCard Object .........................................................................................................................................................12
2.7.4 VirtualCard Object .....................................................................................................................................................13
[Link] spendControlCurrencyType - Billing .................................................................................................................14
[Link] spendControlCurrencyType - Merchant ...........................................................................................................14
[Link] referenceData ...................................................................................................................................................14
2.7.5 SpendControl Object ..................................................................................................................................................15
[Link] Spend control validation. ..................................................................................................................................16
2.7.6 SuccessResponse Object ............................................................................................................................................16
2.7.7 ErrorResponse Object ................................................................................................................................................17
2.7.8 Error Object ...............................................................................................................................................................17

2.8 Scopes (Authorisation) ...................................................................................................................... 21

2.9 Methods ........................................................................................................................................... 22
2.9.1 Account......................................................................................................................................................................22
[Link] Create Account .................................................................................................................................................22
[Link] Update Account ................................................................................................................................................22
[Link] Delete Account .................................................................................................................................................22
[Link] Query Account ..................................................................................................................................................23
[Link] Query Accounts ................................................................................................................................................23
2.9.2 RealCardAccount .......................................................................................................................................................25
[Link] Create RealCardAccount ...................................................................................................................................25
[Link] Update RealCardAccount..................................................................................................................................25
[Link] Enable RealCardAccount ...................................................................................................................................25
[Link] Disable RealCardAccount ..................................................................................................................................26

Proprietary and confidential © Dataflexnet 2021 2

 [Link] Cancel RealCardAccount ...................................................................................................................................26
[Link] Query RealCardAccount....................................................................................................................................27
[Link] Query RealCardAccounts ..................................................................................................................................27
2.9.3 RealCard ....................................................................................................................................................................29
[Link] Create (Provision) RealCard ..............................................................................................................................29
[Link] Update RealCard ...............................................................................................................................................29
[Link] Query RealCard .................................................................................................................................................30
[Link] Query RealCards ...............................................................................................................................................30
2.9.4 VirtualCard.................................................................................................................................................................32
[Link] Create VirtualCard ............................................................................................................................................32
[Link] Enable VirtualCard ............................................................................................................................................32
[Link] Disable VirtualCard ...........................................................................................................................................32
[Link] Cancel VirtualCard ............................................................................................................................................33
[Link] Query VirtualCard .............................................................................................................................................33
2.9.6 Query Health .............................................................................................................................................................35

3 Authentication and Authorisation ................................................................................................ 36

3.1 Authorisation .................................................................................................................................... 36
3.2 Authentication .................................................................................................................................. 36
3.3 Management of Client Credentials..................................................................................................... 36
3.4 IPv4 Whitelisting of Client Credentials ............................................................................................... 36
3.5 Automatic Configuration ................................................................................................................... 36
4 Non-Functional ............................................................................................................................ 37
4.1 Scope................................................................................................................................................ 37
4.2 Deprecation ...................................................................................................................................... 37
4.3 Security ............................................................................................................................................ 37
4.4 Service Levels.................................................................................................................................... 37
5 Glossary ...................................................................................................................................... 38

Proprietary and confidential © Dataflexnet 2021 3

Document Control
Platform Date Changes Author
Version
TBC 02/03/2020 Initial API documentation. Michael Cliffe
Andrew Unwin
Adam Willden
TBC 04/03/2020 Changed sub-section numbering and cardholder name. Michael Cliffe

TBC 10/06/2020 The following changes have been made in this revision of the API Michael Cliffe
documentation, Andrew Unwin
• A RealCard must have a current RealCardAccount. Adam Willden
• The X-COM-DATAFLEXNET-TRACE header is clarified as
being optional and the strict format requirements explicitly
stated.
• Clarified an Account may have a parent Account, as such, an
Account may have many children. Also, made clear that an
Account may similarly have RealCardAccount children.
• Clarified enablement of RealCardAccounts can impact
bound VirtualCards even though their actual state is not
changed.
• Revised service level statement to meet commercial
commitments only.
• Added support for a name property on a RealCard, a
property designed for human consumption typically used as
a surrogate reference.
• The currency of a RealCard is system defined, the currency
cannot be set using the API, now correctly reflected in this
documentation.
• Introduced more fine grain authorisation scope definitions
to support more varied software client scenarios including
better control of sensitive data.
• Clarified that data transfer object properties marked with (-)
will be ignored without error.
• Clarified the replacement RealCard’s currency must match
the current RealCard’s currency for the RealCardAccount.
• Introduced OpenAPI v3 endpoint.
• Document version will align with the platform version, yet
to be confirmed, greater than version 6.
• Added support to update an existing RealCard’s
cardholderName and/or name properties without having to
introduce a new RealCard.
• Clarified error codes.
• cardHolderName is mandatory on the RealCard.
• Added missing RealCard properties validFromMonth and
validFromYear
• Clarified RealCard expiryMonth and expiryYear to be
expiresEndMonth and expiresEndYear as names.
• Clarified the sort order on query methods.
• Clarified the error descriptions are not the actual
description that may be returned in the Error data transfer
object. We also increased the maximum size that can be
returned as an error description to accommodate value
references if required.

Proprietary and confidential © Dataflexnet 2021 4

Platform Date Changes Author
Version
TBC 19/06/2020 • Corrected that RealCardAccount, RealCard and Account Michael Cliffe
name on the data transfer objects are now Yes on POST and Adam Willden
? (optional) on PUT. Andrew Unwin
• Clarified that cancellation of a VirtualCard does not cancel
the RealCardAccount.
• Clarified that cancellation of a RealCardAccount also cancels
the RealCard.
TBC 23/06/2020 • Corrected that Account PUT method requires accountId Michael Cliffe
property on the data transfer object.
TBC 07/09/2020 • Revised the authentication and/or authorisation to not Michael Cliffe
assume protocol (or configuration thereof), for reasons of Neil Chapman
the flexibility in security models offered by the Dataflexnet Adam Willden
authentication service, and refer to external documentation
that can cover those topics with greater focus avoiding
duplication of information.
• Changed the identifier of each data transfer object to be id
instead of <name>Id to align the API with Dataflexnet
standard practice, consistency with paths, and general best
practice
• Introduced 503 http status code to cover planned
maintenance scenarios.
• Correction on realCardAccountIds on the Account data
transfer obtain, which are those returned for the Account
and not RealCardAccount.
• Change count pager parameter to be named size to align
with Dataflexnet standard practice.
• Where a data transfer object is supported by partial (rather
than complete) update we have aligned the use of https
verbs with best practice, instead of PUT, in these cases we
now use PATCH instead.
• When updating an Account the document explained it
would return a newly created Account, which is wrong,
description corrected to explain the updated Account is
returned as would be expected of the operation anyway.
• expiresEndYear on RealCard is limited to a maximum value
of 9999.
• RealCard vaueFromYear must be less than or equal to
expiresEndYear and must be less than or equal to 10 years
prior to the expires expiresEndYear.
• Client cancelled the HTTP request with a response code of
499.
• Added a read only status property for RealCardAccount.
• Added a read only status property for Account. At this time
the API does not support the ability to enable and/or
disable an Account.
• RealCard currency has been omitted, is needed, when
creating a new RealCard. It must align with the
RealCardAccount if present i.e. new current RealCard.
• Glossary terms ‘system installation’ & ‘domain’ have been
rationalized to ‘instance’ to avoid confusion.
• Captialized the acronym UUID and added this to the
Glossary

Proprietary and confidential © Dataflexnet 2021 5

Platform Date Changes Author
Version
• Update RealCardAccount status to have American spelling
of ‘Canceled’ to match standard coding practices.
• Fixed incorrect request header name
• Fixed incorrect request header value
• Replaced incorrectly applied vc-accounts-modify scope with
intended vc-accounts-view for the methods:
o Query RealCardAccounts
o Query RealCard
o Query RealCards
• Clarified the effect the vc-accounts-sensitive scope has on
requests. Updated both the scope definition and explicitly
against methods
• Removed vc-accounts-sensitive scope from the methods:
o Query RealCardAccount
o Query RealCardAccounts
• Added missing ‘201’ response status
TBC 15th • Clarified that the currency of the RealCard must be Neil Chapman
September supported by the virtual card system instance. Michael Cliffe
2020 • Added current readonly property to better support the
onlyCurrent filter property on RealCards.
TBC 26th • Updated Errors Andy Thwaites
November • Removed patch from Account ParentAccountId property.
2020 • Expanded summary for vc-accounts-sensitive scope
• Added vc-accounts-sensitive scope to Real Card POST and
PATCH
r7.0 1st • Platform confirmed as r7.0 Michael Cliffe
December • Added explanation of JSON patch
2020 • Unique validation error codes to be removed for
RealCardAccount and Account name
r7.0 13th • Added where an issuer does not agree to RCN updates, the Andrew Unwin
January feature will prevent the replacement of a RealCard within a
2021 RealCardAccount
• Updated Errors
r7.0 16th • Updated error message template for Pagerinfo Offset Neil Chapman
February • Specified that some cascade functionality is not yet
2021 implemented in the Cancel RealCardAccount section
R9.1 November • Added the following object model definitions Andrew Unwin
2021 o VirtualCard
o SpendControl
• Added the following Methods:
o VirtualCards
▪ Create
▪ Get
▪ Enable
▪ Disable
▪ Cancel

Proprietary and confidential © Dataflexnet 2021 6

1 Introduction
1.1 Overview
The virtual card system offers features that are manually using the virtual card website. The virtual card website is
also known as the portal. Not all integrators of the virtual card system, in terms of their own systems, workflow,
policy, procedures and standards, are able or wish to utilise the website. They need a different approach, an
approach that is custom, one that meets their specific needs. The virtual card website offers a common approach
to all integrators, a quick start, and therefore cannot be extensively customised. Given the approach of this API, by
definition, the API is not integrator specific, so it is important an integrator does not plan to seek (or rely on)
changes that are specific to their own challenges.

This API of the virtual card system will in time reflect the capabilities of the virtual card system, iteratively
developed over many versions, taking a factored approach in terms of design, and includes versioning capabilities
where backward compatibility would otherwise be broken. It is expected that integrators overtime, especially if
they seek new functionality, will upgrade. We set out a deprecation policy in this document.

This API is offered on a per virtual card system installation basis i.e. franchise. The API will not operate across
virtual card installations. This might be a relevant consideration if a group of integrators operate multiple virtual
card system installations. There are many reasons for this approach that include isolation, performance, security,
residency, as examples. Henceforth a system installation which encompasses both the virtual card website and API
installations will be known as an instance.

This document details the API.

1.2 Scope
Technical documentation of the virtual card API to support the following areas of functionality,

• authentication and/or authorisation.

• management of account structures and associated real card accounts within the virtual card system.

• life cycle management of real cards against real card accounts that includes their provisioning.

• API health monitoring.

1.3 Audience
This document is for technical personnel that have technical knowledge and skills to develop and maintain software
that will call the virtual card API for manipulating account structures and associated real card accounts, as some
process, using business to business connectivity.

It is assumed that the reader has knowledge of the following,

• HTTPS 2.0 or 1.1 with TLS.

• JSON.

• RESTful API design principles and practices.

• Selected protocols for OpenID Connection v1 (OIDC) and oAuth 2.0 for client software authentication.

• PCI DSS related security policies, procedures, and standards, especially in respect of key management.

1.4 Breaking Changes

There will be no breaking changes made to APIv2 during it’s development life, this is to ensure existing integrations
of APIv2 are not required to update their code/integration unless they wish to benefit from the additional
functionality, should a change be considered too significant that would result in potentially breaking an existing
integration, would have to either increase the version or provide an alternative method, retaining all existing
functionality

Proprietary and confidential © Dataflexnet 2021 7

2 API
2.1 Overview
The API is RESTful, using UTF8 character sets for JSON objects as the envelope for the exchanged content. We
optionally support GZIP as encoding. This general approach is covered is section 2.3.

The API has several areas of functionality,

• authentication – software client authentication.

• authorisation – presenting proof of having authenticated and scope of access.

• accounts – management of account structures.

• real cards and real card accounts – life cycle management of real cards, including updating real cards, and
in relation to real card accounts.

• health – reachability and intrinsic health status reports for monitoring the API externally.

Further information about these API methods are covered in section 2.8. A description of the custom data types,
also known as data transfer objects, that essentially capture the content exchanged along with the validation rules,
are covered in section 2.6.

The API requires an access token to be presented in an HTTP header for the purpose of authorisation. A
deployment of a software client uses standard protocols to authenticate itself with the Dataflexnet authentication
service, which if successful will issue an access token for use by the software client deployment with the API. This is
discussed in more detail in section 3.

The API also includes some additional capabilities, such as tracing to assist with diagnostics covered in section 2.5.

These subsequent sections cover all functional aspects of the API in detail.

2.2 URLs
The production and certification URLs are respectively,

• [Link]

• [Link]

Note: See section 3 for additional URLs for authentication of client software deployments.

2.3 Versioning
The API is versioned on the path, as per the following example,

• [Link]

• [Link]

2.4 Open API

The API supports Open API v3 specification, the URL is,

[Link]

Proprietary and confidential © Dataflexnet 2021 8

 2.5 General Definitions
In these sub-sections, we outline the common approach taken by the API.

2.5.1 Request Body

The request body is JSON with these clarifications of treatment,

• Unknown fields will be ignored.

• Null fields are allowed but treated as no value.

• PATCH operations are encoded as JSON Patch as per RFC 6902.

2.5.2 Request Methods

The HTTP verb is used to determine the nature of the request, and resource URL, as follows,

Verb URL format Comment

POST [Link] Create this resource

GET [Link] Get this resource

PUT [Link] Entirely replace this resource

PATCH [Link] Partially replace this resource

DELETE [Link] Delete this resource (logically)

2.5.3 Request Headers

These headers must be provided according to HTTP protocols unless it is marked as optional,

Header Verb Value

Content-Type POST, PUT, PATCH application/json

Accept-Charset GET, POST, PUT, PATCH, DELETE utf-8

Accept-Encoding (optional) GET, POST, PUT, PATCH, DELETE gzip

See section Error! Reference
Authentication GET, POST, PUT, PATCH, DELETE source not found. for
information.
See section Error! Reference
X-COM-DATAFLEXNET-TRACE (optional) GET, POST, PUT, PATCH, DELETE source not found. for
information.

2.5.4 Response Body

The response body for successful API call is the SuccessResponse object, assuming a response body is relevant, see
section Error! Reference source not found.. For an error response, the ErrorResponse object is returned, assuming
a response body is relevant, see section Error! Reference source not found.. The response status indicates success.
The response status also states if a response body would be returned at all. The ErrorResponse object may include
additional error information but this is always subject to security concerns and type of error status.

Proprietary and confidential © Dataflexnet 2021 9

 2.5.5 Response status
HTTP status codes are used to report the outcome of the method call on a resource.

Status Code Success Comment

200 Yes Request was successful and response body is available.

201 Yes Request was successful and a new resource has been created.

204 Yes Request was successful without a response body returned.

400 No Validation error or incorrect formatting.

401 No The request requires authentication.

403 No The request was denied, indicative of insufficient permissions.

404 No The request does not match resource.

405 No Method (GET, POST, PUT, etc) not allowed for the given request path.
Method call rate has been throttled due to exceeding service level quota to protect
429 No
the resource.
499 No The request was cancelled by the calling client.

500 No Indicative of a program error and should be reported for resolution.

503 No The API is currently unavailable due to maintenance.

2.5.6 Response Encodings

Dataflexnet optionally supports GZIP encoding if accepted by HTTP headers at the discretion of the API.

2.6 API Call Tracing (Diagnostics)

An optional HTTP header is supported, that accepts a trace code, which the API will return in the same header as
response. This trace code is logged by Dataflexnet to facilitate diagnosis activities.

The code must be formatted as a UUID, if it is not correctly formatted, it will not be used or returned by the API.
The HTTP header is named X-COM-DATAFLEXNET-TRACE.

The following format is strictly expected as a UUID,

123e4567-e89b-12d3-a456-426655440000

2.7 Model Definitions

A software client using the API will use POST, PUT, PATCH, DELETE or PATCH verbs whose content is data transfer
objects. The properties vary depending on the API method called, HTTP verb applied, and whether it is a response
object. These data transfer objects are detailed below and referenced by the API method calls later.

(-) means not applicable

(?) means optional

(*) means many

If a value is passed for a property of a data transfer object that is marked (-) it will be ignored without error.

The DELETE verb is omitted from the data transfer objects as no content is given nor returned.

Proprietary and confidential © Dataflexnet 2021 10

 2.7.1 Account Object
Data type represents an Account of a client entity and/or logical client group.

An Account may have a parent Account, as such, an Account may therefore have many children, thus forming an
Account hierarchy recursively top down. Use the Account parentAccountId property for this purpose.

An Account may have many RealCardAccount children associated. Use the RealCardAccount accountIds property to
make those associations.

Please note these invariants,

• The parent-child relationship formed with accountId and parentAccountId cannot form a circular graph of
relationships.
Property Type POST PATCH PUT GET or Size Comments
Return
id UUID - - - Yes 32 Account identifier.
name String Yes ? - Yes 0-128
realCardAccountIds UUID[] - - - Yes 0-* Returned for each RealCard associated
with the Account ids.
parentAccountId UUID ? - - ? - Returned if set, once set must be
included and will be returned.
status String - - - Yes Enum One of,
• Enabled
• Disabled

2.7.2 RealCardAccount Object

Data type represents a RealCardAccount.

An issued VirtualCard is bound to a RealCardAccount for the lifetime of the VirtualCard. This cannot be changed. A
RealCardAccount is associated with a RealCard. Transaction processing against the VirtualCard uses the current
RealCard that is associated with the RealCardAccount.

If supported by the issuer, a RealCardAccount may be associated over time with many RealCards. If a subsequent
RealCard has been associated with a RealCardAccount then the most recently associated RealCard is used for
transaction processing as the current RealCard for that RealCardAccount.

There are no invariants.

Property Type POST PATCH PUT GET or Size Comments
Return
id UUID - - - Yes 32 Real card account identifier.
name String Yes ? - Yes 0-128
currency String - - - ? Enum The numerical numbers from ISO4217.
This is an enumeration of the currency
code short value.

This value is returned only if the

RealCardAccount has a current RealCard.
currentRealCardId UUID - - - ? - The realCardId of the current RealCard (if
associated) used for transaction
processing.
accountIds UUID[] ? ? - ? 0-1 Once associated with an Account cannot
be changed and must be included and
will be returned.
status String - - - Yes Enum One of,
• Cancelled
• Enabled
• Disabled

Proprietary and confidential © Dataflexnet 2021 11

 2.7.3 RealCard Object
Data type represents a RealCard.

A RealCard is always associated with a RealCardAccount. It is directly equivalent to a real card on which the
transactions would be performed for a VirtualCard bound to shared RealCardAccount.

There are no invariants.

Property Type POST PATCH PUT GET or Size Comments
Return
id UUID - - - Yes 32 Real card identifier.
pan String Yes - - ? 14-19 Plain PAN if authorized is asked and
granted.
maskedPan String - - - ? PAN masked according to scheme rules.

Authorisation is required to GET or

Return.
cvv2 String ? - - No 3-4 Numerical only. All digits must be
present padded with leading 0 if
required.
cardHolderName String Yes ? - ? 0-128 The name of the cardholder.

Authorisation is required to GET.

expiresEndMonth Number Yes - - ? 1-12 Must be present month or later when
created with the present year.

Authorisation is required to GET or

Return.
expiresEndYear Number Yes - - ? 2020-9999 Must be present year or later when
created.

Authorisation is required to GET or

Return.
validFromMonth Number Yes - - ? 1-12 Must be present month or later when
created with the year.

Authorisation is required to GET or

Return.
validFromYear Number Yes - - ? Authorisation is required to GET or
Return.
Must less than or equal 10 years prior to
the current year when created.

Must be less than or equal to

expiresEndYear when created.
realCardAccountId UUID Yes - - Yes 32 The realCardAccountId of its
RealCardAccount.
name String Yes ? - Yes 0-128
currency String Yes - - Yes Enum The numerical numbers from ISO4217.
This is an enumeration of the currency
code short value.

The currency must match the

RealCardAccount if a currency is
returned.

If the RealCardAccount has no previously

associated RealCard, this currency is only
limited by those allowed by the virtual
card system instance. Otherwise, the
currency must match that of the
RealCardAccount which is determined by
association with its current RealCard.
current Boolean - - - Yes True True if the RealCard is current for a
False RealCardAccount.

Proprietary and confidential © Dataflexnet 2021 12

 2.7.4 VirtualCard Object
Data type represents a VirtualCard.

A VirtualCard is always associated with a RealCardAccount.

There are no invariants.

Property Type POST PATCH PUT GET or Size Comments
Return
id UUID - Yes - Yes 32 Real card identifier.
pan String - - - ? 14-19 Plain PAN if authorized is asked and
granted.
maskedPan String - - - ? 14-19 PAN masked according to scheme rules.

Authorisation is required to GET or

Return.
cvv2 String - - - ? 3-4 Numerical only. All digits will be present
padded with leading 0.
cardHolderName String ? ? - ? 0-128 The name of the cardholder.

Authorisation is required to GET.

expiresEndMonth Number - - - ? 1-12 Must be present month or later when
created with the present year.

Authorisation is required to GET or

Return.
expiresEndYear Number - - - ? 2020- Must be present year or later when
9999 created.

Authorisation is required to GET or

Return.
validFromMonth Number - - - ? 1-12 Must be present month or later when
created with the year.

Authorisation is required to GET or

Return.
validFromYear Number - - - ? 2020- Authorisation is required to GET or
9999 Return.
Must less than or equal 10 years prior to
the current year when created.

Must be less than or equal to

expiresEndYear when created.
realCardAccountId UUID Yes - - Yes 32 The realCardAccountId of its
RealCardAccount.
name String Yes ? - Yes 0-128
merchantCurrencies List of Yes - - Yes 0-1 The numerical numbers from ISO4217.
String This is an enumeration of the currency
code short value.

status String - - - Yes Enum One of,

• Canceled
• Enabled
• Disabled
spendControlCurrencyType String ? ? - ? 7-8 “Billing” or “Merchant”
referenceData List of ? ? - Yes 0-32(30) Reference data is limited to 30
String characters,
Null fields
spendControls List of Yes ? - Yes 1-2 See spendControl object
spendCo
ntrol

Proprietary and confidential © Dataflexnet 2021 13

 Property Type POST PATCH PUT GET or Size Comments
Return
createdAt String - - - Yes 28 ISO 8601 Complete date plus hours,
minutes, seconds, and a decimal fraction
of a second
YYYY-MM-DDThh:mm:[Link]
(2018-04-25T18:00:30.45+01:00)
updatedAt String - - - Yes 28 ISO 8601 Complete date plus hours,
minutes, seconds, and a decimal fraction
of a second
YYYY-MM-DDThh:mm:[Link]
(2018-04-25T18:00:30.45+01:00)

[Link] spendControlCurrencyType - Billing

When selected, the billing amount and currency during authorisation are used against virtual card spend controls.

The billing currency and virtual card currency MUST match the virtual card’s real card. Also, billing currency is fixed
for the franchise according to the virtual card’s BIN.

Authorisations are declined where the virtual card currency does not match the billing currency.

Advantages,

One can use the virtual card for multiple currency purchases, if the currency is supported by the franchise and if
an foreign exchange is performed, the billing amount will be passed for approval.

Disadvantages,

One will need to ensure the virtual card amount has sufficient tolerance taking into account the foreign
exchange rate.

[Link] spendControlCurrencyType - Merchant

When selected, the merchant amount and currency during authorisation are used against spend controls.

The merchant currency and the virtual card currency MUST be same, but they can be different to the virtual card’s
real card.

Authorisations are declined where the virtual card currency does not match the merchant currency.

Advantages,

You can specify an exact amount of the purchase in the merchant currency, without the concern of exchange
rate fluctuations affecting the authorisation outcome.

Disadvantages,

The card can only be used for the currency which has been selected.

[Link] referenceData
Client reference data can be provided when creating or subsequently amending a virtual card, the client fields must
be presented in the correct order in the list, ‘null’ fields must be used to space out the reference data where data
are not provided.

e.g. to provide clientReferenceData for fields 1, 3 and 5.

"referenceData": ["abc123",
null,
"ghi789",
null,
"jkl012"]

Proprietary and confidential © Dataflexnet 2021 14

 2.7.5 SpendControl Object
Data type represents a virtual card’s SpendControl

A SpendControl is always associated with a VirtualCard.

There are no invariants.

Property Type POST PATCH PUT GET or Size Comments

Return
startDate String Yes ? - Yes 28 ISO 8601 Complete date plus hours, minutes,
seconds, and a decimal fraction of a second
YYYY-MM-DDThh:mm:[Link]
(2018-04-25T18:00:30.45+01:00)
endDate String Yes ? - Yes 28 ISO 8601 Complete date plus hours, minutes,
seconds, and a decimal fraction of a second
YYYY-MM-DDThh:mm:[Link]
(2018-04-25T18:00:30.45+01:00)
transactionMinSpend Number Yes ? - Yes +ve The minimum spend allowed for a single
Zero - transaction
BigInteger +ve number <= transactionMaxSpend
transactionMaxSpend Number Yes ? - Yes +ve The maximum spend allowed for a single
Non-zero - transaction
BigInteger +ve non-zero number >=
transactionMinSpend
spendWindowDurationUnit String Yes ? - ? 3-5 Defines the duration of the spend window in
combination with
SpendWindowDurationQuantity
Accepted Values
• Whole
• Day
• Month
• Year

spendWindowDurationQua Number ? ? - ? 1-9999 Defines the duration of the spend window in

ntity combination with
SpendWindowDurationUnit

Required when SpendWindowDurationUnit is

not Whole
spendWindowReferenceDa String ? ? - ? 28 Used to determine when the spend window
te rolls over.
ISO 8601 Complete date plus hours, minutes,
seconds, and a decimal fraction of a second
YYYY-MM-DDThh:mm:[Link]
i.e. 2018-04-25T18:00:30.45+01:00
spendWindowMaxSpend Number ? ? - ? +ve The maximum spend allowed within the
Non-zero - spend window.
BigInteger Positive Number
spendWindowMaxTransact Number ? ? - ? +ve The maximum number of transactions
ionCount Non-zero - allowed within the spend window
Integer
availableToSpend Number - - - Yes +ve Derived value based on existing
Non-zero - authorizations within the SpendControl
BigInteger current window.

Proprietary and confidential © Dataflexnet 2021 15

 [Link] Spend control validation.
Due to some legacy technical limitations of transaction processing v1, there are some strict controls and validations
applied to spend controls when creating or updating a virtual card. These limitations will be reviewed over time
allowing more flexibility in spend-controls with transaction processing v2.

The following validation is applied:

• All Spend-controls MUST have.

o Valid startDate and endDate values present, and they must be the same for all spend controls of a
virtual card.

o A valid spendWindowDurationUnit value.

o A valid spendWindowReferenceDate value which is the same as the startDate.

o Either one or both of spendWindowMaxSpend and spendWindowMaxTransactionCount values.

• One spend control MUST have.

o A spendWindowDurationUnit value of ‘Whole’

• A Virtual card must have

o ONE spend-control applied whose spendWindowDurationUnit is Whole.

o This spend-control MUST have the spendWindowMaxSpend value set as the total allowable
expenditure of the virtual card.

• For SUA virtual cards, the transactionMinSpend and transactionMaxSpend values MUST be the same as the
spendWindowMaxSpend, and the spendWindowMaxTransactionCount values MUST be set to 1. No
additional spend control would be supported for SUA.

VirtualCards will be rejected if.

• There is not at least one spend-controls.

• There is more than one spend-control with a spendWindowDurationUnit value of ‘Whole’.

• There is a spend-control with a spendWindowDurationUnit which is not ‘Whole’ where

spendWindowDurationQuantity is empty or less than 1.

• The spend-control startDate and endDate are not within the RealCard’s validFrom and expiresEnd date
range

2.7.6 SuccessResponse Object

This is a conceptual type of data, it represents any API response for a successful method call, where a response
body is given, except for the health API method calls.

Where a method call would only ever return a single result then a single JSON object will be returned. However, if
a method call may return more than a single result, no matter how many are returned, a JSON array of objects will
be returned.

The data type of the JSON object is documented in the method call itself.

Proprietary and confidential © Dataflexnet 2021 16

 2.7.7 ErrorResponse Object
Data type represents an API response object returned for a method call that errors, if a response body is to be
given, except for the health API method calls.
Property Type POST PATCH PUT Return Size Comments
errors Error[] - - - ? 0..*

2.7.8 Error Object

Data type for error validation information.
Property Type POST PATCH PUT Return Size Comments
code Number - - - Yes See below.
description String - - - Yes 0-512 See below.

These codes may be reported. The software client must NOT treat them as exhaustive. This allows the introduction
of additional codes in the future without the need for coordination. The fact that an error occurred, status code
wise, is what drives the logic.

Code Comments ( not actual description value returned )

1 PagerInfo '{PropertyName}' must be greater than or equal to {ComparisonValue}.
2 PagerInfo 'Size ' must be between {From} and {To}. You entered {Value}.
1001 Account cannot be deleted as it has one or more child Accounts.
1002 Account 'Id' is required.
1003 Account 'Name ' contains sensitive information that is not permitted.
1004 Account 'Name' must be {MaxLength} characters or fewer. You entered {TotalLength} characters.
1005 Account 'Name ' is required
1007 Account 'Parent Account Id' is not an Account that exists, is in scope, or is an invalid format.
RealCardAccount 'Account Ids' has one or more Accounts that does not support the current RealCard
2001
'Currency'.
RealCardAccount 'Account Ids' does not contain an existing association. Once an Account has been
2002
associated to a RealCardAccount, it cannot be changed.
RealCardAccount 'Account Ids' has one or more Accounts that does not exist, is in scope, or is an invalid
2003
format.
RealCardAccount 'Account Ids' must be between {MinCount} and {MaxCount} items. The list has
2004
{TotalCount} item(s).
RealCardAccount 'Description' must be {MaxLength} characters or fewer. You entered {TotalLength}
2005
characters.
2006 RealCardAccount 'Id' is required.
2007 RealCardAccount 'Name' contains sensitive information that is not permitted.
RealCardAccount 'Name' must be {MaxLength} characters or fewer. You entered {TotalLength}
2008
characters.
2009 RealCardAccount 'Name' is required.
2011 RealCardAccount is 'Cancelled'.
2012 RealCardAccount is 'Disabled'.
2013 RealCardAccount is 'Enabled'.
3001 RealCard 'Bin' of 'Pan' is not allowed or in scope.
3002 RealCard 'Card Holder Name' contains sensitive information that is not permitted.
RealCard 'Card Holder Name' must be {MaxLength} characters or fewer. You entered {TotalLength}
3003
characters.
3004 RealCard 'Card Holder Name' is required.
3005 RealCard 'Currency' must match the current RealCard 'Currency' for the RealCardAccount.
3006 RealCard 'Currency' is not a valid ISO-4217 currency number.
3007 RealCard 'Currency' is not supported by the instance.
3008 RealCard 'Currency' is required.
3009 RealCard of the RealCardAccount cannot be updated.

Proprietary and confidential © Dataflexnet 2021 17

Code Comments ( not actual description value returned )
3010 RealCard 'Cvv2' is an invalid format.
3012 RealCard 'Cvv2' must be between {MinLength} and {MaxLength} digits. You entered {TotalLength} digits.
3013 RealCard 'Cvv2' is required.
3014 RealCard 'Expired' must be equal to '{ComparisonValue}'.
3015 RealCard 'Expires End Month' must be between {From} and {To}. You entered {Value}.
3016 RealCard 'Expires End Month' is required.
3017 RealCard 'Expires End' cannot have already expired.
3018 RealCard 'Expires End' must be greater than 'Valid From'.
3019 RealCard 'Expires End' is required.
3020 RealCard 'Expires End Year' is an invalid format. Must be 4 digits.
3021 RealCard 'Expires End Year' must be less than or equal to '{ComparisonValue}'
3022 RealCard 'Expires End Year' must be greater than or equal to '{ComparisonValue}'.
3023 RealCard 'Expires End Year' is required.
3024 RealCard 'Id' is not a RealCard that exists, is in scope, or is an invalid format.
3025 RealCard 'Id' is required.
3026 RealCard 'IssueNumber' must be greater than or equal to '{ComparisonValue}'.
3027 RealCard 'Name' contains sensitive information that is not permitted.
3028 RealCard 'Name' must be {MaxLength} characters or fewer. You entered {TotalLength} characters.
3029 RealCard 'Name' is required.
3030 RealCard 'Pan' is an invalid format.
3031 RealCard 'Pan' is required.
3032 RealCard 'Real Card Account Id' is not a RealCardAccount that exists, is in scope, or is an invalid format.
3033 RealCard 'Real Card Account Id' is required.
3034 RealCard 'Scheme' must not be equal to '{ComparisonValue}'.
3035 RealCard 'Scheme' must be equal to '{ComparisonValue}'.
3036 RealCard 'Status' has a range of values which does not include '{PropertyValue}'.
3037 RealCard 'Type' must be equal to '{ComparisonValue}'.
3038 RealCard 'Valid From Month' must be between {From} and {To}. You entered {Value}.
3039 RealCard 'Valid From Month' is required.
3040 RealCard 'Valid From' is required.
3041 RealCard 'Valid From Year' must be greater than or equal to 'Expires End Year'.
3042 RealCard 'Valid From Year' is an invalid format. Must be 4 digits.
3043 RealCard 'Valid From Year' must be less than or equal to '{ComparisonValue}'.
3044 RealCard 'Valid From Year' must be greater than or equal to '{ComparisonValue}'.
3045 RealCard 'Valid From Year' is required.
3046 RealCard replacements are not permitted
AccountRealCardAccount 'Real Card Account Id' is not an Account that exists, is in scope, or is an invalid
4001
format.
4002 AccountRealCardAccount 'Account Id' is required.
AccountRealCardAccount 'Real Card Account Id' is not a RealCardAccount that exists, is in scope, or is
4003
an invalid format.
4004 AccountRealCardAccount 'Real Card Account Id' is required.
5001 Filter 'Client Id' is not a RelyingParty that exists, is in scope, or is an invalid format.
6001 Account 'Parent Account Id' is not an Account that exists, is in scope, or is an invalid format.
7001 RealCardAccount 'Account Id' is not an Account that exists, is in scope, or is an invalid format.
8001 RealCard 'Real Card Account Id' is not a RealCardAccount that exists, is in scope, or is an invalid format.
9001 VirtualCard 'Bin' of 'Pan' is not allowed or in scope.
9002 VirtualCard 'CardHolderName' contains sensistive information that is not permitted.
VirtualCard 'CardHolderName' must be {MaxLength} characters or fewer. You entered {TotalLength}
9003 characters.
9004 VirtualCard 'CardHolderName' is required.
VirtualCard 'Cvv2' must be between {MinLength} and {MaxLength} digits. You entered {TotalLength}
9005 digits.

Proprietary and confidential © Dataflexnet 2021 18

Code Comments ( not actual description value returned )
9006 VirtualCard 'Cvv2' is an invalid format.
9007 VirtualCard 'Cvv2' is required.
9008 VirtualCard 'Id' is not a VirtualCard that exists, is in scope, or is an invalid format.
9009 VirtualCard 'Id' is required.
9010 VirtualCard 'Name' contains sensistive information that is not permitted.
9011 VirtualCard 'Name' must be {MaxLength} characters or fewer. You entered {TotalLength} characters.
9012 VirtualCard 'Name' is required.
9013 VirtualCard 'Pan' is an invalid format.
9014 VirtualCard 'Pan' is required.
9015 VirtualCard 'RealCardAccountId' is Canceled.
9016 VirtualCard 'RealCardAccountId' current RealCard expired.
9017 VirtualCard 'RealCardAccountId' current RealCard not active.
9018 VirtualCard 'RealCardAccountId' is Disabled.
9019 VirtualCard 'RealCardAccountId' is not a RealCardAccount that exists, is in scope, or is an invalid format.
9020 VirtualCard 'RealCardAccountId' is not associated to any Accounts.
9021 VirtualCard 'RealCardAccountId' does not have a current RealCard.
9022 VirtualCard 'ReferenceData' is required.
9023 VirtualCard 'SpendControlCurrencyType' is required.
9024 VirtualCard 'SpendControlCurrencyType' has a range of values which does not include '{PropertyValue}'.
9025 VirtualCard is 'Canceled'.
9026 VirtualCard is 'Disabled'.
9027 VirtualCard is 'Enabled'.
VirtualCard 'ReferenceData' must be between {MinCount} and {MaxCount} items. The list has
9101 {TotalCount} item(s).
VirtualCard 'ReferenceData[{CollectionIndex}]' must be {MaxLength} characters or fewer. You entered
9102 {TotalLength} characters.
VirtualCard 'SpendControls' must be between {MinCount} and {MaxCount} items. The list has
9201 {TotalCount} item(s).
VirtualCard 'SpendControls' must be between {MinCount} and {MaxCount} items when
9202 FixedVcnAmount. The list has {TotalCount} item(s).
9203 VirtualCard 'SpendControls' has mutliple 'StartDate' set which is not supported.
VirtualCard 'SpendControls[{CollectionIndex}].StartDate' must be greater than or equal to
9204 '{ComparisonValue}'.
9205 VirtualCard 'SpendControls' has mutliple 'End Date' set which is not supported.
VirtualCard 'SpendControls[{CollectionIndex}].EndDate' must be less than or equal to
9206 '{ComparisonValue}'.
VirtualCard 'SpendControls' has multiple items with a 'SpendWindowDurationUnit' of 'Whole' which is
9207 not supported.
9208 VirtualCard 'SpendControls' must have a single item with a 'SpendWindowDurationUnit' of 'Whole'.
VirtualCard 'SpendControls[{SpendWindowSpendControlCollectionIndex}].SpendWindowMaxSpend'
must be less than or equal to
9209 '{PropertyName}[{WholeSpendControlCollectionIndex}].SpendWindowMaxSpend'.
9210 VirtualCard 'SpendControls' has multiple 'Spend Window Transaction Count' set which is not supported.
9211 VirtualCard 'SpendControls' has mutliple 'SpendWindowReferenceDate' set which is not supported.
9212 VirtualCard 'SpendControls' has multiple 'TransactionMaxSpend' set which is not supported.
9213 VirtualCard 'SpendControls' has multiple 'TransactionMinSpend' set which is not supported.
9301 VirtualCard 'MerchantCurrencies' must be empty when 'SpendControlCurrencyType' is 'Billing'.
VirtualCard 'MerchantCurrencies' must be {MaxCount} items when 'SpendControlCurrencyType' is
9302 'Merchant'. The list has {TotalCount} item(s).
9304 VirtualCard 'MerchantCurrencies[{CollectionIndex}]' is not a valid ISO-4217 currency number.
9305 VirtualCard 'MerchantCurrencies[{CollectionIndex}]' is required.
10001 VirtualCard 'SpendControls[{CollectionIndex}].StartDate' is required.
VirtualCard 'SpendControls[{CollectionIndex}].StartDate' must be greater than or equal to current date
10002 and time.

Proprietary and confidential © Dataflexnet 2021 19

Code Comments ( not actual description value returned )
10003 VirtualCard 'SpendControls[{CollectionIndex}].EndDate' is required.
VirtualCard 'SpendControls[{CollectionIndex}].EndDate' must be greater than
10004 'SpendControls[{CollectionIndex}].StartDate'.
VirtualCard 'SpendControls[{CollectionIndex}].TransactionMinSpend' must be greater than or equal to
10005 '{ComparisonValue}'.
VirtualCard 'SpendControls[{CollectionIndex}].TransactionMinSpend' must be empty when
10006 'SpendControls[{CollectionIndex}].SpendWindowDurationUnit' is not 'Whole'.
VirtualCard 'SpendControls[{CollectionIndex}].TransactionMinSpend' must be equal to
10007 'SpendControls[{CollectionIndex}].TransactionMaxSpend'.
VirtualCard 'SpendControls[{CollectionIndex}].TransactionMaxSpend' must be greater than or equal to
10008 '{ComparisonValue}'.
VirtualCard 'SpendControls[{CollectionIndex}].TransactionMaxSpend' must be empty when
10009 'SpendControls[{CollectionIndex}].SpendWindowDurationUnit' is not 'Whole'.
VirtualCard 'SpendControls[{CollectionIndex}].TransactionMaxSpend' must be equal to
10010 'SpendControls[{CollectionIndex}].SpendWindowMaxSpend'.
VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowDurationQuantity' is required when
10011 'SpendControls[{CollectionIndex}].SpendWindowDurationUnit' is not 'Whole'.
VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowDurationQuantity' must be greater than or
10012 equal to '{ComparisonValue}'.
VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowDurationQuantity' must be empty when
10013 'SpendControls[{CollectionIndex}].SpendWindowDurationUnit' is 'Whole'.
10014 VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowDurationUnit' is required.
VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowDurationUnit' has a range of values which
10015 does not include '{PropertyValue}'.
10016 VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowReferenceDate' is required.
VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowReferenceDate' must be equal to
10017 'SpendControls[{CollectionIndex}].StartDate'.
10018 VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowMaxSpend' is required.
VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowMaxSpend' must be greater than or equal
10019 to '{ComparisonValue}'.
10020 VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowMaxTransactionCount' is required.
VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowMaxTransactionCount' must be greater
10021 than or equal to '{ComparisonValue}'.
VirtualCard 'SpendControls[{CollectionIndex}].SpendWindowMaxTransactionCount' must be equal to
10021 '{ComparisonValue}'.
11001 VirtualCard 'ReferenceData[{CollectionIndex}].Value' is required.
VirtualCard 'ReferenceData[{CollectionIndex}].Value' must be {MaxLength} characters or fewer. You
11002 entered {TotalLength} characters.
VirtualCard 'ReferenceData[{CollectionIndex}].Index' must be greater than or equal to
11003 '{ComparisonValue}'.
11004 VirtualCard 'ReferenceData[{CollectionIndex}].Id' is required.

Proprietary and confidential © Dataflexnet 2021 20

 2.8 Scopes (Authorisation)
This API has a very simple scope schema in terms of API authorisation. The software client only is required to be
granted, and obtain, the required scopes with the authorisation system.

The level of authorization within the authorized scope will be managed as part of the access control mechanism
within the virtual card installation itself.

These scopes are supported, each method definition shows which is relevant,

Scope Summary of Authorisation

vc-accounts-view The software client is authorised to GET Accounts, RealCards, RealCardAccounts
to the extent permitted by the access token. However, the software client is not
authorised to view sensitive properties on those data types.
vc-accounts-modify The software client is authorised to modify Accounts, RealCardAccounts,
RealCards
vc-accounts-sensitive The software client is authorised to GET or Return sensitive data (specifically
including card holder data) to the extent permitted by the access token and other
scopes. This scope is not required to successfully call the API however the
presence of the scope does change how sensitive data is managed. This scope
cannot be used on its own, if required it must be used in conjunction with one of
the other vc-accounts-x scopes listed above.
vc-virtualcards-view The software client is authorised to GET VirtualCards to the extent permitted by
the access token. However, the software client is not authorised to view sensitive
properties on those data types.
vc-virtualcards-modify The software client is authorised to modify VirtualCards
vc-virtualcards-sensitive The software client is authorised to GET or Return sensitive data (specifically
including card holder data) to the extent permitted by the access token and other
scopes. This scope is not required to successfully call the API however the
presence of the scope does change how sensitive data is managed. This scope
cannot be used on its own, if required it must be used in conjunction with one of
the other vc-virtualcards-x scopes listed above.

Proprietary and confidential © Dataflexnet 2021 21

 2.9 Methods
This section explains each of the methods available.

2.9.1 Account
[Link] Create Account
Description
The creation of a new Account.

The new Account can optionally be related to an existing Account.

Request
Verb POST

Scope vc-accounts-modify

Path /v2/accounts

Body Account object to create.

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the newly created Account object. Otherwise,
depending on status returned, an ErrorResponse object is returned.

[Link] Update Account

Description
A logical update of an existing Account. The Account is referenced by the id returned from the API for the same
Account.

Request
Verb PATCH

Scope vc-accounts-modify

Path /v2/accounts/{id}

Body Revised Account object.

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse object is returned being the updated Account object. Otherwise,
depending on status returned, an ErrorResponse object is returned.

[Link] Delete Account

Description
Logical deletion of an existing Account. The Account is referenced by the id returned from the API for the same
Account.

You cannot delete an existing Account if it is a parent i.e. has children.

Deleting an Account has a cascade effect on state, including but not limited to,

Proprietary and confidential © Dataflexnet 2021 22

 • All user access will be removed.

• All VirtualCards issued against the Account will be cancelled.

• All SharePays will be revoked against now cancelled VirtualCards.

• Account integrations will be affected.

Associated RealCardAccounts will not be affected by this method call. If you specifically want the RealCardAccounts
cancelled they need to be explicitly cancelled.

Request
Verb DELETE

Scope vc-accounts-modify

Path /v2/accounts/{id}

Body No content

Param None.

Response
Status See standard responses.

Body If successful, a SuccessResponse object is returned as no content. Otherwise, depending on status

returned, an ErrorResponse object is returned.

[Link] Query Account

Description
Fetch an Account object by id.

The Account is referenced by the id as returned from the API for the same Account object.

Request
Verb GET

Scope vc-accounts-view

Path /v2/accounts/{id}

Body No content

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned as the Account object. Otherwise, depending on status
returned, an ErrorResponse object is returned.

[Link] Query Accounts

Description
Fetch many Account objects according to the search criteria.

The Account objects are returned ascending order of creation.

Request
Verb GET

Proprietary and confidential © Dataflexnet 2021 23

Scope vc-accounts-view

Path /v2/accounts

Body No content

Param These parameters are supported,

Name Type Required / Default

offset Number No / 0 Offset into result set from which to respond with. Must be
greater or equal to 0.
size Number No / 5 Maximum number of items from the result set to response
with. Must be between 1 and 11.
parentAccountId UUID No / None The id of the Account’s parent Account to filter on.
Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being an array of matching Account objects. Otherwise,
depending on status returned, an ErrorResponse object is returned.

Proprietary and confidential © Dataflexnet 2021 24

 2.9.2 RealCardAccount
[Link] Create RealCardAccount
Description
Creates a new RealCardAccount.

The new RealCardAccount is disabled by default.

Request
Verb POST

Scope vc-accounts-modify

Path /v2/realCardAccounts

Body RealCardAccount object

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the new RealCardAccount object. Otherwise,
depending on status returned, an ErrorResponse object is returned.

[Link] Update RealCardAccount

Description
Updates an existing RealCardAccount. The RealCardAccount is referenced by the id returned from the API for the
same RealCardAccount.

Request
Verb PATCH

Scope vc-accounts-modify

Path /v2/realCardAccounts/{id}

Body RealCardAccount object

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the updated RealCardAccount object. Otherwise,
depending on status returned, an ErrorResponse object is returned.

[Link] Enable RealCardAccount

Description
Enable an existing RealCardAccount as update. The RealCardAccount is referenced by the id returned from the API
for the same RealCardAccount.

This has no cascade effect on state. However, it will in effect enable associated VirtualCards by re-enabling them if
the RealCardAccount was disabled beforehand.

Request
Verb POST

Scope vc-accounts-modify

Proprietary and confidential © Dataflexnet 2021 25

Path /v2/realCardAccounts/{id}/enable

Body No content

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the updated RealCardAccount object. Otherwise,
depending on status returned, an ErrorResponse object is returned.

[Link] Disable RealCardAccount

Description
Disable an existing RealCardAccount as update. The RealCardAccount is referenced by the id returned from the API
for the same RealCardAccount.

This has no cascade effect on state. However, it will in effect disable associated VirtualCards as though they had
been disabled too.

Request
Verb POST

Scope vc-accounts-modify

Path /v2/realCardAccounts/{id}/disable

Body No content

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned with the updated RealCardAccount object. Otherwise,
depending on status returned, an ErrorResponse object is returned.

[Link] Cancel RealCardAccount

Description
Cancels an existing RealCardAccount as update. The RealCardAccount is referenced by the id returned from the API
for the same RealCardAccount.

A cancelled RealCardAccount cannot be undone.

Cancelling a RealCardAccount has a cascade effect on state, including but not limited to,

• The RealCards against the cancelled RealCardAccount will be cancelled too.

• Dependent integrations will be affected if this RealCardAccount is in use.

• The following cascade functionality is not implemented in Virtual Card v7.0, but will be implemented in a
future release:

• All VirtualCards issued against the cancelled RealCardAccount will be cancelled too.

Note: A cancelled VirtualCard will not cancel its RealCardAccount.

• All SharePays will be revoked against now cancelled VirtualCards.

Proprietary and confidential © Dataflexnet 2021 26

Request
Verb POST

Scope vc-accounts-modify

Path /v2/realCardAccounts/{id}/cancel

Body No content

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the updated RealCardAccount object. Otherwise,
depending on status returned, an ErrorResponse object is returned.

[Link] Query RealCardAccount

Description
Fetch a RealCardAccount object by id. The RealCardAccount is referenced by the id returned from the API for the
same RealCardAccount.

Request
Verb GET

Scope vc-accounts-view

Path /v2/realCardAccounts/{id}

Body No content

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the RealCardAccount object. Otherwise, depending
on status returned, an ErrorResponse object is returned.

[Link] Query RealCardAccounts

Description
Fetch many RealCardAccount objects matching the search criteria.

By default the RealCardAccount objects are returned in ascending order of creation by default.

Request
Verb GET

Scope vc-accounts-view

Path /v2/realCardAccounts

Body No content

Param These parameters are supported,

Name Type Required /

Default

Proprietary and confidential © Dataflexnet 2021 27

 offset Number No / 0 Offset into result set from which to respond with. Must be
zero or greater than 0.
size Number No / 5 Maximum number of items from the result set to response
with. Must be between 1 and 11.
accountId UUID No / None The id of an Account each returned RealCardAccount must
be associated with.
name String No / None Filter the results to accounts which contain this value
(white space is ignored)
orderBy String No / Name Single value from the following (case insensitive)
• Name
• CreatedAt
• UpdatedAt
orderByDirection String No / Asc Single value from the following (case insensitive)
• Asc
• Desc
statuses String() No / None An array of the following statuses (case insensitive)
• Disabled
• Enabled
• Cancelled
If no statuses are passed, all will be returned.
Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being an array of matched RealCardAccount objects.

Otherwise, depending on status returned, an ErrorResponse object is returned.

Proprietary and confidential © Dataflexnet 2021 28

 2.9.3 RealCard
[Link] Create (Provision) RealCard
Description
Creates a new RealCard against an existing RealCardAccount by reference to the RealCardAccount’s id as returned
from the API for the desired RealCardAccount. This newly created RealCard is made current for the
RealCardAccount. The previous current RealCard will continue to be related with the same RealCardAccount but is
no longer the current RealCard.

The RealCard expires end must be in the current month or later.

If the RealCard is replacing a current RealCard on a RealCardAccount then both currencies must match.

If unsupported by the issuer, the replacing of a RealCard on a RealCardAccount will not be permitted.

Request
Verb POST

Scope vc-accounts-modify

vc-accounts-sensitive

If this vc-accounts-sensitive scope is present then the plain text pan parameter is correctly returned
on the RealCard object, otherwise, the pan value returned is an empty string.

Path /v2/realCards

Body RealCard object

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the new RealCard object. Otherwise, depending on
status returned, an ErrorResponse object is returned.

[Link] Update RealCard

Description
Updates an existing RealCard. The RealCard is referenced by the id returned from the API for the same RealCard.

Request
Verb PATCH

Scope vc-accounts-modify

vc-accounts-sensitive

If this vc-accounts-sensitive scope is present then the plain text pan parameter is correctly returned on
the RealCard object, otherwise, the pan value returned is an empty string.

Path /v2/realCards/{id}

Body RealCard object

Param None

Response

Proprietary and confidential © Dataflexnet 2021 29

Status See standard responses.

Body If successful, a SuccessResponse is returned being the updated RealCard object. Otherwise, depending
on status returned, an ErrorResponse object is returned.

[Link] Query RealCard

Description
Fetch a RealCard object by id. The RealCard is referenced by the id returned from the API for the same RealCard.

Request
Verb GET

Scope vc-accounts-view

vc-accounts-sensitive

If this vc-accounts-sensitive scope is present then the plain text pan parameter is correctly returned on
the RealCard object, otherwise, the pan value returned is an empty string.

Path /v2/realCards/{id}

Body No content

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned with the RealCard object. Otherwise, depending on status
returned, an ErrorResponse object is returned.

[Link] Query RealCards

Description
Fetch many RealCard objects matching the search criteria.

RealCard objects are returned in ascending order of creation.

Request
Verb GET

Scope vc-accounts-view

vc-accounts-sensitive

If this vc-accounts-sensitive scope is present then the plain text pan parameter is correctly returned for
each RealCard object, otherwise, the pan value returned is an empty string.

Path /v2/realCards

Body No content

Param These parameters are supported,

Name Type Required / Default

offset Number No / 0 Offset into result set from which to respond with. Must
be equal or greater than 0.
size Number No / 5 Maximum number of items from the result set to
response with. Must be between 1 and 11.

Proprietary and confidential © Dataflexnet 2021 30

 realCardAccountId UUID No / None The id of a RealCardAccount each returned RealCard
must be associated with.
onlyCurrent Boolean No / All Each returned RealCard must be current for a
RealCardAccount.
Response
Status See standard responses.

Body If successful, a SuccessResponse is returned with an array of matched RealCard objects. Otherwise,
depending on status returned, an ErrorResponse object is returned.

Proprietary and confidential © Dataflexnet 2021 31

 2.9.4 VirtualCard
[Link] Create VirtualCard
Description
Create a VirtualCard. The VirtualCard can be referenced by the id returned from the API for the same VirtualCard.

Request
Verb POST

Scope vc-virtualcard-modify

vc-virtualcard-sensitive

If this vc-accounts-sensitive scope is present then the plain text pan and cvv2 parameter is correctly
returned on the VirtualCard object, otherwise, the pan and cvv2 value returned is an empty string.

Path /v2/virtualCards

Body VirtualCard object

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the new VirtualCard object. Otherwise, depending
on status returned, an ErrorResponse object is returned.

[Link] Enable VirtualCard

Description
Enable an existing VIrtualCard as update. The VirtualCard is referenced by the id returned from the API for the
same VirtualCard.

Request
Verb POST

Scope vc-virtualcards-modify

Path /v2/virtualCards/{id}/enable

Body No content

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the updated VirtualCard object. Otherwise,
depending on status returned, an ErrorResponse object is returned.

[Link] Disable VirtualCard

Description
Disable an existing VIrtualCard as update. The VIrtualCard is referenced by the id returned from the API for the
same VIrtualCard.

Request
Verb POST

Proprietary and confidential © Dataflexnet 2021 32

Scope vc-virtualcards-modify

Path /v2/virtualCards/{id}/disable

Body No content

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the updated VirtualCard object. Otherwise,
depending on status returned, an ErrorResponse object is returned.

[Link] Cancel VirtualCard

Description
Cancels an existing VirtualCard as update. The VirtualCard is referenced by the id returned from the API for the
same VirtualCard.

A cancelled VirtualCard cannot be undone.

Cancelling a VirtualCard has a cascade effect on state, including but not limited to,

• The following cascade functionality is not implemented in Virtual Card v9.0, but will be implemented in a
future release:

• All SharePays will be revoked against now cancelled VirtualCards.

Request
Verb POST

Scope vc-virtualcards-modify

Path /v2/virtualCards/{id}/cancel

Body No content

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned being the updated VirtualCard object. Otherwise,
depending on status returned, an ErrorResponse object is returned.

[Link] Query VirtualCard

Description
Fetch a VirtualCard object by id. The VirtualCard is referenced by the id returned from the API for the same
VirtualCard.

Request
Verb GET

Scope vc-virtualcards-view

vc-virtualcards-sensitive

Proprietary and confidential © Dataflexnet 2021 33

 If this vc-virtualcards-sensitive scope is present then the plain text pan and cvv2 parameter is correctly
returned on the VirtualCard object, otherwise, the pan and cvv2 value returned is an empty string.

Path /v2/virtualCards/{id}

Body No content

Param None

Response
Status See standard responses.

Body If successful, a SuccessResponse is returned with the VirtualCard object. Otherwise, depending on
status returned, an ErrorResponse object is returned.

Proprietary and confidential © Dataflexnet 2021 34

 2.9.6 Query Health
Description
External monitoring endpoint(s) to determine connectivity and reported health of the resources. Please check for
200 status code and that the status field is Pass to confirm all is good.

Request
Verb GET

Scope None

Path /v2/health

Body None

Param None

Response
Status 200

Body The following JSON is responded as content,

{ "status": "Pass" }

Proprietary and confidential © Dataflexnet 2021 35

3 Authentication and Authorisation
The API authorisation is by bearer access token. Access tokens must be obtained from the Dataflexnet
authentication service, with which the deployment of the software client must authentication itself, and where the
software client securely retains its client credential associated secrets.

These sub-sections cover more ground. As the Dataflexnet authentication service is standards-based we refer to
those standards, as necessary.

3.1 Authorisation
In oAuth 2 terminology, the API is considered a resource server and for authentication an access token must be
presented to the API by the software client using the Authorization Request Header field following the Bearer
authentication scheme. The Bearer authentication scheme is defined in section 2.1 of rfc6760.

An invalid token is presented, no matter the reason, the API will be responded to with HTTP status code 401 with
an error content body. It will not disclose a reason that would compromise security.

3.2 Authentication
The software client must obtain access tokens from the Dataflexnet authentication service. Dataflexnet can
provide separate documentation to cover this topic is greater detail as complement to the well documented
standard protocols that are leveraged.

Before any deployment of a software client can authenticate, an out of bound setup procedure must be followed
by authorised personnel that establishes a client credential for that deployment. The procedure securely
establishes (and assists the ongoing management of) the necessary secret(s) for authentication. This procedure is
also covered in separate documentation in greater detail.

A successful response will yield an access token. It will be short-lived. It is important that no assumption of the
access token’s lifetime is made. It is important that the access token is always held in confidence.

3.3 Management of Client Credentials

The owner is responsible for life-time management of their client credential secrets with the authentication service
by authorised personnel. Otherwise, the owner will manage their secrets according to their own policies,
procedures, and standards.

Several client credentials may be maintained as valid for each deployment of a software client at any one time. This
allows for rotation of secrets. It also allows the owner to manage client credentials across segmented
environments if necessary.

Dataflexnet will require the owner to clearly distinguish between production and non-production when requesting
new client credentials.

3.4 IPv4 Whitelisting of Client Credentials

Dataflexnet offers the option to IP whitelist per setup client credential. If requested, the authentication service will
only accept authentication service requests from the given IP CIDRs.

3.5 Automatic Configuration

The Dataflexnet authentication service implements the OpenID Connect v1 Discovery protocol (v1), which is
calculated from the authentication service domain, according to protocol,

[Link]

The above by protocol will translated into [Link] but must

itself not be hardcoded directly.

It is very important that only the authentication service domain is configured by the owner and that all other
configuration is obtained dynamically using discovery. The owner’s software client may fail if any other value is
hard coded since it is subject to change at any time.

Proprietary and confidential © Dataflexnet 2021 36

4 Non-Functional
4.1 Scope
The client credentials provided to the owner implicitly limit the scope of data that can be accessed.

The oAuth 2 scopes allowed to be requested by the owner’s deployment of software clients will also limit access.

The capability of the issuer may limit features.

The API implicitly can only operate on a per instance basis.

4.2 Deprecation
Dataflexnet has no wish to maintain an API legacy. As such, we require integrators to upgrade to the latest version
of the API in good time. Dataflexnet will therefore maintain prior version(s) of the API for at least a period of two
years once marked for deprecation.

Dataflexnet plan to deprecate older versions of this API when a newer version is released. Dataflexnet will clearly
communicate notices of deprecation.

Dataflexnet reserve the right to deprecate more quickly to meet contractual, legal, or regulation requirements.

4.3 Security
Key points,

• All communications will be HTTPS v2 - v1.1 using TLS 1.2 or higher, with suitable ciphers and key exchange
suites configured. A software client must be able to negotiate a connection and explicitly validate
Dataflexnet certificates are valid and correct. Dataflexnet will ensure their certificate is valid and managed
in a compliant fashion under PCI DSS.

• Authentication on the API requires the software client to obtain a bearer access token from Dataflexnet
authentication service and with necessary scope. This will require owner of the software client to manage
secret(s), one per deployment of a software client, according to their own policies and procedures, in
collaboration with the authentication service, for establishing client credentials with the authentication
service.

• The owner has the option to whitelist IPs for each client credential described above.

4.4 Service Levels

Dataflexnet will comply with its commercial agreements only.

The API may respond with 429 if you exceed your quota in relation to commercial agreements. You are required to
respond to 429 by reducing the rate of calls you make against the API. As example, one approach might implement
a limited retry strategy that incorporates an exponential back off, though it is up to the integrator to determine the
best strategy of course.

The API may respond with 503 if it is currently unavailable due to maintenance.

Proprietary and confidential © Dataflexnet 2021 37

5 Glossary
Term Explanation
oAuth 2.0 A set of authorisation protocols.
OIDC v1 OpenID Connect v1 is a set of standards that build upon oAuth 2.0 mainly
introducing the idea of identity-based authentication, grants, and
authorisations.
Client Client software.
OP An OIDC v1 provider.
CHD Card holder data as defined by PCI DSS.
SAD Sensitive authentication data as defined by PCI DSS.
Enum A set of defined enumerations.
API Application programming interface.
RP A Relying Party is a server providing access to a secure client software.
Claims-based client software, where a claim is a statement an entity
makes about itself in order to establish access, are also called Relying
Party applications.
UTF8 UTF-8 (8-bit Unicode Transformation Format) is a variable width
character encoding capable of encoding all 1,112,064 valid code points in
Unicode using one to four one-byte (8-bit) code units.
GZIP gzip is a format and a software application used for file compression and
decompression.
JSON JavaScript Object Notation is an open standard file format, and data
interchange format, that uses human-readable text to store and transmit
data objects consisting of attribute–value pairs and array data types (or
any other serializable value).
RSA RSA key is a private key based on RSA algorithm. Private Key is used for
authentication and a symmetric key exchange during establishment of an
SSL/TLS session. It is a part of the public key infrastructure that is
generally used in case of SSL certificates.
TLS The SSL or TLS handshake enables the SSL or TLS client and server to
establish the secret keys with which they communicate. ... SSL or TLS
then uses the shared key for the symmetric encryption of messages,
which is faster than asymmetric encryption.
PCI DSS The Payment Card Industry Data Security Standard is an information
security standard for organizations that handle branded credit cards
from the major card schemes. The PCI Standard is mandated by the card
brands but administered by the Payment Card Industry Security
Standards Council.
HTTP(S) HTTP means HyperText Transfer Protocol. HTTP is the underlying
protocol used by the World Wide Web and this protocol defines how
messages are formatted and transmitted, and what actions Web servers
and browsers should take in response to various commands.
UUID Universally Unique IDentifier as defined by RFC 4122

Virtual Card API v2r9.1 Page 38 of 38