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 processedoptional
4XXNotification could not be processedoptional
5XXNotification could not be processedoptional