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
| 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 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
| Fields | 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:
- Nium sends an Extended Model request to your end for an $88 expenditure.
- After 2 seconds without receiving a response, the platform times out the request.
- The platform declines the transaction to the card network.
- A second later, your system finishes processing the authorization and attempts to respond with an authorization for $88.
- 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:
- Nium declines the transaction to the scheme or network.
- 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: Client_Settlement_Report_clientHashId_YYYYMMDD.csv
Refer to the client settlement report for format details.