Delegated Model

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

HeadersParameters
Content-Typeapplication/octet-stream
x-request-idUniversally Unique Identifier (UUID)
x-client-nameString
[client-customized-headers]String (static value only)

Request body

FieldDescriptionType
transactionIdThe transaction ID is a Nium-generated 36-character UUID, which is unique per transaction.UUID
transactionType

Allowed transaction types:

DEBIT

REVERSAL

ORIGINAL_CREDIT

ORIGINAL_CREDIT_REVERSAL

REVERSAL_ADVICE

String
cardHashIdA 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 billing amount is a transactionAmount that is converted to the currency used by the card network and NIUM for end-of-day settlements, and it is denoted in billingCurrencyCode. The conversion rate is based on billingConversionRate.

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
billingCurrencyCodeThe 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 codeString
transactionCurrencyCodeThe 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
authCurrencyCodeThe auth currency code is the currency being used in the transaction between NIUM and your client pool account. The format of this field should be a 3-letter code representing the currency - 3-letter ISO-4217 currency code.String
authAmountThe auth amount displays the amount charged by NIUM to the client pool account during cardholder purchase, and it is denoted in authCurrencyCode.Double
effectiveAuthAmountThe effective auth amount refers to the combined total of the "authAmount" and the charges documented under transactionFees. And it is denoted in authCurrencyCode.Double
billingConversionRateThe rate used by the card network to convert the transaction amount to the cardholder billing amount.String
dateOfTransactionThe transaction date is shown in the format of MMDDHHMMSS using UTC time.String
localTimeReserved for futureString
localDateReserved for futureString
merchantCategoryCodeThe code that defines the type of business, product, or service offered by a merchant is called the Merchant Category Code (MCC). [MCC List]String
merchantTerminalIdA code that identifies a terminal at the card acceptor location (TID).String
merchantTerminalIdCodeA merchant ID number, also known as a merchant number or MID, is a 15-digit numerical identifier that uniquely identifies a merchant.String
merchantNameLocationA name and location of the card acceptor (merchant), including the
city name and country code

position 1-25: card acceptor name

position 26-38: city name

position 39-40: country code
String
posEntryModeThis 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)

04: Reserved for future Use

05: Chip card read

06: Reserved for future Use

07: Proximity payment originating using VSDC chip data rules

10: Credential stored on file

90: Entire content of magnetic stripe was transmitted in authorization request (CVV)

91: Proximity payment originating using magnetic strip data rules

95: Initiated by chip card: CVV data may be unreliable

Position 3:

0: Unknown

1: terminal can accept and forward online PINs

2: terminal cannot accept and forward online PINs

8: Terminal PIN pad down

9: Reserved for future Use

Position 4:

0: Unused
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

• 3 - Bar code read capability

• 4 - OCR read capability

• 5 - Integrated circuit card read capability

• 9 -Terminal does not read card data

UUID
retrievalReferenceNumberA 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
systemTraceAuditNumberA 6-digit number that the message initiator assigns that uniquely identifies a transaction.String
acquiringInstitutionCountryCodeThis field accepts the 3-digit ISO country code for the acquiring institution.String
acquiringInstitutionCodeA code that identifies the financial institution acting as the acquirer of the transaction.String
paymentServiceFieldsThis is a private use field. It contains the first data merchant number.String
originalDateOfTransactionOriginal transaction date of the purchase, this is present for correction or reversal transaction.String
originalSystemTraceAuditNumberOriginal System trace Audit Number of the purchase, this is present for correction or reversal transaction.String
originalTransactionIdOriginal transaction Id of the purchase, this is present for correction or reversal transaction.UUID
transactionFeesThis 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.nameThe name of the fees or markup.String
transactionFees.valueThe amount of the fees or markup.Double
transactionFees.currencyCodeThis field contains the 2-letter ISO-2 country code for identifying the country prefix to a mobile number.String
billingReplacementAmountDeprecated. This field is no longer in use and should be ignored.Double
transactionReplacementAmountDeprecated. 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

