Delegated Models

The authorization API for the Dynamic Authorization consists of a request and a response body. Nium sends the request body to the authorization endpoint. The authorization endpoint accepts the request payload in the specification the document provides. The response payload contains fields in which the API responds to Nium for processing.

With Delegated Model requests, Nium delays the response to the card network and sends the request to your system for your decision.

1. Delegated Model flow

As the client, your two key tasks are to apply any rules that you may have and also deduct the customer's balance based on sufficient funds.

1.1 Authorization

Authorization headers

Headers	Parameters
Content-Type	application/octet-stream
x-request-id	Universally Unique Identifier (UUID)
x-client-name	String
[client-customized-headers]	String (static value only)

Request body

Fields	Description	Type
transactionId	The transaction ID is a Nium-generated 36-character UUID, which is unique per transaction.	UUID
transactionType	Allowed transaction type:•DEBIT	String
cardHashId	A unique card identifier generated during a new card issuance.	UUID
processingCode	The processing code is a 2-character field. Refer to the table below for more details on the processing code.•00 - Purchase transaction•01 - Cash Withdrawal or Cash Disbursement•02 - Debit Adjustment•09 - Purchase with Cashback•10 - Account Funding•11 - Quasi Cash Transaction (Debit)•20 - Merchant Return / Refund•21 - Incoming Credit for Mastercard•22 - Credit Adjustment•26 - Incoming Credit for Visa	String
billingAmount	The amount of funds that the cardholder requests. It needs to be represented in the cardholder billing currency.The amount is 0 in case of an account verification request.	Double
transactionAmount	The amount that the merchant charges the cardholder in the currency as defined in transactionCurrencyCode.The amount is 0 in case of an account verification request.	Double
billingCurrencyCode	The billing currency refers to the currency used by the card network and NIUM for end-of-day settlements. The format of this field should be a 3-letter code representing the currency. 3-letter ISO-4217 currency code	String
transactionCurrencyCode	The transaction currency is the currency being used in the transaction between the cardholder and merchant. The format of this field contains the 3-letter ISO-4217 currency code.	String
authCurrencyCode	The auth currency code is the currency being used in the transaction between NIUM and cardholder wallet account. The format of this field should be a 3-letter code representing the currency - 3-letter ISO-4217 currency code.	String
authAmount	The auth amount displays the amount charged by Nium to the cardholder wallet account during their purchase, and it is denoted in authCurrencyCode.	Double
effectiveAuthAmount	The effective auth amount refers to the combined total of the "authAmount" and the charges documented under transactionFees. And it is denoted in authCurrencyCode.	Double
billingConversionRate	The rate used by the card network to convert the transaction amount to the cardholder billing amount.	String
dateOfTransaction	The transaction date is shown in the format of MMDDHHMMSS using UTC time.	String
localTime	Reserved for future	String
localDate	Reserved for future	String
merchantCategoryCode	The code that defines the type of business, product, or service offered by a merchant is called the Merchant Category Code (MCC). MCC List	String
merchantTerminalId	A code that identifies a terminal at the card acceptor location (TID).	String
merchantTerminalIdCode	A merchant ID number, also known as a merchant number or MID, is a 15-digit numerical identifier that uniquely identifies a merchant.	String
merchantNameLocation	A name and location of the card acceptor (merchant), including the city name and country codeposition 1-25: card acceptor nameposition 26-38: city nameposition 39-40: country code	String
posEntryMode	This is a 4-digit code that identifies the actual method used at the point of service to enter the cardholder account number and the card expiration date.Position 1-2:•00: Unknown or terminal not used•01: Manual Key Entry•02: Magnetic Stripe•03: Bar code read (VISA only)•05: Chip card read•07: Proximity payment originating using VSDC chip data rules•10: Credential stored on filePosition 3:•0: Unknown•1: terminal can accept and forward online PINs•2: terminal cannot accept and forward online PINs	String
posConditionCode	A code identifying transaction conditions at the point-of-sale or point of service.•00 - Normal transaction•01 - Cardholder not present•02 - Unattended cardholder-activated environment•03 - Merchant suspicious•05 - Cardholder present, card not present•06 - Preauthorized request•08 - Mail/telephone order•51 - Account verification request (AVR)•55 - ICC capable branch ATM•59 - Electronic commerce•90 - Recurring payment	String
posEntryCapabilityCode	This field provides information about the terminal used at the point of service. The type of terminal field values include:•0 - Unspecified•2 - Unattended terminal (customer-operated)•4 - Electronic cash register•7 - Telephone device•8 - MCAS device•9 - Mobile acceptance solution (mPOS)Capability of terminal field values include:•0 - Unspecified•1 - Terminal not used•2 - Magnetic stripe read capability•5 - Integrated circuit card read capability	UUID
retrievalReferenceNumber	A 12-digit number that's used with other data elements as a key to identify and track all messages related to a given customer transaction.	String
systemTraceAuditNumber	A 6-digit number that the message initiator assigns that uniquely identifies a transaction.	String
acquiringInstitutionCountryCode	This field accepts the 3-digit ISO country code for the acquiring institution.	String
acquiringInstitutionCode	A code that identifies the financial institution acting as the acquirer of the transaction.	String
paymentServiceFields	This is a private use field. It contains the first data merchant number.	String
originalDateOfTransaction	Original transaction date of the purchase, this is present for correction or reversal transaction.	String
originalSystemTraceAuditNumber	Original System trace Audit Number of the purchase, this is present for correction or reversal transaction.	String
originalTransactionId	Original transaction Id of the purchase, this is present for correction or reversal transaction.	UUID
transactionFees	This field is an array containing a list of fees that need to be applied to a given transaction. The valid names of fees are ATM_FEE, POS_FEE, ECOM_FEE, and TRANSACTION_MARKUP.	Array
transactionFees.name	The name of the fees or markup.	String
transactionFees.value	The amount of the fees or markup.	Double
transactionFees.currencyCode	This field contains the 2-letter ISO-2 country code for identifying the country prefix to a mobile number.	String
billingReplacementAmount	Deprecated. This field is no longer in use and should be ignored.	Double
transactionReplacementAmount	Deprecated. This field is no longer in use and should be ignored.	Double

