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

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 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

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 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

This report contains the end-of-day settlement data as received between Nium and the scheme.

There are two versions of the file format available for the daily client settlement report. Section 2.2.1 contains the latest version and 2.2.2 is the previous version that is deprecated and will eventually become unsupported.

As a client administrator, you can sign in to the Nium portal and view or download the settlement report based on the selected date range. You also have the option to have the file delivered to you over Secure File Transfer Protocol (SFTP).

2.2.1 Settlement file naming convention: [ClientHashID]_SETTLEMENT_YYYYMMDDHHmmSS.TXT.pgp

The following characteristics apply to this version of the settlement file

• Download file name convention: [ClientHashID]_SETTLEMENT_YYYYMMDDHHmmSS.TXT.pgp
• The extracted file naming convention is [ClientHashId]_SETTLEMENT_YYYYMMDDHHmmSS.TXT
• Fields in the settlement file are separated by a pipe ['|'] delimited
• Each settlement file contains three sections:
  a. Header
  b. Detail Record
  c. Trailer
• Current PGP encryption will apply, with no change in the logic.
• The last 10 columns are added for future use.

Design Abbreviations

Header Record

Detailed Record

Trailer Record

2.2.2 Settlement file naming convention: [clientHashId]_MONTX_YYYYMMDDHHmmSS.TXT.pgp

⚠️

WARNING

This file is a deprecated version which will become unsupported in Jun 2024. Refer to section 2.2.1 Settlement file to get the latest version.

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

Transaction record structure

Trailer record structure

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