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}

POST /{merchant_notification_url}

Parameters

Request body

eventIdstringoptional
Id of the event
example: 554ccc00-28fb-4344-a3fa-4bb8d1999bd5
eventTimestringoptional
Event time in ISO 8601 datetime. All timestamps are assumed to be in UTC+01:00.
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
  Unique identifier of the order. The string can contain up to 27 characters. Only the following characters are allowed:
  
  English letters (A–Z, a–z)
  
  Digits (0–9)
  
  The following special symbols: # * + - . : ; = ? [ ] _ { | } (accented letters, non-ASCII characters, or any other symbols are not allowed).
  
  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 datetime. All timestamps are assumed to be in UTC+01:00.
  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 datetime. All timestamps are assumed to be in UTC+01:00.
    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 datetime. All timestamps are assumed to be in UTC+01:00.
    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 datetime. All timestamps are assumed to be in UTC+01:00.
    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 datetime. All timestamps are assumed to be in UTC+01:00.
    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 datetime. All timestamps are assumed to be in UTC+01:00.
    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 datetime. All timestamps are assumed to be in UTC+01:00.
    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 processedoptional
4XXNotification could not be processedoptional
5XXNotification could not be processedoptional