Request example

curl -X POST \
  'http://<client-authorization-endpoint>' \
    -H 'content-type: application/octet-stream' \
    -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
    -H 'x-client-name: Nium-Collaborative-Service' \      
  -d '{
    "transactionId": "5047d30f-e348-4baa-87c0-d799a63f8965",
    "transactionType": "DEBIT",
    "cardHashId": "a5ce460c-2ead-4e25-ad6c-b3a6e9d727ec",
    "processingCode": "010000",
    "billingAmount": 1.3,
    "transactionAmount": 1.12,
    "billingCurrencyCode": "SGD",
    "transactionCurrencyCode": "USD",
    "authCurrencyCode": "USD",
    "authAmount": 1.12,
    "effectiveAuthAmount": 1.14,
    "billingConversionRate": "1.000000000",
    "dateOfTransaction": "2601233174",
    "localTime": null,
    "localDate": null,
    "merchantCategoryCode": "5834",
    "merchantTerminalId": "450480",
    "merchantTerminalIdCode": null,
    "merchantNameLocation": null,
    "posEntryMode": "0710",
    "posConditionCode": "59",
    "posEntryCapabilityCode": null,
    "retrievalReferenceNumber": "344154374485",
    "systemTraceAuditNumber": "374485",
    "acquiringInstitutionCountryCode": "702",
    "acquiringInstitutionCode": "489028",
    "paymentServiceFields": null,
    "originalTransactionId": null,
    "originalDateOfTransaction": null,
    "originalSystemTraceAuditNumber": null,
    "originalAcquiringInstitutionCode": null,
    "billingReplacementAmount": 0.0,
    "transactionReplacementAmount": 0.0,
    "transactionFees": [
        {
            "name": "TRANSACTION_MARKUP",
            "value": 0.044,
            "currencyCode": "SGD"
        },
        {
            "name": "ECOM_FEE",
            "value": 0.02,
            "currencyCode": "USD"
        }
    ]
}'

📒 NOTE

The example request payload above isn't encrypted with a PGP key. In an actual integration, the payload is encrypted with Nium's public PGP key.

Response body

Field	Description	Type
responseCode	Choose an appropriate 2-digit response code, from the response code list below, under which the client can process the transaction.	String
partnerReferenceNumber	This is a unique number that the client generates for the given transaction which is used as a reference for it. We recommend clients generate a version 4 UUID.	String

Response example

{
    "responseCode": "00",
    "partnerReferenceNumber": "f2bc2c33-9bd0-4f16-be54-2a13ce9b174e"
}

📒 NOTE

The client is expected to send an HTTP 200 response status code with all responses. The following response payload isn't encrypted with a PGP key. In an actual integration, the payload is encrypted with Nium's public PGP key.

Response codes

