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
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
Field | 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 | 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 being used in the transaction between Nium and your client pool account. 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 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 to identify 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 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
Field | 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 a Delegated 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 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 your
prefund
account. - A reversal advice is sent to you with details about the original transaction.
- 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
The settlement file naming convention is: [clientHashId]_MONTX_YYYYMMDDHHmmSS.TXT.pgp
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
From | To | Field name | Format length | Example value | Description | Mandatory / Optional |
---|---|---|---|---|---|---|
1 | 13 | Identifier | Alphanumeric (AN) length is 13 characters (13) AN(13) | 0000000000000 | This field contains all zeros to indicate it as a header record. | M |
14 | 21 | Batch Date | yyyyMMdd (08) | 20210425 | This field indicates the posting date of the file sent to the SFTP. The file contains settlement records of the date with the format: yyyyMMdd . | M |
22 | 35 | Creation Date | yyyyMMddHHmmss (14) | 20210426013548 | This field indicates the creation date of the file. It contains today's Nium cards processing date-time in UTC with the format: yyyyMMddHHmmss . | M |
36 | 71 | Client Hash ID | AN(36) | 123e4567-e89b-12d3-a456-426655440000 | This field indicates the client unique ID. | M |
72 | 91 | File Identification | AN(20) | TRANSACTION EXTRACT | This field indicates the identifier for the file. | M |
92 | 500 | Filler | AN(409) | Value = Spaces | O |
Transaction record structure
From | To | Field name | Format length | Example value | Description | Mandatory / Optional |
---|---|---|---|---|---|---|
1 | 36 | Card Hash ID | AN(36) | 3f860722-9f50-4689-9e3b-16c03560b7fc | The unique card hash ID. | M |
37 | 72 | Transaction ID | AN(36) | 28b0de5c-576e-4d34-b747-db37d811fcd1 | The transaction's unique transaction hash ID. | O |
73 | 108 | Partner Transaction Reference Number | AN(36) | 28b0de5c-576e-4d34-b747-db37d811fcd1 | The transaction reference unique hash ID. | O |
109 | 109 | Record Type | AN(1) | M | M | |
110 | 117 | Effective Date | 9(8) | 20202004 | The effective date when the settlement is released. | M |
118 | 125 | Batch Date | 9(8) | 20202004 | The batch of the settlement clearance. | M |
126 | 126 | Transaction Type | AN(1) | D | Type of transaction: • Debit= D • Credit= C | M |
127 | 131 | Transaction Code | 9(5) | 00101 | 5 digits to refer debit and credit transactions: • 00101 – RETAIL SALE • 00102 – SALE REVERSAL • 00103 – CASH ADVANCE • 00104 -CASH RVERSAL | M |
132 | 151 | Billing Amount | 9(20) | 00000000000000100000 | Billing amount in format (15,4): • Where 15 stands for whole • 4 stand for decimal value • 0 in 16th position stands for "." | M |
152 | 154 | Billing Currency Code | 9(3) | SGD | 3-digit ISO3 currency code. | M |
155 | 174 | Transaction Amount | 9(20) | 00000000000000100000 | Transaction amount in format (15,4): • Where 15 stands for whole • 4 stand for decimal value •0 in 16th position stands for "." | O (space when the transaction amount is the same as the billing amount) |
175 | 177 | Transaction Currency Code | 9(3) | SGD | 3-digit ISO3 currency code. | O (space when the transaction currency is the same as the billing currency) |
178 | 183 | Authorization Code | 9(6) | 557006 | 6- digit code for an approved transaction. | O |
184 | 223 | Description | AN(40) | RETAIL ONLINE | Description of transaction. | O |
224 | 239 | Card Acceptor ID | AN(16) | CARD ACCEPTOR | Alphanumeric card acceptor ID. | M |
240 | 262 | Interchange Reference | 9(23) | 78600000317792070999001 | Interchange reference on transaction provided by merchant. | M |
263 | 277 | Visa Transaction ID | 9(15) | 019164261950302 | Unique ID provided for the transaction by Visa. | M |
278 | 288 | Token Requestor ID | AN(11) | 40010030273 | ApplePay / GooglePay Token Requester ID | M |
289 | 307 | Token Number | AN(19) | 4513696691503434 | ApplePay / GooglePay Token Number | M |
308 | 500 | For Future Purpose | AN(193) | To add additional fields in future | O |
Trailer record structure
From | To | Field name | Format length | Example value | Description | M/O |
---|---|---|---|---|---|---|
1 | 13 | Identifier | AN(13) | 9999999999999 | This field contains all nines to indicate it as a trailer record. | M |
14 | 22 | Trailer Count | 9(09) | 000000002 | This field indicates the total number of detail records. | M |
23 | 500 | Fillers | AN(478) | Value = Spaces | O |
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
Updated 6 days ago