Extended Model
The Extended Model is an optional feature if you're on a wallet-based model in the Nium One platform. This feature requires you to make a decision as an extended step in the authorization decision chain.
This feature only applies to card-based transactions. By default, this feature 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 | The transaction type can be: • • • • • | String |
cardHashId | A 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 •30 - Balance Inquiry | 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 |
billingCurrencyCode | This 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 |
transactionCurrencyCode | This field contains the 3-letter ISO-4217 currency code for the transaction amount. It's the currency in which the transaction is done. | String |
authCurrencyCode | This field contains the 3-letter ISO-4217 authorization currency code for authorization. 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 |
authAmount | This field contains the amount of funds actually received in the authorization. It needs to be represented in the authorization currency. | Double |
effectiveAuthAmount | This field contains the effective authorization amount which includes fees and markup on top of the authorization amount. | Double |
billingConversionRate | The conversion rate of the transaction currency to the billing currency which is present for all card transactions. The format is DECIMAL(19,9). | String |
dateOfTransaction | The date and time of the transaction. The format is MMDDHHMMSS . | String |
localTime | This field is applicable in the future. | String |
localDate | This field is applicable in the future. | String |
merchantCategoryCode | A code describing the merchant's type of business product or service. | String |
merchantTerminalId | A code that identifies a terminal at the merchant location. | String |
merchantTerminalIdCode | A code that identifies a merchant. | String |
merchantNameLocation | The address, country, or city where the merchant is located. | String |
posEntryMode | This 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 |
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 | The 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 |
originalSystemTraceAuditNumber | The 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 |
originalTransactionId | The data element contained in the original message that identifies a transaction for correction or reversal. This is the transaction ID received with the original 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: ClientSettlement_Report{clientHashId}_YYYYMMDD.csv
Refer to the client settlement report for format details.
Updated about 5 hours ago