Response code	Response reason	Notes
00	Success	This response code indicates that the authorization is approved.
03	Invalid Merchant	Use this decline reason code if you, as the client, know that this transaction isn't allowed for the cardholder, at this particular merchant, based on the merchant category code.
12	Invalid Transaction	Use this decline reason code if you, as the client, know that this transaction is invalid.
46	Account Closed	Use this decline reason code if you, as the client, know that this account is no longer valid or is closed.
51	Insufficient Funds	Use this decline reason code if you, as the client, know that the cardholder has insufficient funds in their account, wallet, or ledger.
57	Transaction not Permitted	Use this decline reason code if you, as the client, know that this transaction, based on some transaction data elements, isn't allowed for the cardholder.
61	Exceeds Amount-based Limits	Use this decline reason code if you, as the client, know that this transaction causes the cardholder to go above any amount-based limits that have been set up.
65	Exceeds Frequency-based Limits	Use this decline reason code if you, as the client, know that this transaction causes the cardholder to go above any frequency-based limits such as daily or monthly.

1.2 Timeout

Because the card networks require a timely response from Nium, there's a timeout limit on the response from your system. If you don't respond to Nium within 2 seconds, Nium declines the transaction to the card network.

Whenever a timeout occurs, a potential ledger mismatch could arise in your system. For example, consider the following scenario:

1. Nium sends a Delegated Model request to your end for an $88 expenditure.
2. After 2 seconds without receiving a response, the platform times out the request.
3. The platform declines the transaction to the card network.
4. A second later, your system finishes processing the authorization and attempts to respond with an authorization for $88.
5. This may become out of sync with the actual state of the transaction and the account balance.

For every transaction your system approves, Nium marks the transaction as Unsettled and provides a response to the scheme.

Timeout scenario

In the event of a timeout during your response to Nium, the following happens:

1. Nium declines the transaction to the scheme or network.
2. Nium credits the funds to your prefund account.
3. A reversal advice is sent to you with details about the original transaction.
4. You can reverse the transaction in the event the customer's wallet is debited at your end.

2. Settlement

The payment settlement process is established on a file-based approach. The file is in a fixed-length format. You need to pull the file from the Nium server daily.

📒 NOTE

You need to subscribe to the settlement file to use the Delegated Model.

2.1 Security

The Nium One platform provides a daily settlement file in a shared Secure File Transfer Protocol (SFTP) folder for your settlement purposes. The platform provides the host and path where the file resides. Use SFTP to access the server using your platform-issued username and password. You have read-only access to the path. The file is PGP encrypted using your public key, which you need to use to decrypt it.

💁 TIP

This file is encrypted with the same PGP public key that's used to encrypt the authorization payload. The file can then be decrypted using your private key.

2.2 File format

This report contains the end-of-day settlement data as received between Nium and the scheme.

There are two versions of the file format available for the daily client settlement report. Section 2.2.1 contains the latest version and 2.2.2 is the previous version that is deprecated and will eventually become unsupported.

As a client administrator, you can sign in to the Nium portal and view or download the settlement report based on the selected date range. You also have the option to have the file delivered to you over Secure File Transfer Protocol (SFTP).

2.2.1 Settlement file naming convention: [ClientHashID]_SETTLEMENT_YYYYMMDDHHmmSS.TXT.pgp

The following characteristics apply to this version of the settlement file

• Download file name convention: [ClientHashID]_SETTLEMENT_YYYYMMDDHHmmSS.TXT.pgp
• The extracted file naming convention is [ClientHashId]_SETTLEMENT_YYYYMMDDHHmmSS.TXT
• Fields in the settlement file are separated by a pipe ['|'] delimited
• Each settlement file contains three sections:
  a. Header
  b. Detail Record
  c. Trailer
• Current PGP encryption will apply, with no change in the logic.
• The last 10 columns are added for future use.

Design Abbreviations

Abbreviation	Description
AN	Alpha-Numeric
A	Alpha only
N	Numeric only
DT	Date

Header Record

Field Name	Field Type	Field Length	Sample Value	Description
Record Type	AN	1	H	Record Type Indicator, H indicates Header record.
Batch Date	N	8	20210425	This field indicates the posting date of the file sent to the SFTP. The file contains settlement records of the date with the format: yyyyMMdd.
Creation Date	N	14	20210426013548	This field indicates the creation date of the file. It has today's Nium cards processing date-time in UTC with the form: yyyyMMddHHmmss.
Client Hash Id	AN	36	123e4567-e89b-12d3-a456-426655440000	This field indicates the client’s unique ID.
File Identification	AN	21	DAILY SETTLEMENT FILE	Fixed value indicating that this is a daily settlement file

