Skip to content

    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.

    Merchant Notification

    POST /{merchant_notification_url}

    Parameters

      Request body

      • eventIdstringoptional

        Id of the event

        example: 554ccc00-28fb-4344-a3fa-4bb8d1999bd5
      • eventTimestringoptional

        Event time in ISO 8601 format

        example: 2022-09-01T01:20:00.001Z
      • securityTokenstringoptional

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

        example: 2f0ea5059b41414ca3744fe672327d85
      • operationobjectoptional
        • orderIdstringoptional

          Merchant order id, unique in the merchant domain

          example: btid2384983
        • operationIdstringoptionalexample: 3470744
        • 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

          example: ECOMMERCE
        • 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

          example: CAPTURE
        • 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

          example: AUTHORIZED
        • operationTimestringoptional

          Operation time in ISO 8601 format

          example: 2022-09-01T01:20:00.001Z
        • paymentMethodstringoptional
          • CARD - Any card circuit
          • APM - Alternative payment method

          CARD, APM

          example: CARD
        • 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.

          example: VISA
        • paymentInstrumentInfostringoptional

          Payment instrument information

          example: ***6152
        • paymentEndToEndIdstringoptional

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

          example: e723hedsdew
        • cancelledOperationIdstringoptional

          Operation id to be undone

        • operationAmountstringoptional

          Operation amount in the payment currency

          example: 3545
        • operationCurrencystringoptional

          Payment currency

          example: EUR
        • customerInfoobjectoptional
          • cardHolderNamestringoptionalexample: Mauro Morandi
          • cardHolderEmailstringoptionalexample: mauro.morandi@nexi.it
          • billingAddressobjectoptional
            • namestringoptionalexample: Mario Rossi
            • streetstringoptionalexample: Piazza Maggiore, 1
            • additionalInfostringoptionalexample: Quinto Piano, Scala B
            • citystringoptionalexample: Bologna
            • postCodestringoptionalexample: 40124
            • provincestringoptionalexample: BO
            • countrystringoptional

              ISO 3166-1 alpha-3

              example: ITA
          • shippingAddressobjectoptional
            • namestringoptionalexample: Mario Rossi
            • streetstringoptionalexample: Piazza Maggiore, 1
            • additionalInfostringoptionalexample: Quinto Piano, Scala B
            • citystringoptionalexample: Bologna
            • postCodestringoptionalexample: 40124
            • provincestringoptionalexample: BO
            • countrystringoptional

              ISO 3166-1 alpha-3

              example: ITA
          • mobilePhoneCountryCodestringoptionalexample: 39
          • mobilePhonestringoptionalexample: 3280987654
          • homePhonestringoptional

            The home phone number provided by the Cardholder.

            example: 391231234567
          • workPhonestringoptional

            The work phone number provided by the Cardholder.

            example: 391231234567
          • cardHolderAcctInfoobjectoptional
            • chAccDatestringoptional

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

              example: 2019-02-11T00:00:00.000Z
            • chAccAgeIndicatorstringoptional

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

              example: 01
            • 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

              example: 2019-02-11T00:00:00.000Z
            • 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.

              example: 01
            • chAccPwChangeDatestringoptional

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

              example: 2019-02-11T00:00:00.000Z
            • chAccPwChangeIndicatorstringoptional

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

              example: 01
            • nbPurchaseAccountnumberoptional

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

              example: 0
            • destinationAddressUsageDatestringoptional

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

              example: 2019-02-11T00:00:00.000Z
            • destinationAddressUsageIndicatorstringoptional

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

              example: 01
            • destinationNameIndicatorstringoptional

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

              example: 01
            • txnActivityDaynumberoptional

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

              example: 0
            • txnActivityYearnumberoptional

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

              example: 0
            • provisionAttemptsDaynumberoptional

              Number of Add Card attempts in the last 24 hours.

              example: 0
            • suspiciousAccActivitystringoptional

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

              example: 01
            • paymentAccAgeDatestringoptional

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

              example: 2019-02-11T00:00:00.000Z
            • paymentAccIndicatorstringoptional

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

              example: 0
          • merchantRiskIndicatorobjectoptional
            • deliveryEmailstringoptional

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

              example: john.doe@email.com
            • deliveryTimeframestringoptional

              Indicates the merchandise delivery timeframe.

              example: 01
            • 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).

                example: 100
              • currencystringoptional

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

                example: EUR
            • giftCardCountnumberoptional

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

              example: 0
            • preOrderDatestringoptional

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

              example: 2019-02-11T00:00:00.000Z
            • preOrderPurchaseIndicatorstringoptional

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

              example: 01
            • reorderItemsIndicatorstringoptional

              Indicates whether the cardholder is reordering previously purchased merchandise.

              example: 01
            • shipIndicatorstringoptional

              Indicates shipping method chosen for the transaction.

              example: 01
        • warningsarrayoptional
          • codestringoptionalexample: TRA001
          • descriptionstringoptionalexample: 3DS warning
        • paymentLinkIdstringoptional

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

          example: 234244353
        • 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 processed.optional
      • 4XXNotification could not be processed.optional
      • 5XXNotification could not be processed.optional