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

The transaction type can be:

DEBIT

REVERSAL

ORIGINAL_CREDIT

ORIGINAL_CREDIT_REVERSAL

REVERSAL_ADVICE

String
cardHashIdA unique card identifier generated during a new or add-on 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 of funds the merchant charges the cardholder. It needs to be represented in the actual transaction currency.

The amount is 0 in case of an account verification request.

Double
billingCurrencyCodeThis field contains the 3-letter ISO-4217 currency code for the billing amount. This is the client's base currency. The settlement with the network is also according to the billing currency.String
transactionCurrencyCodeThis field contains the 3-letter ISO-4217 currency code for the transaction amount. It's the currency in which the transaction is done.String
authCurrencyCodeThis field contains the 3-letter ISO-4217 authorization currency code being used in the transaction between Nium and your client pool account. It's possible that the transaction could be in the Indian Rupee (INR) currency, but the client holds only the Singapore Dollar (SGD) currency. In this case, INR becomes the transaction currency and SGD becomes the authorization currency.String
authAmountThis field contains the amount of funds actually received in the authorization. It needs to be represented in the authorization currency.Double
effectiveAuthAmountThis field contains the effective authorization amount which includes fees and markup on top of authorization amount.Double
billingConversionRateThe conversion rate of the transaction currency to the billing currency which is present for all card transactions. The format is DECIMAL(19,9).String
dateOfTransactionThe date and time of the transaction. The format is MMDDHHMMSS.String
localTimeThis field is applicable in the future.String
localDateThis field is applicable in the future.String
merchantCategoryCodeA code describing the merchant's type of business product or service.String
merchantTerminalIdA code that identifies a terminal at the merchant location.String
merchantTerminalIdCodeA code that identifies a merchant.String
merchantNameLocationThe address, country, or city where the merchant is located.String
posEntryModeThis is a 2-digit code that identifies the actual method used at the point of service to enter the cardholder account number and the card expiration date.String
posConditionCode

A code that describes the condition under which the transaction takes place at the point of service.

• 00 - Normal transaction

• 01 - Cardholder not present

• 03 - Merchant suspicious

• 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
originalDateOfTransactionThe data elements contained in the original message to identify a transaction for correction or reversal. It's used to build field 90 "Original Data Elements" of Visa.String
originalSystemTraceAuditNumberThe data elements contained in the original message to identify a transaction for correction or reversal. It's used to build field 90 "Original Data Elements" of Visa.String
originalTransactionIdThe data element contained in the original message to identify a transaction for correction or reversal. This is the transaction ID received with the original 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

The settlement file naming convention is: [clientHashId]_MONTX_YYYYMMDDHHmmSS.TXT.pgp

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