Detailed Record

Field Name	Field Type	Field Length	Sample Value	Description
Record Type	AN	1	D	Record Type Indicator, D indicates Detail record.
CardHashId	AN	36	3f860722-9f50-4689-9e3b-16c03560b7fc	The unique card hash ID.
Masked Card Number	AN	16	4111XXXXXXXX1111	Masked PAN
Transaction Id	AN	36	28b0de5c-576e-4d34-b747-db37d811fcd1	The transaction's unique transaction hash ID.
Partner Transaction Reference Number	AN	36	28b0de5c-576e-4d34-b747-db37d811fcd1	The transaction reference number provided by the partner.
Effective Date	N	8	20202004	The effective date when the settlement is released.
Batch Date	N	8	20202004	The batch of the settlement clearance.
Transaction Sign	A	1	D or C	D = Debit or C = Credit
Transaction Currency	A	3	SGD or AUD	3-character ISO3 currency code.
Transaction Amount	N	15,1,4	AAAAAAAAAAAAAAATDDDD	Transaction amount in format (15,1,4). A indicates the amount, T indicates the dot separating the decimals, D indicates the decimals.
Local Transaction Currency	A	3	SGD or AUD	3-character ISO3 currency code.
Local Transaction Amount	N	15,1,4	AAAAAAAAAAAAAAATDDDD	Local Transaction amount in format (15,1,4). A indicates the amount, T indicates the dot separating the decimals, D indicates the decimals.
Billing Currency	A	3	SGD or AUD	3-character ISO3 currency code.
Billing Amount	N	15,1,4	AAAAAAAAAAAAAAATDDDD	Transaction amount in format (15,1,4). A indicates the amount, T indicates the dot separating the decimals, D indicates the decimals.
Settlement Currency	A	3	SGD or AUD	3-character ISO3 currency code.
Settlement Amount	N	15,1,4	AAAAAAAAAAAAAAATDDDD	Transaction amount in format (15,1,4). A indicates the amount, T indicates the dot separating the decimals, D indicates the decimals.
Authorization Code	AN	6	557B06	6-character approval code for a transaction.
System Trace Audit Number (STAN)	N	12		This field contains a number assigned by the message initiator (merchant or acquirer) that uniquely identifies a cardholder transaction.
Retrieval Reference Number (RRN)	N	12		The acquirer usually defines it, but a merchant or an electronic terminal may define it.
Scheme Transaction Identifier	N	16		This contains a scheme-generated Transaction Identifier (TID) unique for each original authorization and financial request.
Description	AN	40	RETAIL ONLINE	Description of transaction.
Merchant Id	AN	12		Unique Id of the Merchant where the card was used.
Merchant Terminal Id	AN	8		Unique Id for the Terminal where the card was used.
Merchant Name	AN	25		Merchant Name / Card Acceptor Name or Automated Teller Machine (ATM) location
Merchant City	AN	13		City of the Merchant / Card Acceptor or the Automated Teller Machine (ATM)
Merchant Country	AN	2		Country of the Merchant / Card Acceptor or the Automated Teller Machine (ATM)
Merchant Category Code	N	4	6011	Alpha-numeric code identifying the merchant operating the POS/ATM.
Acquirer Id	N	12		This code identifies the financial institution acting as the acquirer of this customer transaction.
Multiple Settlement Indicator	A	1	M or F	M - Indicating Multiple; F - Indicating Final
Interchange Reference	N	25	78600000317792070999001	Interchange reference on transaction provided by merchant
Interchange Fee Sign	A	1	- or -	- for Positive; - for Negative
Interchange Fee	N	9
Original Interchange Fee Sign	a	1	- or -	- for Positive; - for Negative
Original Interchange Fee	N	15
Token Requestor ID	AN	11	40010030273	ApplePay / GooglePay Token Requester ID

** Trailer Record **

Field Name	Field Type	Field Length	Sample Value	Description
Record Type	AN	1	T	Record Type Indicator, T indicates Trailer record.
Record Count	N	9	000000002	This field indicates the total number of detail records.

2.2.2 Settlement file naming convention: [clientHashId]_MONTX_YYYYMMDDHHmmSS.TXT.pgp

⚠️ WARNING

This file is a deprecated version which will become unsupported in Jun 2024. Refer to section 2.2.1 Settlement file to get the latest version.

Each settlement file consists of the following three sections:

• Header record
• Transaction record
• Trailer record

💁 TIP

The total length of each settlement record in the file is 500 characters. Usually, the record data ends at 307 and is followed by spaces.

