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
example: 554ccc00-28fb-4344-a3fa-4bb8d1999bd5Id of the event
eventTimestringoptional
example: 2022-09-01T01:20:00.001ZEvent time in ISO 8601 format
securityTokenstringoptional
example: 2f0ea5059b41414ca3744fe672327d85Token received in the payment initialization phase. Used to detect the notification comes from the payment gateway.
operationobjectoptional
orderIdstringoptional
example: btid2384983Merchant order id, unique in the merchant domain
operationIdstringoptionalexample: 3470744
channelstringoptional
example: ECOMMERCEIt 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
example: CAPTUREIt 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
example: AUTHORIZEDTransaction 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
example: 2022-09-01T01:20:00.001ZOperation time in ISO 8601 format
paymentMethodstringoptional
example: CARD- CARD - Any card circuit
- APM - Alternative payment method
CARD
,APM
paymentCircuitstringoptional
example: VISAone 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
example: ***6152Payment instrument information
paymentEndToEndIdstringoptional
example: e723hedsdewIt is defined by the circuit to uniquely identify the transaction. Required for circuid reconciliation purposes.
cancelledOperationIdstringoptional
Operation id to be undone
operationAmountstringoptional
example: 3545Operation amount in the payment currency
operationCurrencystringoptional
example: EURPayment currency
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
example: ITAISO 3166-1 alpha-3
shippingAddressobjectoptional
namestringoptionalexample: Mario Rossi
streetstringoptionalexample: Piazza Maggiore, 1
additionalInfostringoptionalexample: Quinto Piano, Scala B
citystringoptionalexample: Bologna
postCodestringoptionalexample: 40124
provincestringoptionalexample: BO
countrystringoptional
example: ITAISO 3166-1 alpha-3
mobilePhoneCountryCodestringoptionalexample: 39
mobilePhonestringoptionalexample: 3280987654
homePhonestringoptional
example: 391231234567The home phone number provided by the Cardholder.
workPhonestringoptional
example: 391231234567The work phone number provided by the Cardholder.
cardHolderAcctInfoobjectoptional
chAccDatestringoptional
example: 2019-02-11T00:00:00.000ZDate that the cardholder opened the account with the 3DS Requestor. ISO 8601 format
chAccAgeIndicatorstringoptional
example: 01Length of time that the cardholder has had the account with the 3DS Requestor.
chAccChangeDatestringoptional
example: 2019-02-11T00:00:00.000ZDate 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
example: 01Length 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
example: 2019-02-11T00:00:00.000ZDate that cardholder's account with the 3DS Requestor had a password change or account reset. ISO 8601 format
chAccPwChangeIndicatorstringoptional
example: 01Indicates the length of time since the cardholder's account with the 3DS Requestor had a password change or account reset.
nbPurchaseAccountnumberoptional
example: 0Number of purchases with this cardholder account during the previous six months.
destinationAddressUsageDatestringoptional
example: 2019-02-11T00:00:00.000ZDate when the shipping address used for this transaction was first used with the 3DS Requestor. ISO 8601 format
destinationAddressUsageIndicatorstringoptional
example: 01Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.
destinationNameIndicatorstringoptional
example: 01Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
txnActivityDaynumberoptional
example: 0Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.
txnActivityYearnumberoptional
example: 0Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.
provisionAttemptsDaynumberoptional
example: 0Number of Add Card attempts in the last 24 hours.
suspiciousAccActivitystringoptional
example: 01Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
paymentAccAgeDatestringoptional
example: 2019-02-11T00:00:00.000ZDate that the payment account was enrolled in the cardholder's account with the 3DS Requestor. ISO 8601 format
paymentAccIndicatorstringoptional
example: 0Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3DS Requestor.
merchantRiskIndicatorobjectoptional
deliveryEmailstringoptional
example: john.doe@email.comFor Electronic delivery, the email address to which the merchandise was delivered.
deliveryTimeframestringoptional
example: 01Indicates the merchandise delivery timeframe.
giftCardAmountobjectoptional
valuenumberoptional
example: 100For 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
example: EURFor prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.
giftCardCountnumberoptional
example: 0For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
preOrderDatestringoptional
example: 2019-02-11T00:00:00.000ZFor a pre-ordered purchase, the expected date that the merchandise will be available. ISO 8601 format
preOrderPurchaseIndicatorstringoptional
example: 01Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
reorderItemsIndicatorstringoptional
example: 01Indicates whether the cardholder is reordering previously purchased merchandise.
shipIndicatorstringoptional
example: 01Indicates shipping method chosen for the transaction.
warningsarrayoptional
codestringoptionalexample: TRA001
descriptionstringoptionalexample: 3DS warning
paymentLinkIdstringoptional
example: 234244353PayByLink 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 processed.optional
4XXNotification could not be processed.optional
5XXNotification could not be processed.optional