Product version Nium 3.94
Last edited November 2022
Produces
All the APIs produce "application/json" content. Refer to the API Reference for examples.
Structured String Parameters
Some response body parameters are documented as type "String" in the API Reference but whose value is similar to JSON. The structures of these parameters will be documented below. To generate code for your target language there are various tools, for a quick web based tool see JSON Schema to pojo.
Get Virtual Card Details Response
The "cardInfo" and "orderedCardInfo" parameters represent a JSON Array as a String value. The structure of these parameters is shown below. The number of allowed key value pairs in this case must not exceed 20.
[
{
"KEY_1":"VALUE:1"
},
{
"KEY_2":"VALUE:2"
},
]
Get Virtual Card Transactions Response
The "statement" parameter represent a JSON Array as a String value.
The structure of this parameter, after sanitisations such as removing unnecessary escaping, should map into object structures as defined by the component schemas below.
{
"components": {
"schemas": {
"KeyValuePair": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
},
"description": "Contains sorted custom additional information for the transaction"
},
"Statement": {
"required": [
"balance",
"date",
"description",
"externalIdentifier",
"feeAmount",
"forexAmount",
"forexBaseRate",
"forexFee",
"forexFeeCurrency",
"forexRate",
"fundsCredited",
"fundsDebited",
"orderedTransactionInfo",
"timestamp",
"transactionInfo",
"transactionMetadata",
"transactionReference",
"transactionType"
],
"type": "object",
"properties": {
"transactionReference": {
"type": "string",
"description": "Represents a unique identifier associated with a transaction. Note: A transaction may be split into several fund movement records. For example, three fund movement records may be returned for one transaction: a transfer record, a foreign exchange fee record, and a transfer fee record. In this case, all fund movement records share the same transactionReference"
},
"transactionType": {
"type": "string",
"description": "Represents the type of the transaction.",
"enum": [
"CARD_CREATE",
"CARD_STATE_CHANGE",
"CARD_RENEWAL",
"CARD_DESTROY",
"SETTLEMENT",
"DISPUTE",
"EXPIRY_EXTENSION",
"TRANSFER",
"DEDUCT_FEE",
"RETURN_FEE",
"SYSTEM_TRANSFER",
"SYSTEM_CREDIT_DEBIT",
"LOSS_RECOVERY"
]
},
"transactionMetadata": {
"type": "array",
"description": "This is a custom field with additional information on the transaction component. This additional information is used to build a custom description.",
"items": {
"$ref": "#/components/schemas/KeyValuePair"
}
},
"timestamp": {
"type": "string",
"description": "Represents the date and time when the transaction occurred in ISO8601 format",
"format": "date-time"
},
"date": {
"type": "string",
"description": "Represents the date when the transaction occurred. The date format conforms to ISO8601 (YYYY-MM-DD)",
"format": "date",
"example": "2022-03-20"
},
"description": {
"type": "string",
"description": "Contains a description of the transaction component"
},
"fundsCredited": {
"type": "string",
"description": "Contains the amount of funds credited on the virtual card by this transaction component. May be omitted if the component was a debitContains a description of the transaction component"
},
"fundsDebited": {
"type": "string",
"description": "Contains the amount of funds debited from the virtual card by this transaction component. May be omitted if the component was a credit"
},
"balance": {
"type": "string",
"description": "Contains the resulting balance on the virtual card after this transaction component"
},
"externalIdentifier": {
"type": "string",
"description": "Represents the customer external identifier of the transaction"
},
"feeAmount": {
"type": "string",
"description": "Represents the transaction fee charged"
},
"forexRate": {
"type": "string",
"description": "Represents the foreign exchange rate between the source and destination currency. For example, with a source currency of EUR and a destination currency of GBP, a rate of 0.8852 means that GBP 0.8852 = EUR 1. The Forex fee component is included in the rate"
},
"forexBaseRate": {
"type": "string",
"description": "Represents the foreign exchange rate between the source and destination currency excluding the fee component"
},
"forexFeeCurrency": {
"type": "string",
"description": "Represents the currency of the Forex fee. If the amount currency is set on source, then the Forex fee will be in destination currency. If amount is set on destination currency, then the Forex currency will be of the source. For example, if source EUR 200 is converted to GBP 144 and GBP is the currency of the destination, the Forex fee would be GBP 2.00"
},
"forexFee": {
"type": "string",
"description": "Contains the Forex fee charged for the indicated card, if available. For example, 2.00. The currency is in the forexFeeCurrency parameter"
},
"forexAmount": {
"type": "string",
"description": "If the transaction component contains Forex, this parameter contains the original amount of the transaction before the Forex conversion is indicated. For example, if EUR 200 was converted to GBP 144, EUR 200 will be returned"
},
"forexEcbRate": {
"type": "string",
"description": "A reference rate defined by the European Central Bank and is intended for information purposes only."
},
"transactionInfo": {
"type": "array",
"description": "Contains custom additional information for the transaction",
"items": {
"$ref": "#/components/schemas/KeyValuePair"
}
},
"orderedTransactionInfo": {
"type": "array",
"description": "Contains sorted custom additional information for the transaction",
"items": {
"$ref": "#/components/schemas/KeyValuePair"
}
}
}
}
}
}
}
Get Virtual Card Batch Entries Response
The "batchEntries" parameter represent a JSON Array as a String value.
The structure of this parameter, after sanitisations such as removing unnecessary escaping, should map into object structures as defined by the component schemas below.
{
"components": {
"schemas": {
"KeyValuePair": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
},
"description": "Contains pairs of additional information"
},
"BatchEntry": {
"required": [
"cardReference",
"entryReference",
"feeAmount",
"feeCurrency",
"status"
],
"type": "object",
"properties": {
"entryReference": {
"type": "string",
"description": "Indicates a reference for a particular card requested in the batch"
},
"status": {
"type": "string",
"description": "Represents the status of the virtual card",
"enum": [
"ACTIVE",
"INACTIVE",
"DELETED"
]
},
"cardReference": {
"type": "string",
"description": "A unique identifier for the indicated card when available"
},
"failureReason": {
"type": "string",
"description": "The reason why a failure occurred (if any)"
},
"fundingAccountReference": {
"type": "string",
"description": "If applicable, represents the funding account from where the initial load and/or the creation and transfer charges are taken"
},
"feeCurrency": {
"type": "string",
"description": "If applicable, represents the currency of the funding account which is also the creation and transfer fee currency"
},
"feeAmount": {
"type": "string",
"description": "If available, represents the transaction fee charged for the indicated card"
},
"externalIdentifier": {
"type": "string",
"description": "Contains a custom external identifier of the virtual card"
},
"cardInfo": {
"$ref": "#/components/schemas/KeyValuePair"
},
"orderedCardInfo": {
"$ref": "#/components/schemas/KeyValuePair"
}
},
"description": "Represents a virtual card entry"
}
}
}
}
Get Virtual Card Authorisations Response
The "statement" parameter represent a JSON Array as a String value.
The structure of this parameter, after sanitisations such as removing unnecessary escaping, should map into object structures as defined by the component schemas below.
{
"components": {
"schemas": {
"Statement": {
"required": [
"authCode",
"billingAmount",
"creditAdjustment",
"date",
"effectedMerchant",
"notificationCase",
"timestamp",
"transactionReference",
"transactionState"
],
"type": "object",
"properties": {
"transactionReference": {
"type": "string",
"description": "Represents a unique internal Nium identifier associated with this authorisation record"
},
"date": {
"type": "string",
"description": "Represents the date when authorisation occurred. The date format conforms to ISO 8601 (YYYY-MM-DD)",
"format": "date"
},
"timestamp": {
"type": "string",
"description": "Represents the date and time when authorisation occurred. The format of this value conforms to ISO 8601",
"format": "date-time"
},
"transactionState": {
"type": "string",
"description": "Represents the specific state of the authorisation record",
"enum": [
"PRE_INITIALISED",
"INITIALISED",
"ALREADY_PROCESSED",
"CASE_PROCESSING",
"EXPIRED",
"FAILED",
"COMPLETED"
]
},
"effectedMerchant": {
"type": "string",
"description": "Contains the name of the merchant that requested authorisation"
},
"notificationCase": {
"type": "string",
"description": "Contains a description of the authorisation case",
"enum": [
"NORMAL_PUT",
"REVERSE_PUT",
"EXPIRY_PUT",
"CLOSE_PUT",
"NORMAL_TAKE",
"REVERSE_TAKE",
"EXPIRY_TAKE",
"CLOSE_TAKE",
"DECLINED_TAKE",
"DECLINED_REVERSE_TAKE"
]
},
"creditAdjustment": {
"type": "string",
"description": "Represents the type of adjustment.",
"enum": [
"DEBIT",
"CREDIT"
]
},
"availableBalance": {
"type": "string",
"description": "Represents the available balance for the card after the authorisation. Important: If authorisation is received from a file (normal authorisation not real-time authorisation): The value of availableBalance is only provided for the first authorisation (for the card and for the day) Subsequent authorisations (for the card and for the day) have a null value of availableBalance This is because the actual available balance cannot be calculated without real-time authorisation information)"
},
"billingAmount": {
"type": "string",
"description": "Represents the amount of funds taken from the virtual card."
},
"transactionAmount": {
"type": "string",
"description": "Represents the original amount of the transaction."
},
"transactionCurrency": {
"type": "string",
"description": "Represents the original currency of the transaction."
},
"terminalCountryCode": {
"type": "string",
"description": "Represents the merchant country code."
},
"authCode": {
"type": "string",
"description": "Represents a unique identifier of the authorisation received from the processor. This identifier is used to link different authorisations records (for example a NORMAL_TAKE authorisation with a REVERSE_TAKE authorisation that follows) as well as authorisation records and settlements."
},
"responseCode": {
"type": "string",
"description": "Represents an authorisation status code received from the processor (if available). This code follows the ISO 8583 standard."
},
"forexEcbRate": {
"type": "string",
"description": "A reference rate defined by the European Central Bank and is intended for information purposes only."
}
},
"description": "A transaction statement representation"
}
}
}
}
Transaction States
| State | Description |
|---|---|
| PRE_INITIALISED | Indicates that the system has initiated the authorisation process but the transaction has not yet started. |
| INITIALISED | Indicates that the system has initialised the authorisation request and is about to check if it needs to be processed. |
| ALREADY_PROCESSED | Indicates that the system has discovered that the authorisation request had already been processed. |
| CASE_PROCESSING | Indicates that the system is currently processing the authorisation request. |
| EXPIRED | Indicates that the authorisation request has expired. |
| FAILED | Indicates that the authorisation request failed. |
| COMPLETED | Indicates that the authorisation process is completed. |
Notification Cases
| Case | Description |
|---|---|
| NORMAL_PUT | Represents an accepted authorisation for a transaction that increases the balance |
| REVERSE_PUT | Represents an accepted reversal of a NORMAL_PUT authorisation. Reversal is initiated by the merchant. |
| EXPIRY_PUT | Represents an expiry of a NORMAL_PUT authorisation. Expiry is initiated by the issuer. |
| CLOSE_PUT | Represents an explicit closure (manual expiry) of a NORMAL_PUT authorisation. Closure is initiated by the issuer. |
| NORMAL_TAKE | Represents an accepted authorisation for a transaction that reduces the balance. |
| REVERSE_TAKE | Represents an accepted reversal of a NORMAL_TAKE authorisation. Reversal is initiated by the merchant. |
| EXPIRY_TAKE | Represents an expiry of a NORMAL_TAKE authorisation. Expiry is initiated by the issuer. |
| CLOSE_TAKE | Represents an explicit closure (manual expiry) of a NORMAL_TAKE authorisation. Closure is initiated by the issuer. |
| DECLINED_TAKE | Represents a declined request for a NORMAL_TAKE authorisation. |
| DECLINED_REVERSE_TAKE | Represents a declined request for the reversal of a NORMAL_TAKE authorisation. |
Credit Adjustment Types
| Adjustment | Description |
|---|---|
| DEBIT | Represents a transaction that reduces the card balance, for example, a purchase or a reversal of a return. |
| CREDIT | Represents a transaction that increases the card balance, for example, a return or a reversal of a purchase. |
Get Funding Account Details Response
The "transactionInfo" parameter represent a JSON Array as a String value. The structure of these parameters is shown below. The number of allowed key value pairs in this case must not exceed 5.
[
{
"KEY_1":"VALUE:1"
},
{
"KEY_2":"VALUE:2"
},
]
Get Funding Account Transactions Response
The "statement" parameter represent a JSON Array as a String value. The structure of these parameters is shown below.
{
"components": {
"schemas": {
"KeyValuePair": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
},
"description": "Contains pairs of additional information"
},
"Statement": {
"required": [
"balance",
"date",
"description",
"externalIdentifier",
"feeAmount",
"forexAmount",
"forexBaseRate",
"forexFee",
"forexFeeCurrency",
"forexRate",
"fundsCredited",
"fundsDebited",
"orderedTransactionInfo",
"timestamp",
"transactionInfo",
"transactionMetadata",
"transactionReference",
"transactionType"
],
"type": "object",
"properties": {
"transactionReference": {
"type": "string",
"description": "Represents a unique identifier for the transaction."
},
"transactionType": {
"type": "string",
"description": "Represents the type of the transaction component.",
"enum": [
"INSTRUMENT_CREATE",
"INSTRUMENT_STATE_CHANGE",
"INSTRUMENT_DESTROY",
"DEPOSIT",
"RETURN_FUNDS",
"TRANSFER",
"INTERNAL_TRANSFER",
"WITHDRAWAL",
"DEDUCT_FEE",
"RETURN_FEE",
"SYSTEM_TRANSFER",
"SYSTEM_CREDIT_DEBIT",
"LOSS_RECOVERY"
]
},
"transactionMetadata": {
"type": "array",
"description": "This is a custom field with additional information on the transaction component. This additional information is used to build a custom description.",
"items": {
"$ref": "#/components/schemas/KeyValuePair"
}
},
"timestamp": {
"type": "string",
"description": "Represents the date and time when the transaction occurred",
"format": "date-time"
},
"date": {
"type": "string",
"description": "Represents the date when the transaction occurred.",
"format": "date"
},
"description": {
"type": "string",
"description": "Contains a description of the transaction component."
},
"fundsCredited": {
"type": "string",
"description": "Contains the amount of funds credited on the funding account by this transaction component. May be omitted if the component was a debit."
},
"fundsDebited": {
"type": "string",
"description": "Contains the amount of funds debited from the funding account by this transaction component. May be omitted if the component was a credit."
},
"balance": {
"type": "string",
"description": "Contains the resulting balance on the funding account after this transaction component."
},
"externalIdentifier": {
"type": "string",
"description": "Represents the customer external identifier of the transaction."
},
"feeAmount": {
"type": "string",
"description": "Represents the transaction fee charged."
},
"forexRate": {
"type": "string",
"description": "Represents the foreign exchange rate between the source and destination currency. For example, with a source currency of EUR and a destination currency of GBP, a rate of 0.8852 means that GBP 0.8852 = EUR 1. The Forex fee component is included in the rate."
},
"forexBaseRate": {
"type": "string",
"description": "Represents the foreign exchange rate between the source and destination currency excluding the fee component."
},
"forexFeeCurrency": {
"type": "string",
"description": "Represents the currency of the Forex fee. If the amount currency is set on source, then the Forex fee will be in destination currency. If amount is set on destination currency, then the Forex currency will be of the source. For example, if source EUR 200 is converted to GBP 144 and GBP is the currency of the destination, the Forex fee would be GBP 2.00."
},
"forexFee": {
"type": "string",
"description": "Contains the Forex fee charged for the indicated funding account, if available. For example, 2.00. The currency is in the forexFeeCurrency parameter."
},
"forexAmount": {
"type": "string",
"description": "If the transaction component contains Forex, this parameter contains the original amount of the transaction before the Forex conversion is indicated. For example, if EUR 200 was converted to GBP 144, EUR 200 will be returned."
},
"transactionInfo": {
"type": "array",
"description": "Contains custom additional information for the transaction.",
"items": {
"$ref": "#/components/schemas/KeyValuePair"
}
},
"orderedTransactionInfo": {
"type": "array",
"description": "Contains custom additional information for the transaction in a sorted manner.",
"items": {
"$ref": "#/components/schemas/KeyValuePair"
}
}
},
"description": "A transaction statement representation"
}
}
}
}
The transaction types are described below
| Transaction Type | Description |
|---|---|
| INSTRUMENT_CREATE | Represents the creation of a funding account. |
| INSTRUMENT_STATE_CHANGE | Represents the change of funding account state from active to inactive (freeze) or the other way around (thaw). |
| INSTRUMENT_DESTROY | Represents the deletion of a funding account or the deletion of a card if funds are returned to the funding account. |
| DEPOSIT | Represents funds being deposited on a funding account. |
| RETURN_FUNDS | Currently not used. |
| TRANSFER | Represents a transfer from a funding accountto a virtual card, or between 2 funding accounts. This includes the initial transfer when a card is created. |
| INTERNAL_TRANSFER | Represents a transfer between two funding accounts This is a deprecated transaction type and is retained for legacy purposes. |
| WITHDRAWAL | Represents a transfer of funds from a funding account to a bank account. |
| DEDUCT_FEE | Represents a deduction of a fee from the funding account balance. This is a deprecated transaction type and is retained for legacy purposes. Note: This type of transaction is for fees that are not associated with transactions. Fees associated with other transactions (for example, a card creation fee) are included in respective transactions. |
| RETURN_FEE | Represents the reversal of a DEDUCT_FEE transaction. Note: This type of transaction is for fees that are not associated with transactions. Fees associated with other transactions (forexample, a card creation fee) are included in respective transactions. |
| SYSTEM_TRANSFER | Represents a manual transfer made by a financial operator. |
| SYSTEM_CREDIT_DEBIT | Represents a manual balance modification (credit or debit) by a financial operator. |
| LOSS_RECOVERY | Represents the recovery of funds from a funding account to a virtual card. For example, there may be a charge for a settlement but a virtual card may not have enough balance for such a charge. In such case, the system takes funds from the funding account of origin to cover the charge. |
Get Scheduled Load Details Response
The "scheduleInfo" parameter represent a JSON Array as a String value. The structure of these parameters is shown below. The number of allowed key value pairs in this case must not exceed 5.
[
{
"KEY_1":"VALUE:1"
},
{
"KEY_2":"VALUE:2"
},
]
Get Scheduled Load List Response
The "scheduledInstructionEntries" parameter represent a JSON Array as a String value.
The structure of this parameter, after sanitisations such as removing unnecessary escaping, should map into object structures as defined by the component schemas below.
{
"components": {
"schemas": {
"KeyValuePair": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
},
"description": "Contains pairs of additional information"
},
"ScheduledLoadListEntry": {
"required": [
"amount",
"cardReference",
"clearanceDate",
"currency",
"externalIdentifier",
"fundingAccountReference",
"scheduleDate",
"scheduleInfo",
"scheduleReference",
"state",
"timestamp"
],
"type": "object",
"properties": {
"scheduleReference": {
"type": "string",
"description": "Represents a unique identifier for the scheduled load."
},
"timestamp": {
"type": "string",
"description": "Contains a timestamp of when the scheduled load was created."
},
"cardReference": {
"type": "string",
"description": "Identifies the virtual card that funds are to be transferred to."
},
"fundingAccountReference": {
"type": "string",
"description": "Identifies the funding account supplying the funds for the transfer."
},
"amount": {
"type": "string",
"description": "Contains the amount of funds to be transferred."
},
"currency": {
"type": "string",
"description": "Represents the currency of the virtual card."
},
"scheduleDate": {
"type": "string",
"description": "Represents the card loading date. ",
"format": "date"
},
"clearanceDate": {
"type": "string",
"description": "The date (in GMT) when the card was or will be emptied and deleted. Cards are cleared at the end of the day, 23:59:59 GMT.",
"format": "date"
},
"externalIdentifier": {
"type": "string",
"description": "This is a custom field that can be used to uniquely identify the scheduled load."
},
"scheduleInfo": {
"type": "array",
"description": "Contains custom additional information on the scheduled load.",
"items": {
"$ref": "#/components/schemas/KeyValuePair"
}
},
"state": {
"type": "string",
"description": "Represents the state of the scheduled load instruction. NOTE: For any scheduled loads created prior to 3.86, PROCESSING_CLEARANCE and PENDING_CLEARANCE may still be returned. However, as from 3.87, COMPLETED will be returned instead.",
"enum": [
"PENDING_LOAD",
"PROCESSING_LOAD",
"CANCELLED",
"COMPLETED",
"FAILED"
]
},
"failureReason": {
"type": "string",
"description": "Contains the reason why the scheduled load has failed. This parameter is returned whenever the value of the parameter state returned in the response is FAILED."
}
},
"description": "Scheduled load entry representation"
}
}
}
}
Get Instrument List Response
The "instrumentList" parameter represent a JSON Array as a String value.
The structure of this parameter, after sanitisations such as removing unnecessary escaping, should map into object structures as defined by the component schemas below.
{
"components": {
"schemas": {
"Statement": {
"required": [
"instrumentReference",
"instrumentName",
"type",
"state"
],
"type": "object",
"properties": {
"instrumentReference": {
"type": "string",
"description": "Represents a unique identifier of the current instrument entry."
},
"instrumentName": {
"type": "string",
"description": "Contains a friendly name for the current instrument entry"
},
"type": {
"type": "string",
"description": "Represents the type of the current instrument entry."
},
"state": {
"type": "string",
"description": "Represents the state of the current instrument entry."
}
},
"description": "An instrument entry representation"
}
}
}
}