FieldDescriptionType
responseCodeChoose an appropriate 2-digit response code, from the response code list below, under which the client can process the transaction.String
partnerReferenceNumberThis 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 codeResponse reasonNotes
00SuccessThis response code indicates that the authorization is approved.
03Invalid MerchantUse 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.
12Invalid TransactionUse this decline reason code if you, as the client, know that this transaction is invalid.
46Account ClosedUse this decline reason code if you, as the client, know that this account is no longer valid or is closed.
51Insufficient FundsUse this decline reason code if you, as the client, know that the cardholder has insufficient funds in their account, wallet, or ledger.
57Transaction not PermittedUse 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.
61Exceeds Amount-based LimitsUse 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.
65Exceeds Frequency-based LimitsUse 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

AbbreviationDescription
ANAlpha-Numeric
AAlpha only
NNumeric only
DTDate

Header Record

Field NameField TypeField LengthSample ValueDescription
Record TypeAN1HRecord Type Indicator, H indicates Header record.
Batch DateN820210425This 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 DateN1420210426013548This 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 IdAN36123e4567-e89b-12d3-a456-426655440000This field indicates the client’s unique ID.
File IdentificationAN21DAILY SETTLEMENT FILEFixed value indicating that this is a daily settlement file

Detailed Record

Field NameField TypeField LengthSample ValueDescription
Record TypeAN1DRecord Type Indicator, D indicates Detail record.
CardHashIdAN363f860722-9f50-4689-9e3b-16c03560b7fcThe unique card hash ID.
Masked Card NumberAN164111XXXXXXXX1111Masked PAN
Transaction IdAN3628b0de5c-576e-4d34-b747-db37d811fcd1The transaction's unique transaction hash ID.
Partner Transaction Reference NumberAN3628b0de5c-576e-4d34-b747-db37d811fcd1The transaction reference number provided by the partner.
Effective DateN820202004The effective date when the settlement is released.
Batch DateN820202004The batch of the settlement clearance.
Transaction SignA1D or CD = Debit or C = Credit
Transaction CurrencyA3SGD or AUD3-character ISO3 currency code.
Transaction AmountN15,1,4AAAAAAAAAAAAAAATDDDDTransaction amount in format (15,1,4):

A indicates the amount.

T indicates the dot separating the de.cimals

D indicates the decimals

500.45 USD will be displayed as 000000000000500.4500

100000 JPY will be displayed as 000000000100000.0000

Note: The client will be responsible for ensuring proper posting based on the currency’s decimal value
Billing CurrencyA3SGD or AUD3-character ISO3 currency code.
Billing AmountN15,1,4AAAAAAAAAAAAAAATDDDDTransaction amount in format (15,1,4):

A indicates the amount.

T indicates the dot separating the decimals.

D indicates the decimals

500.45 USD will be displayed as 000000000000500.4500

100000 JPY will be displayed as 000000000100000.0000

Note: The client will be responsible for ensuring proper posting based on the currency’s decimal value.
Settlement CurrencyA3SGD or AUD3-character ISO3 currency code.
Settlement AmountN15,1,4AAAAAAAAAAAAAAATDDDDTransaction amount in format (15,1,4):

A indicates the amount.

T indicates the dot separating the decimals.

D indicates the decimals

500.45 USD will be displayed as 000000000000500.4500

100000 JPY will be displayed as 000000000100000.0000

Note: The client will be responsible for ensuring proper posting based on the currency’s decimal valu
Authorization CodeAN6557B066-character approval code for a transaction.
System Trace Audit Number (STAN)N12This field contains a number assigned by the message initiator (merchant or acquirer) that uniquely identifies a cardholder transaction.
Retrieval Reference Number (RRN)N12The acquirer usually defines it, but a merchant or an electronic terminal may define it.
Scheme Transaction IdentifierN16This contains a scheme-generated Transaction Identifier (TID) unique for each original authorization and financial request.
DescriptionAN40RETAIL ONLINEDescription of transaction.
Merchant IdAN12Unique Id of the Merchant where the card was used.
Merchant Terminal IdAN8Unique Id for the Terminal where the card was used.
Merchant NameAN25Merchant Name / Card Acceptor Name or Automated Teller Machine (ATM) location
Merchant CityAN13City of the Merchant / Card Acceptor or the Automated Teller Machine (ATM)
Merchant CountryAN2Country of the Merchant / Card Acceptor or the Automated Teller Machine (ATM)
Merchant Category CodeN46011Alpha-numeric code identifying the merchant operating the POS/ATM.
Acquirer IdN12This code identifies the financial institution acting as the acquirer of this customer transaction.
Multiple Settlement IndicatorA1M or FM - Indicating Multiple

