Extended Model

The Extended Model is a customizable authorization logic if you're on the Hosted Model in the Nium One platform. This model requires you to make a decision as an extended step in the authorization decision chain.

This model only applies to card-based transactions. By default, this model is turned off and not available. You need to work with your implementation manager to turn it on.

Extended Model flow

As the client, your key tasks are to apply any rules that you may have and provide a decision.

Nium recommends the Extended Model if you meet the following criteria:

  • You don't have a financial services license for e-money and you want to participate in the authorization decision.
  • You don't have the capability to process all types of transactions.

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

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

Allowed transaction type:

DEBIT

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 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
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 code String
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 cardholder wallet 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 cardholder wallet account during their 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 request example 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

FieldsDescriptionType
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 an Extended 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 Nium 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 the customer's wallet.

2. Settlement report

This report contains the end-of-day settlement data that Nium and the scheme send. As a client administrator, you can sign into Nium's back office to see or download the report based on the selected date range.

You can also set up a daily settlement data static report. You can download it and get it over Secure File Transfer Protocol. The file naming convention is: ClientSettlement_Report{clientHashId}_YYYYMMDD.csv

Refer to the client settlement report for format details.