Header record structure

From	To	Field name	Format length	Example value	Description	Mandatory / Optional
1	13	Identifier	Alphanumeric (AN) length is 13 characters (13) AN(13)	0000000000000	This field contains all zeros to indicate it as a header record.	M
14	21	Batch Date	yyyyMMdd(08)	20210425	This field indicates the posting date of the file sent to the SFTP. The file contains settlement records of the date with the format: yyyyMMdd.	M
22	35	Creation Date	yyyyMMddHHmmss(14)	20210426013548	This field indicates the creation date of the file. It contains today's Nium cards processing date-time in UTC with the format: yyyyMMddHHmmss.	M
36	71	Client Hash ID	AN(36)	123e4567-e89b-12d3-a456-426655440000	This field indicates the client unique ID.	M
72	91	File Identification	AN(20)	TRANSACTION EXTRACT	This field indicates the identifier for the file.	M
92	500	Filler	AN(409)		Value = Spaces	O

Transaction record structure

From	To	Field name	Format length	Example value	Description	Mandatory / Optional
1	36	Card Hash ID	AN(36)	3f860722-9f50-4689-9e3b-16c03560b7fc	The unique card hash ID.	M
37	72	Transaction ID	AN(36)	28b0de5c-576e-4d34-b747-db37d811fcd1	The transaction's unique transaction hash ID.	O
73	108	Partner Transaction Reference Number	AN(36)	28b0de5c-576e-4d34-b747-db37d811fcd1	The transaction reference unique hash ID.	O
109	109	Record Type	AN(1)	M		M
110	117	Effective Date	9(8)	20202004	The effective date when the settlement is released.	M
118	125	Batch Date	9(8)	20202004	The batch of the settlement clearance.	M
126	126	Transaction Type	AN(1)	D	Type of transaction: Debit = D; Credit = C	M
127	131	Transaction Code	9(5)	00101	5 digits to refer debit and credit transactions: 00101 – RETAIL SALE; 00102 – SALE REVERSAL; 00103 – CASH ADVANCE; 00104 - CASH RVERSAL	M
132	151	Billing Amount	9(20)	00000000000000100000	Billing amount in format (15,4): 15 stands for whole, 4 stands for decimal value, 0 in 16th position stands for "."	M
152	154	Billing Currency Code	9(3)	SGD	3-digit ISO3 currency code.	M
155	174	Transaction Amount	9(20)	00000000000000100000	Transaction amount in format (15,4): 15 stands for whole, 4 stands for decimal value, 0 in 16th position stands for "."	O (space when the transaction amount is the same as the billing amount)
175	177	Transaction Currency Code	9(3)	SGD	3-digit ISO3 currency code.	O (space when the transaction currency is the same as the billing currency)
178	183	Authorization Code	9(6)	557006	6-digit code for an approved transaction.	O
184	223	Description	AN(40)	RETAIL ONLINE	Description of transaction.	O
224	239	Card Acceptor ID	AN(16)	CARD ACCEPTOR	Alphanumeric card acceptor ID.	M
240	262	Interchange Reference	9(23)	78600000317792070999001	Interchange reference on transaction provided by merchant.	M
263	277	Visa Transaction ID	9(15)	019164261950302	Unique ID provided for the transaction by Visa.	M
278	288	Token Requestor ID	AN(11)	40010030273	ApplePay / GooglePay Token Requester ID	M
289	307	Token Number	AN(19)	4513696691503434	ApplePay / GooglePay Token Number	M
308	500	For Future Purpose	AN(193)		To add additional fields in future	O

Trailer record structure

From	To	Field name	Format length	Example value	Description	M/O
1	13	Identifier	AN(13)	9999999999999	This field contains all nines to indicate it as a trailer record.	M
14	22	Trailer Count	9(09)	000000002	This field indicates the total number of detail records.	M
23	500	Fillers	AN(478)		Value = Spaces	O

Example of a decrypted settlement file with a sample record (containing header, detail record and trailer):

000000000000020230322202303222124557
cdabff2-e588-40db-82dc-9cfb9259c71cTRANSACTION EXTRACT
3874ab0b-cb93-474d-9576-e0ff9cf3de6648f29ad1-c9e8-cdfb-d253-2d1a08b4b6e448f29ad1-c9e8-cdfb-d253-2d1a08b4b6e4M2023032020230322D0010100000000000003408000AUD                       2V1U0YHungry Jacks             Mermaid WaterAU477388002000607 74773883079000920765851463079402693187           0000000000000000                                                                                                                                                                                                    
9999999999999000000001