F - Indicating Final
Interchange ReferenceN2578600000317792070999001Interchange reference on transaction provided by merchant
Interchange Fee SignA1+ or -+ for Positive

- for Negative
Interchange FeeN9
Original Interchange Fee Signa1+ or -+ for Positive

- for Negative
Original Interchange FeeN15
Token Requestor IDAN1140010030273ApplePay / GooglePay Token Requester ID

Trailer Record

Field NameField TypeField LengthSample ValueDescription
Record TypeAN1TRecord Type Indicator, T indicates Trailer record.
Record CountN9000000002This 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

FromToField nameFormat lengthExample valueDescriptionMandatory / Optional
113IdentifierAlphanumeric (AN) length is 13 characters (13) AN(13)0000000000000This field contains all zeros to indicate it as a header record.M
1421Batch DateyyyyMMdd(08)20210425This 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
2235Creation DateyyyyMMddHHmmss(14)20210426013548This field indicates the creation date of the file. It contains today's Nium cards processing date-time in UTC with the format: yyyyMMddHHmmss.M
3671Client Hash IDAN(36)123e4567-e89b-12d3-a456-426655440000This field indicates the client unique ID.M
7291File IdentificationAN(20)TRANSACTION EXTRACTThis field indicates the identifier for the file.M
92500FillerAN(409)Value = SpacesO

Transaction record structure

FromToField nameFormat lengthExample valueDescriptionMandatory / Optional
136Card Hash IDAN(36)3f860722-9f50-4689-9e3b-16c03560b7fcThe unique card hash ID.M
3772Transaction IDAN(36)28b0de5c-576e-4d34-b747-db37d811fcd1The transaction's unique transaction hash ID.O
73108Partner Transaction Reference NumberAN(36)28b0de5c-576e-4d34-b747-db37d811fcd1The transaction reference unique hash ID.O
109109Record TypeAN(1)MM
110117Effective Date9(8)20202004The effective date when the settlement is released.M
118125Batch Date9(8)20202004The batch of the settlement clearance.M
126126Transaction TypeAN(1)DType of transaction:

• Debit= D

• Credit= C

M
127131Transaction Code9(5)00101

5 digits to refer debit and credit transactions:

• 00101 – RETAIL SALE

• 00102 – SALE REVERSAL

• 00103 – CASH ADVANCE

• 00104 -CASH RVERSAL

M
132151Billing Amount9(20)00000000000000100000

Billing amount in format (15,4):

• Where 15 stands for whole

• 4 stand for decimal value

• 0 in 16th position stands for "."

M
152154Billing Currency Code9(3)SGD3-digit ISO3 currency code.M
155174Transaction Amount9(20)00000000000000100000

Transaction amount in format (15,4):

• Where 15 stands for whole

• 4 stand for decimal value

•0 in 16th position stands for "."

O (space when the transaction amount is the same as the billing amount)
175177Transaction Currency Code9(3)SGD3-digit ISO3 currency code.O (space when the transaction currency is the same as the billing currency)
178183Authorization Code9(6)5570066- digit code for an approved transaction.O
184223DescriptionAN(40)RETAIL ONLINEDescription of transaction.O
224239Card Acceptor IDAN(16)CARD ACCEPTORAlphanumeric card acceptor ID.M
240262Interchange Reference9(23)78600000317792070999001Interchange reference on transaction provided by merchant.M
263277Visa Transaction ID9(15)019164261950302Unique ID provided for the transaction by Visa.M
278288Token Requestor IDAN(11)40010030273ApplePay / GooglePay Token Requester IDM
289307Token NumberAN(19)4513696691503434ApplePay / GooglePay Token NumberM
308500For Future PurposeAN(193) To add additional fields in futureO

Trailer record structure

FromToField nameFormat lengthExample valueDescriptionM/O
113IdentifierAN(13)9999999999999This field contains all nines to indicate it as a trailer record.M
1422Trailer Count9(09)000000002This field indicates the total number of detail records.M
23500FillersAN(478) Value = SpacesO

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