Skip to content
XPay

    XPay Notification APIs

    This API describes the merchant server to server notifications.

    Scroll down for code samples, example requests and responses.
    Select a language for code samples from the tabs or the mobile navigation menu.

    POST /{merchant_notification_url}

    Parameters

      Request body

      • eventIdstringoptional

        Id of the event

      • eventTimestringoptional

        Event time in ISO 8601 format

      • securityTokenstringoptional

        Token received in the payment initialization phase. Used to detect the notification comes from the payment gateway.

      • operationobjectoptional
        • orderIdstringoptional

          Merchant order id, unique in the merchant domain

        • operationIdstringoptional
        • channelstringoptional

          It indicates the originating channel:

          • ECOMMERCE - carholder initiated operation through an online channel.
          • POS - carholder initiated operation through a physical POS.
          • BACKOFFICE - merchant initiated operation. It includes post operations and MIT.

          ECOMMERCE, POS, BACKOFFICE

        • operationTypestringoptional

          It indicates the purpose of the request:

          • AUTHORIZATION - any authorization with explicit capture
          • CAPTURE - a captured authorization or an implicit captured payment
          • VOID - reversal of an authorization
          • REFUND - refund of a captured amount
          • CANCEL - the rollback of an capture, refund.

          AUTHORIZATION, CAPTURE, VOID, REFUND, CANCEL

        • operationResultstringoptional

          Transaction output:

          • AUTHORIZED - Payment authorized
          • EXECUTED - Payment confirmed, verification successfully executed
          • DECLINED - Declined by the Issuer during the authorization phase
          • DENIED_BY_RISK - Negative outcome of the transaction risk analysis
          • THREEDS_VALIDATED - 3DS authentication OK or 3DS skipped (non-secure payment)
          • THREEDS_FAILED - cancellation or authentication failure during 3DS
          • PENDING - Payment ongoing. Follow up notifications are expected
          • CANCELED - Canceled by the cardholder
          • VOIDED - Online reversal of the full authorized amount
          • REFUNDED - Full or partial amount refunded
          • FAILED - Payment failed due to technical reasons

          AUTHORIZED, EXECUTED, DECLINED, DENIED_BY_RISK, THREEDS_VALIDATED, THREEDS_FAILED, PENDING, CANCELED, VOIDED, REFUNDED, FAILED

        • operationTimestringoptional

          Operation time in ISO 8601 format

        • paymentMethodstringoptional
          • CARD - Any card circuit
          • APM - Alternative payment method

          CARD, APM

        • paymentCircuitstringoptional

          one of the payment circuit values returned by the GET payment_methods web service VISA, MC, AMEX, DINERS, GOOGLE_PAY, APPLE_PAY, PAYPAL, BANCONTACT, BANCOMAT_PAY, MYBANK, PIS, AMAZON_PAY, ALIPAY etc.

        • paymentInstrumentInfostringoptional

          Payment instrument information

        • paymentEndToEndIdstringoptional

          It is defined by the circuit to uniquely identify the transaction. Required for circuid reconciliation purposes.

        • cancelledOperationIdstringoptional

          Operation id to be undone

        • operationAmountstringoptional

          Operation amount in the payment currency

        • operationCurrencystringoptional

          Payment currency

        • customerInfoobjectoptional
          • cardHolderNamestringoptional
          • cardHolderEmailstringoptional
          • billingAddressobjectoptional
            • namestringoptional
            • streetstringoptional
            • additionalInfostringoptional
            • citystringoptional
            • postCodestringoptional
            • provincestringoptional
            • countrystringoptional

              ISO 3166-1 alpha-3

          • shippingAddressobjectoptional
            • namestringoptional
            • streetstringoptional
            • additionalInfostringoptional
            • citystringoptional
            • postCodestringoptional
            • provincestringoptional
            • countrystringoptional

              ISO 3166-1 alpha-3

          • mobilePhoneCountryCodestringoptional
          • mobilePhonestringoptional
          • homePhonestringoptional

            The home phone number provided by the Cardholder.

          • workPhonestringoptional

            The work phone number provided by the Cardholder.

          • cardHolderAcctInfoobjectoptional
            • chAccDatestringoptional

              Date that the cardholder opened the account with the 3DS Requestor. ISO 8601 format

            • chAccAgeIndicatorstringoptional

              Length of time that the cardholder has had the account with the 3DS Requestor.

            • chAccChangeDatestringoptional

              Date that the cardholder's account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. ISO 8601 format

            • chAccChangeIndicatorstringoptional

              Length of time since the cardholder's account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.

            • chAccPwChangeDatestringoptional

              Date that cardholder's account with the 3DS Requestor had a password change or account reset. ISO 8601 format

            • chAccPwChangeIndicatorstringoptional

              Indicates the length of time since the cardholder's account with the 3DS Requestor had a password change or account reset.

            • nbPurchaseAccountnumberoptional

              Number of purchases with this cardholder account during the previous six months.

            • destinationAddressUsageDatestringoptional

              Date when the shipping address used for this transaction was first used with the 3DS Requestor. ISO 8601 format

            • destinationAddressUsageIndicatorstringoptional

              Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.

            • destinationNameIndicatorstringoptional

              Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.

            • txnActivityDaynumberoptional

              Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.

            • txnActivityYearnumberoptional

              Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.

            • provisionAttemptsDaynumberoptional

              Number of Add Card attempts in the last 24 hours.

            • suspiciousAccActivitystringoptional

              Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

            • paymentAccAgeDatestringoptional

              Date that the payment account was enrolled in the cardholder's account with the 3DS Requestor. ISO 8601 format

            • paymentAccIndicatorstringoptional

              Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3DS Requestor.

          • merchantRiskIndicatorobjectoptional
            • deliveryEmailstringoptional

              For Electronic delivery, the email address to which the merchandise was delivered.

            • deliveryTimeframestringoptional

              Indicates the merchandise delivery timeframe.

            • giftCardAmountobjectoptional
              • valuenumberoptional

                For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).

              • currencystringoptional

                For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.

            • giftCardCountnumberoptional

              For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.

            • preOrderDatestringoptional

              For a pre-ordered purchase, the expected date that the merchandise will be available. ISO 8601 format

            • preOrderPurchaseIndicatorstringoptional

              Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

            • reorderItemsIndicatorstringoptional

              Indicates whether the cardholder is reordering previously purchased merchandise.

            • shipIndicatorstringoptional

              Indicates shipping method chosen for the transaction.

        • warningsarrayoptional
          • codestringoptional
          • descriptionstringoptional
        • paymentLinkIdstringoptional

          PayByLink id used for correlating this operation with the original link.

        • additionalDataobjectoptional

          Map of additional fields specific to the chosen payment method

      Request body

      {
    "eventId": "554ccc00-28fb-4344-a3fa-4bb8d1999bd5",
    "eventTime": "2022-09-01T01:20:00.001Z",
    "securityToken": "2f0ea5059b41414ca3744fe672327d85",
    "operation": {
        "orderId": "btid2384983",
        "operationId": "3470744",
        "channel": "ECOMMERCE",
        "operationType": "CAPTURE",
        "operationResult": "AUTHORIZED",
        "operationTime": "2022-09-01T01:20:00.001Z",
        "paymentMethod": "CARD",
        "paymentCircuit": "VISA",
        "paymentInstrumentInfo": "***6152",
        "paymentEndToEndId": "e723hedsdew",
        "cancelledOperationId": "",
        "operationAmount": "3545",
        "operationCurrency": "EUR",
        "customerInfo": {
            "cardHolderName": "Mauro Morandi",
            "cardHolderEmail": "mauro.morandi@nexi.it",
            "billingAddress": {
                "name": "Mario Rossi",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "city": "Bologna",
                "postCode": "40124",
                "province": "BO",
                "country": "ITA"
            },
            "shippingAddress": {
                "name": "Mario Rossi",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "city": "Bologna",
                "postCode": "40124",
                "province": "BO",
                "country": "ITA"
            },
            "mobilePhoneCountryCode": "39",
            "mobilePhone": "3280987654",
            "homePhone": 391231234567,
            "workPhone": 391231234567,
            "cardHolderAcctInfo": {
                "chAccDate": "2019-02-11T00:00:00.000Z",
                "chAccAgeIndicator": "01",
                "chAccChangeDate": "2019-02-11T00:00:00.000Z",
                "chAccChangeIndicator": "01",
                "chAccPwChangeDate": "2019-02-11T00:00:00.000Z",
                "chAccPwChangeIndicator": "01",
                "nbPurchaseAccount": 0,
                "destinationAddressUsageDate": "2019-02-11T00:00:00.000Z",
                "destinationAddressUsageIndicator": "01",
                "destinationNameIndicator": "01",
                "txnActivityDay": 0,
                "txnActivityYear": 0,
                "provisionAttemptsDay": 0,
                "suspiciousAccActivity": "01",
                "paymentAccAgeDate": "2019-02-11T00:00:00.000Z",
                "paymentAccIndicator": "0"
            },
            "merchantRiskIndicator": {
                "deliveryEmail": "john.doe@email.com",
                "deliveryTimeframe": "01",
                "giftCardAmount": null,
                "giftCardCount": 0,
                "preOrderDate": "2019-02-11T00:00:00.000Z",
                "preOrderPurchaseIndicator": "01",
                "reorderItemsIndicator": "01",
                "shipIndicator": "01"
            }
        },
        "warnings": [
            {
                "code": "TRA001",
                "description": "3DS warning"
            }
        ],
        "paymentLinkId": "234244353",
        "additionalData": {
            "authorizationCode": "647189",
            "cardCountry": "ITA",
            "threeDS": "FULL_SECURE",
            "schemaTID": "MCS01198U",
            "multiCurrencyConversion": {
                "amount": "2662",
                "currency": "JPY",
                "exchangeRate": "0.007510523"
            }
        }
    }
}

      Responses

      • 200Notification successfully processedoptional
      • 4XXNotification could not be processedoptional
      • 5XXNotification could not be processedoptional