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

Request body

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

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

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.