Real Time Auth Notify

This notification is triggered when an authorisation is processed on a card in real-time.

https://<customerHost:Port>/handlenotification

Header

Field	Description
Content-Type	application/json

Request example

curl --location --request POST 'https://<customerHost:Port>/handlenotification' \
-H 'Content-Type: application/json' \
-d '{
      "notificationType": "REAL_TIME_AUTH_NOTIFY",
      "notificationCreationTime": "2025-03-07T15:10:52.462Z",
      "notificationContent": {
        "notificationKey": "D8CCR7aK5HMEBKYG",
        "cardReference": "0UwInjcdQl8TE1OGJDQuOTg7h",
        "transactionReference": "0UwIEGFh7fUHpNyUJDbsQeVbImN",
        "realTimeAuthReference": "0UwLsfsdffIC_DrGd8rBSWgzaX",
        "transactionTimestamp": "2025-03-09T14:07:43.369Z",
        "originalTransactionAmount": "2618.00",
        "originalTransactionCurrency": "MYR",
        "billingAmount": "-590.30",
        "billingCurrency": "USD",
        "billingConversionRate": "0.22548",
        "forexEcbRate": "0.223715586",
        "messageTypeIndicator": "100",
        "transactionCode": "SALE_OR_PURCHASE",
        "cardAcceptorIdentifier": "123456ABC",
        "cardAcceptorLocation": "TURKISH AIRLINE||KUALA LUMPUR|123456789||MYS|",
        "mccCode": "3047",
        "approvalCode": "123456",
        "posCardHolderPresence": "CARD_HOLDER_PRESENT",
        "posCardHolderAuthenticationMethod": "NOT_AUTHENTICATED",
        "posCardPresence": "PRESENT",
        "terminalCode": "99999999",
        "authState": "PROCESSED",
        "failReason": ""
      }
    }'

Request Body

Field	Description	Type
notificationType	Specifies the type of notification being sent.	string required
notificationCreationTime	Specifies the creation date and time for the notification. The date format conforms to ISO 8601	string required
notificationContent	Specifies the notification content	object required

Properties of notificationContent

Field	Description	Type
notificationKey	Represents a unique identifier for Nium that confirms the API method call is genuine	string required
cardReference	Represents a unique identifier for the virtual card	string required
transactionReference	Represents a unique identifier for transaction	string
realTimeAuthReference	Represents a unique identifier for the real-time authorisation	string required
transactionTimestamp	Represents the date and time when the transaction was executed, in ISO 8601 format	string required
originalTransactionAmount	Represents the original amount of the transaction	string required
originalTransactionCurrency	Represents the original currency of the transaction, in ISO 4217 format (e.g., USD).	string required
billingAmount	Represents the amount of the transaction expressed in the currency of the card	string required
billingCurrency	Represents the virtual card currency, in ISO 4217 format (e.g., USD).	string required
billingConversionRate	Represents the conversion rate used to calculate the billingAmount from the originalTransactionAmount	string required
forexEcbRate	A reference rate defined by the European Central Bank and is intended for information purposes only	string
messageTypeIndicator	Identifies the ISO 8583 MTI code	string
transactionCode	Defines the transaction type. Possible values: SALE_OR_PURCHASE, PREAUTHORIZATION_TRANSACTION_PURCHASE, PREAUTHORIZATION_TRANSACTION_PURCHASE_COMPLETION, MAIL_OR_TELEPHONE_ORDER, CASH, SALE_WITH_CASHBACK, MERCHANDISE_RETURN	string required
cardAcceptorIdentifier	Contains the merchant ID	string required
cardAcceptorLocation	Contains the merchant name	string required
mccCode	Contains the merchant category code	string required
approvalCode	Contains the code with which the authorisation is labelled when approved	string required
posCardHolderPresence	Defines whether the cardholder was present during the transaction. Possible values: CARD_HOLDER_PRESENT, NOT_PRESENT_UNSPECIFIED, NOT_PRESENT_MAIL_ORDER, NOT_PRESENT_TELEPHONE_ORDER, NOT_PRESENT_STANDING_ORDER, NOT_PRESENT_ELECTRONIC_ORDER, PRESENT_STANDING_ORDER, RESERVED	string
posCardHolderAuthenticationMethod	Defines the authentication method used by the cardholder. Possible values: NOT_AUTHENTICATED, PIN, ELECTRONIC_SIGNATURE_ANALYSIS, BIOMETRICS, BIOGRAPHIC, MANUAL_SIGNATURE_VERIFICATION, MANUAL_ORDER, UNKNOWN, E_COMMERCE_TRANSACTION, INVALID_VALUE	string
posCardPresence	Defines whether the card was present during the transaction. Possible values: PRESENT, NOT_PRESENT	string
terminalCode	Contains a code that identifies the terminal	string
authState	The authentication state. Possible values: PROCESSED, DECLINED, FAILED	string required
failReason	Specifies the failure reason when authState is DECLINED	string