XPay Payment APIs
Scroll down for code samples, example requests and responses.
Select a language for code samples from the tabs or the mobile navigation menu.
Create Order for Hosted Payment
POST /orders/hpp
Hosted Payment Initialization. Server-to-Server API for starting the order lifecycle
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
Create Order for Hosted Payment
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/hpp"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/json"); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody); IRestResponse response = client.Execute(request);
Request body
orderobjectoptional
orderIdstringrequired
example: btid2384983Merchant order id, unique in the merchant domain
amountstringrequired
example: 3545Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
currencystringrequired
example: EURTransaction currency. ISO 4217 alphabetic code
customerIdstringoptional
example: mcid97295873Customer label for this transaction
descriptionstringoptional
example: TV LG 3423Transaction description
customFieldstringoptional
example: weekend promotionAdditional transaction description
customerInfoobjectoptional
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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.
transactionSummaryarrayoptional
languagestringoptional
example: engLanguage to be used on the transaction summary details, ISO 639-2.
summaryListarrayoptional
labelstringoptional
example: Number of peoplelabel of the field
valuestringoptional
example: 4value
installmentsarrayoptional
datestringoptional
example: 2022-09-01T00:00:00.000ZInstallment time.
amountstringoptional
example: 350Installment amount.
termsAndConditionsIdsarrayoptional
paymentSessionobjectoptional
actionTypestringoptional
example: PAYPAY
,VERIFY
,PREAUTH
amountstringrequired
example: 3545Amount of the first payment which may be less or equals to the order amount. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
recurrenceobjectoptional
actionstringoptional
example: NO_RECURRINGNO_RECURRING
,SUBSEQUENT_PAYMENT
,CONTRACT_CREATION
,CARD_SUBSTITUTION
contractIdstringoptionalexample: C2834987
contractTypestringoptional
example: MIT_UNSCHEDULEDMIT_UNSCHEDULED
,MIT_SCHEDULED
,CIT
contractExpiryDatestringoptional
example: 2023-03-16T00:00:00.000ZUsed with contractType MIT_SCHEDULED.
contractFrequencystringoptional
example: 120Used with contractType MIT_SCHEDULED. Number of days
captureTypestringoptional
example: EXPLICITOverwrites the default confirmation method of the terminal, for card payments only:
- IMPLICIT - automatic confirmation
- EXPLICIT - authorization only
Default value depends on the terminal configuration.
IMPLICIT
,EXPLICIT
exemptionsstringoptional
example: NO_PREFERENCENO_PREFERENCE
,CHALLENGE_REQUESTED
languagestringrequired
example: itaLanguage to be used on the hosted payment page. ISO 639-2
resultUrlstringoptional
example: https://{merchant_result_url}Merchant URL where the cardholder is redirected once the hosted payment completes
cancelUrlstringoptional
example: https://{merchant_cancel_url}Merchant URL where the cardholder is redirected once the hosted payment is abandoned
notificationUrlstringoptional
example: https://{merchant_notification_url}Merchant URL where the gateway pushes notifications
Request body
{ "order": { "orderId": "btid2384983", "amount": "3545", "currency": "EUR", "customerId": "mcid97295873", "description": "TV LG 3423", "customField": "weekend promotion", "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": { "value": 100, "currency": "EUR" }, "giftCardCount": 0, "preOrderDate": "2019-02-11T00:00:00.000Z", "preOrderPurchaseIndicator": "01", "reorderItemsIndicator": "01", "shipIndicator": "01" } }, "transactionSummary": [ { "language": "eng", "summaryList": [ { "label": "Number of people", "value": "4" } ] } ], "installments": [ { "date": "2022-09-01T00:00:00.000Z", "amount": "350" } ], "termsAndConditionsIds": [ "16dd6ac6-0791-4c72-b362-85f77f1728a2" ] }, "paymentSession": { "actionType": "PAY", "amount": "3545", "recurrence": { "action": "NO_RECURRING", "contractId": "C2834987", "contractType": "MIT_UNSCHEDULED", "contractExpiryDate": "2023-03-16T00:00:00.000Z", "contractFrequency": "120" }, "captureType": "EXPLICIT", "exemptions": "NO_PREFERENCE", "language": "ita", "resultUrl": "https://{merchant_result_url}", "cancelUrl": "https://{merchant_cancel_url}", "notificationUrl": "https://{merchant_notification_url}" } }
Responses
200Payment initialization successfuloptional
hostedPagestringoptional
example: https://{gateway_hosted_page}URL of the hosted payment page. Redirect the payment flow to this URL.
securityTokenstringoptional
example: 2f0ea5059b41414ca3744fe672327d85Token which may be used for validating the notifications related to this payment
400Invalid request dataoptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 200
- 400
- 500
{ "hostedPage": "https://{gateway_hosted_page}", "securityToken": "2f0ea5059b41414ca3744fe672327d85" }
Find Orders
GET /orders
Find orders in reversed chronological order
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
fromTimestringoptional
toTimestringoptional
maxRecordsnumberoptional
customFieldstringoptional
Find Orders
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders?fromTime=SOME_STRING_VALUE&toTime=SOME_STRING_VALUE&maxRecords=SOME_NUMBER_VALUE&customField=SOME_STRING_VALUE"); var request = new RestRequest(Method.GET); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); IRestResponse response = client.Execute(request);
Responses
200Request successfully processedoptional
ordersarrayoptional
orderobjectoptional
orderIdstringrequired
example: btid2384983Merchant order id, unique in the merchant domain
amountstringrequired
example: 3545Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
currencystringrequired
example: EURTransaction currency. ISO 4217 alphabetic code
customerIdstringoptional
example: mcid97295873Customer label for this transaction
descriptionstringoptional
example: TV LG 3423Transaction description
customFieldstringoptional
example: weekend promotionAdditional transaction description
customerInfoobjectoptional
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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.
transactionSummaryarrayoptional
languagestringoptional
example: engLanguage to be used on the transaction summary details, ISO 639-2.
summaryListarrayoptional
labelstringoptional
example: Number of peoplelabel of the field
valuestringoptional
example: 4value
installmentsarrayoptional
datestringoptional
example: 2022-09-01T00:00:00.000ZInstallment time.
amountstringoptional
example: 350Installment amount.
termsAndConditionsIdsarrayoptional
authorizedAmountstringoptionalexample: 3545
capturedAmountstringoptionalexample: 3545
lastOperationTypestringoptional
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
lastOperationTimestringoptional
example: 2022-11-25T15:38:28.135ZOperation time
401Unauthorizedoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 200
- 500
{ "orders": [ { "order": { "orderId": "btid2384983", "amount": "3545", "currency": "EUR", "customerId": "mcid97295873", "description": "TV LG 3423", "customField": "weekend promotion", "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": { "value": 100, "currency": "EUR" }, "giftCardCount": 0, "preOrderDate": "2019-02-11T00:00:00.000Z", "preOrderPurchaseIndicator": "01", "reorderItemsIndicator": "01", "shipIndicator": "01" } }, "transactionSummary": [ { "language": "eng", "summaryList": [ { "label": "Number of people", "value": "4" } ] } ], "installments": [ { "date": "2022-09-01T00:00:00.000Z", "amount": "350" } ], "termsAndConditionsIds": [ "16dd6ac6-0791-4c72-b362-85f77f1728a2" ] }, "authorizedAmount": "3545", "capturedAmount": "3545", "lastOperationType": "CAPTURE", "lastOperationTime": "2022-11-25T15:38:28.135Z" } ] }
Find Order by ID
GET /orders/{orderId}
Retrieve all the operations for the given order
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
orderIdstringrequired
Merchant order id
Find Order by ID
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/btid2384983"); var request = new RestRequest(Method.GET); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); IRestResponse response = client.Execute(request);
Responses
200Order foundoptional
orderStatusobjectoptional
orderobjectoptional
orderIdstringrequired
example: btid2384983Merchant order id, unique in the merchant domain
amountstringrequired
example: 3545Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
currencystringrequired
example: EURTransaction currency. ISO 4217 alphabetic code
customerIdstringoptional
example: mcid97295873Customer label for this transaction
descriptionstringoptional
example: TV LG 3423Transaction description
customFieldstringoptional
example: weekend promotionAdditional transaction description
customerInfoobjectoptional
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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.
transactionSummaryarrayoptional
languagestringoptional
example: engLanguage to be used on the transaction summary details, ISO 639-2.
summaryListarrayoptional
labelstringoptional
example: Number of peoplelabel of the field
valuestringoptional
example: 4value
installmentsarrayoptional
datestringoptional
example: 2022-09-01T00:00:00.000ZInstallment time.
amountstringoptional
example: 350Installment amount.
termsAndConditionsIdsarrayoptional
authorizedAmountstringoptionalexample: 3545
capturedAmountstringoptionalexample: 3545
lastOperationTypestringoptional
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
lastOperationTimestringoptional
example: 2022-11-25T15:38:28.135ZOperation time
operationsarrayoptional
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-11-25T15:38:28.135ZOperation time
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
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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
paymentLinksarrayoptional
linkIdstringoptional
example: 92864835Unique identifier for this link.
amountstringoptional
example: 3545Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
expirationDatestringoptional
example: 2022-09-01T00:00:00.000ZExpiration date.
linkstringoptional
example: https://{gateway_hosted_page}Link to be shared with the customer for doing the payment.
paidByOperationIdstringoptional
example: 3470744Operation Id identifying the successful payment related to this link.
401Unauthorizedoptional
404Order not foundoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 200
- 500
{ "orderStatus": { "order": { "orderId": "btid2384983", "amount": "3545", "currency": "EUR", "customerId": "mcid97295873", "description": "TV LG 3423", "customField": "weekend promotion", "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": { "value": 100, "currency": "EUR" }, "giftCardCount": 0, "preOrderDate": "2019-02-11T00:00:00.000Z", "preOrderPurchaseIndicator": "01", "reorderItemsIndicator": "01", "shipIndicator": "01" } }, "transactionSummary": [ { "language": "eng", "summaryList": [ { "label": "Number of people", "value": "4" } ] } ], "installments": [ { "date": "2022-09-01T00:00:00.000Z", "amount": "350" } ], "termsAndConditionsIds": [ "16dd6ac6-0791-4c72-b362-85f77f1728a2" ] }, "authorizedAmount": "3545", "capturedAmount": "3545", "lastOperationType": "CAPTURE", "lastOperationTime": "2022-11-25T15:38:28.135Z" }, "operations": [ { "orderId": "btid2384983", "operationId": "3470744", "channel": "ECOMMERCE", "operationType": "CAPTURE", "operationResult": "AUTHORIZED", "operationTime": "2022-11-25T15:38:28.135Z", "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": { "value": 100, "currency": "EUR" }, "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" } } } ], "paymentLinks": [ { "linkId": "92864835", "amount": "3545", "expirationDate": "2022-09-01T00:00:00.000Z", "link": "https://{gateway_hosted_page}", "paidByOperationId": "3470744" } ] }
Find Operation by ID
GET /operations/{operationId}
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
operationIdstringrequired
Operation id
Find Operation by ID
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/operations/21345"); var request = new RestRequest(Method.GET); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); IRestResponse response = client.Execute(request);
Responses
200Operation foundoptional
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-11-25T15:38:28.135ZOperation time
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
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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
401Unauthorizedoptional
404Operation not foundoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 200
- 500
{ "orderId": "btid2384983", "operationId": "3470744", "channel": "ECOMMERCE", "operationType": "CAPTURE", "operationResult": "AUTHORIZED", "operationTime": "2022-11-25T15:38:28.135Z", "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": { "value": 100, "currency": "EUR" }, "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" } } }
Find Operations
GET /operations
Find operations created in the given time interval
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
fromTimestringoptional
toTimestringoptional
maxRecordsnumberoptional
channelstringoptional
operationTypestringoptional
customFieldstringoptional
Find Operations
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/operations?fromTime=SOME_STRING_VALUE&toTime=SOME_STRING_VALUE&maxRecords=SOME_NUMBER_VALUE&channel=ECOMMERCE&operationType=CAPTURE&customField=SOME_STRING_VALUE"); var request = new RestRequest(Method.GET); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); IRestResponse response = client.Execute(request);
Responses
200Request successfully processedoptional
operationsarrayoptional
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-11-25T15:38:28.135ZOperation time
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
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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
401Unauthorizedoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 200
- 500
{ "operations": [ { "orderId": "btid2384983", "operationId": "3470744", "channel": "ECOMMERCE", "operationType": "CAPTURE", "operationResult": "AUTHORIZED", "operationTime": "2022-11-25T15:38:28.135Z", "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": { "value": 100, "currency": "EUR" }, "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" } } } ] }
Refund
POST /operations/{operationId}/refunds
Refund or Reversal based on the clearing state, partial or full
Parameters
X-API-KEYstringrequired
Idempotency-Keystring (uuid)required
Correlation-Idstring (uuid)required
operationIdstringrequired
Operation id
Refund
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/operations/21345/refunds"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/json"); request.AddHeader("Idempotency-Key", "SOME_STRING_VALUE"); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody); IRestResponse response = client.Execute(request);
Request body
Responses
200Post operation acceptedoptional
400Request rejectedoptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
404Transaction not foundoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 400
- 500
{ "errors": [ { "code": "GW0001", "description": "Invalid merchant URL" } ] }
Capture
POST /operations/{operationId}/captures
Payment confirmation
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
operationIdstringrequired
Operation id
Capture
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/operations/21345/captures"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/json"); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody); IRestResponse response = client.Execute(request);
Request body
Responses
200Post operation acceptedoptional
400Request rejectedoptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
404Transaction not foundoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 400
- 500
{ "errors": [ { "code": "GW0001", "description": "Invalid merchant URL" } ] }
Cancel a capture operation. Does not apply to any other operation types.
POST /operations/{operationId}/cancels
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
operationIdstringrequired
Operation id of a capture operation to be cancelled
Cancel a capture operation. Does not apply to any other operation types.
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/operations/3470744/cancels"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/json"); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody); IRestResponse response = client.Execute(request);
Request body
descriptionstringoptional
example: refund executed by mistakeFree text message available to describe the rationale of the cancel.
Request body
{ "description": "refund executed by mistake" }
Responses
200Request acceptedoptional
400Request rejectedoptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
404Order or operation not foundoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 400
- 500
{ "errors": [ { "code": "GW0001", "description": "Invalid merchant URL" } ] }
List of payment methods supported by this merchant together with associated attributes
GET /payment_methods
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
List of payment methods supported by this merchant together with associated attributes
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/payment_methods"); var request = new RestRequest(Method.GET); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); IRestResponse response = client.Execute(request);
Responses
200Request processed successfullyoptional
paymentMethodsarrayoptional
circuitstringoptional
example: VISAone of VISA, MASTERCARD, PAYPAL, BANCONTACT, MYBANK etc.
methodTypestringoptional
example: CARD- CARD - Card circuit * APM - Alternative payment method
CARD
,APM
imageLinkstringoptional
example: https://ngwecomm.nexi.it/monetaweb/static/images/mybank.svgLocation for the logo of this payment method in SVG format
recurringSupportedbooleanoptionalexample: true
oneClickSupportedbooleanoptionalexample: true
401Unauthorizedoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 200
- 500
{ "paymentMethods": [ { "circuit": "VISA", "methodType": "CARD", "imageLink": "https://ngwecomm.nexi.it/monetaweb/static/images/mybank.svg", "recurringSupported": true, "oneClickSupported": true } ] }
MOTO Payment
POST /orders/moto
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
MOTO Payment
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/moto"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/json"); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody); IRestResponse response = client.Execute(request);
Request body
orderobjectoptional
orderIdstringrequired
example: btid2384983Merchant order id, unique in the merchant domain
amountstringrequired
example: 3545Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
currencystringrequired
example: EURTransaction currency. ISO 4217 alphabetic code
customerIdstringoptional
example: mcid97295873Customer label for this transaction
descriptionstringoptional
example: TV LG 3423Transaction description
customFieldstringoptional
example: weekend promotionAdditional transaction description
customerInfoobjectoptional
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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.
transactionSummaryarrayoptional
languagestringoptional
example: engLanguage to be used on the transaction summary details, ISO 639-2.
summaryListarrayoptional
labelstringoptional
example: Number of peoplelabel of the field
valuestringoptional
example: 4value
installmentsarrayoptional
datestringoptional
example: 2022-09-01T00:00:00.000ZInstallment time.
amountstringoptional
example: 350Installment amount.
termsAndConditionsIdsarrayoptional
cardobjectoptional
panstringrequired
example: 23498093745973Card PAN
expiryDatestringrequired
example: 0824Card expiry date in format mmyy
cvvstringoptional
example: 234Card Validation Value, when available
captureTypestringoptional
example: EXPLICITOverwrites the default confirmation method of the terminal, for card payments only:
- IMPLICIT - automatic confirmation
- EXPLICIT - authorization only
Default value depends on the terminal configuration.
IMPLICIT
,EXPLICIT
Request body
{ "order": { "orderId": "btid2384983", "amount": "3545", "currency": "EUR", "customerId": "mcid97295873", "description": "TV LG 3423", "customField": "weekend promotion", "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": { "value": 100, "currency": "EUR" }, "giftCardCount": 0, "preOrderDate": "2019-02-11T00:00:00.000Z", "preOrderPurchaseIndicator": "01", "reorderItemsIndicator": "01", "shipIndicator": "01" } }, "transactionSummary": [ { "language": "eng", "summaryList": [ { "label": "Number of people", "value": "4" } ] } ], "installments": [ { "date": "2022-09-01T00:00:00.000Z", "amount": "350" } ], "termsAndConditionsIds": [ "16dd6ac6-0791-4c72-b362-85f77f1728a2" ] }, "card": { "pan": "23498093745973", "expiryDate": "0824", "cvv": "234" }, "captureType": "EXPLICIT" }
Responses
200Payment successfuloptional
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-11-25T15:38:28.135ZOperation time
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
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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
400Invalid request dataoptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 200
- 400
- 500
{ "operation": { "orderId": "btid2384983", "operationId": "3470744", "channel": "ECOMMERCE", "operationType": "CAPTURE", "operationResult": "AUTHORIZED", "operationTime": "2022-11-25T15:38:28.135Z", "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": { "value": 100, "currency": "EUR" }, "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" } } } }
Card Verification
POST /orders/card_verification
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
Card Verification
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/card_verification"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/json"); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody); IRestResponse response = client.Execute(request);
Request body
orderobjectoptional
orderIdstringrequired
example: btid2384983Merchant order id, unique in the merchant domain
amountstringrequired
example: 3545Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
currencystringrequired
example: EURTransaction currency. ISO 4217 alphabetic code
customerIdstringoptional
example: mcid97295873Customer label for this transaction
descriptionstringoptional
example: TV LG 3423Transaction description
customFieldstringoptional
example: weekend promotionAdditional transaction description
customerInfoobjectoptional
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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.
transactionSummaryarrayoptional
languagestringoptional
example: engLanguage to be used on the transaction summary details, ISO 639-2.
summaryListarrayoptional
labelstringoptional
example: Number of peoplelabel of the field
valuestringoptional
example: 4value
installmentsarrayoptional
datestringoptional
example: 2022-09-01T00:00:00.000ZInstallment time.
amountstringoptional
example: 350Installment amount.
termsAndConditionsIdsarrayoptional
cardobjectoptional
panstringrequired
example: 23498093745973Card PAN
expiryDatestringrequired
example: 0824Card expiry date in format mmyy
cvvstringoptional
example: 234Card Validation Value, when available
Request body
{ "order": { "orderId": "btid2384983", "amount": "3545", "currency": "EUR", "customerId": "mcid97295873", "description": "TV LG 3423", "customField": "weekend promotion", "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": { "value": 100, "currency": "EUR" }, "giftCardCount": 0, "preOrderDate": "2019-02-11T00:00:00.000Z", "preOrderPurchaseIndicator": "01", "reorderItemsIndicator": "01", "shipIndicator": "01" } }, "transactionSummary": [ { "language": "eng", "summaryList": [ { "label": "Number of people", "value": "4" } ] } ], "installments": [ { "date": "2022-09-01T00:00:00.000Z", "amount": "350" } ], "termsAndConditionsIds": [ "16dd6ac6-0791-4c72-b362-85f77f1728a2" ] }, "card": { "pan": "23498093745973", "expiryDate": "0824", "cvv": "234" } }
Responses
200Payment successfuloptional
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-11-25T15:38:28.135ZOperation time
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
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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
400Invalid request dataoptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 200
- 400
- 500
{ "operation": { "orderId": "btid2384983", "operationId": "3470744", "channel": "ECOMMERCE", "operationType": "CAPTURE", "operationResult": "AUTHORIZED", "operationTime": "2022-11-25T15:38:28.135Z", "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": { "value": 100, "currency": "EUR" }, "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" } } } }
Merchant Initiated Transaction
POST /orders/mit
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
Merchant Initiated Transaction
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/mit"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/json"); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody); IRestResponse response = client.Execute(request);
Request body
orderobjectoptional
orderIdstringrequired
example: btid2384983Merchant order id, unique in the merchant domain
amountstringrequired
example: 3545Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
currencystringrequired
example: EURTransaction currency. ISO 4217 alphabetic code
customerIdstringoptional
example: mcid97295873Customer label for this transaction
descriptionstringoptional
example: TV LG 3423Transaction description
customFieldstringoptional
example: weekend promotionAdditional transaction description
customerInfoobjectoptional
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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.
transactionSummaryarrayoptional
languagestringoptional
example: engLanguage to be used on the transaction summary details, ISO 639-2.
summaryListarrayoptional
labelstringoptional
example: Number of peoplelabel of the field
valuestringoptional
example: 4value
installmentsarrayoptional
datestringoptional
example: 2022-09-01T00:00:00.000ZInstallment time.
amountstringoptional
example: 350Installment amount.
termsAndConditionsIdsarrayoptional
contractIdstringrequiredexample: C2834987
captureTypestringoptional
example: EXPLICITOverwrites the default confirmation method of the terminal, for card payments only:
- IMPLICIT - automatic confirmation
- EXPLICIT - authorization only
Default value depends on the terminal configuration.
IMPLICIT
,EXPLICIT
Request body
{ "order": { "orderId": "btid2384983", "amount": "3545", "currency": "EUR", "customerId": "mcid97295873", "description": "TV LG 3423", "customField": "weekend promotion", "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": { "value": 100, "currency": "EUR" }, "giftCardCount": 0, "preOrderDate": "2019-02-11T00:00:00.000Z", "preOrderPurchaseIndicator": "01", "reorderItemsIndicator": "01", "shipIndicator": "01" } }, "transactionSummary": [ { "language": "eng", "summaryList": [ { "label": "Number of people", "value": "4" } ] } ], "installments": [ { "date": "2022-09-01T00:00:00.000Z", "amount": "350" } ], "termsAndConditionsIds": [ "16dd6ac6-0791-4c72-b362-85f77f1728a2" ] }, "contractId": "C2834987", "captureType": "EXPLICIT" }
Responses
200Payment successfuloptional
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-11-25T15:38:28.135ZOperation time
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
cardHolderNamestringrequiredexample: 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.
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.
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.
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.
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.
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.
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
400Invalid request dataoptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
500Internal Server Erroroptional
errorsarrayoptional
codestringoptionalexample: GW0001
descriptionstringoptionalexample: Invalid merchant URL
- 200
- 400
- 500
{ "operation": { "orderId": "btid2384983", "operationId": "3470744", "channel": "ECOMMERCE", "operationType": "CAPTURE", "operationResult": "AUTHORIZED", "operationTime": "2022-11-25T15:38:28.135Z", "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": { "value": 100, "currency": "EUR" }, "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" } } } }
Generates a link to be shared with the cardholder for triggering the payment for the specified order
POST /orders/paybylink
Parameters
X-API-KEYstringrequired
Correlation-Idstring (uuid)required
Generates a link to be shared with the cardholder for triggering the payment for the specified order
- C#
- PHP
- Node
- Shell
var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/paybylink"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/json"); request.AddHeader("Correlation-Id", "SOME_STRING_VALUE"); request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE"); request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody); IRestResponse response = client.Execute(request);
Request body
orderobjectoptional
orderIdstringrequired
example: btid2384983Merchant order id, unique in the merchant domain
amountstringrequired
example: 3545Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
currencystringrequired
example: EURTransaction currency. ISO 4217 alphabetic code
customerIdstringoptional
example: mcid97295873Customer label for this transaction
descriptionstringoptional
example: TV LG 3423Transaction description
customFieldstringoptional
example: weekend promotionAdditional transaction description
customerInfoobjectoptional
cardHolderNamestringrequiredexample: 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
Date that the cardholder opened the account with the 3DS Requestor.