No results

POST/orders/3steps/validation

PROD
https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/3steps/validation
TEST
https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/3steps/validation

Validation of the 3DS authentication outcome. This operation is required during the 3-step Server-to-Server payment flow. For more information, please refer to the dedicated page Payment 3 Steps.

PARAM HEADER
NAME DESCRIPTION FORMAT
X-Api-Key Authentication API Key. String
Format: uuid
Example: 625b4884-38f8-11ed-a261-0242ac120002
Correlation-Id Unique identifier of the request. String
Format: uuid
Example: 4935e818-38e0-11ed-a261-0242ac120002
PARAM PATH
NAME DESCRIPTION FORMAT
No param path
PARAM QUERY
NAME DESCRIPTION FORMAT
No param query
PARAM BODY

NAME DESCRIPTION FORMAT
operationId Identifier of the payment pending. String
Example: 3470744
threeDSAuthResponse Encrypted message containing the 3DS authentication result. String
Example: ni2178hiekh29830...
Arrow RESPONSE 200
Validation done successful - No Header for this response
BODY
NAME DESCRIPTION FORMAT
operation Object containing operation detail. Object
orderId Merchant order id, unique in the merchant domain. String
Max. length: 18
Example: btid2384983
operationId Operation ID. String
Example: 3470744
channel It indicates the originating channel:
* ECOMMERCE - cardholder initiated operation through an online channel.
* POS - cardholder initiated operation through a physical POS.
* BACKOFFICE - merchant initiated operation. It includes post operations and MIT.
 String
Example: ECOMMERCE
channelDetail Identify the type of service from which the operation originated, it can take the following values:
- "HOSTED_PAYMENT_PAGE": Hosted Payment Page solution with redirect to checkout page, no-show operation, incremental, delay charge.
- "SERVER_TO_SERVER": server-to-server 3-step solution, XPay Build.
- "MERCHANT_INITIATED_TRANSACTION": recurring payment.
- "PAY_BY_LINK": payment operation via Pay-By-Link link.
- "MOTO": payment operation via MOTO service.
- "POST_PAYMENT_OPERATION": capture, refund, cancel operation.
- "PRE_PAYMENT_OPERATION": card verification operation.
String
operationType It indicates the purpose of the request:
- AUTHORIZATION - payment authorization.
- CAPTURE - capture of the authorized amount.
- VOID - reversal of an authorization.
- REFUND - refund of a captured amount.
- CANCEL - the rollback of an capture, refund.
- CARD_VERIFICATION - verify operation, without any charge, with the sole purpose of confirming the validity of the card data entered by the customer.
- NOSHOW - noshow operation (reserved for Disputeless service).
- INCREMENTAL - incremental operation (reserved for Disputeless service).
- DELAY_CHARGE - delay charge operation (reserved for the Disputeless service).
 String
Example: CAPTURE
operationResult Outcome of the operation:
* 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
 String
Example: AUTHORIZED
operationTime Operation time. String
Example: 2022-09-01T01:20:00.001Z
paymentMethod * CARD - Any card circuit
* APM - Alternative payment method
 String
Example: CARD
paymentCircuit one of the payment circuit values returned by the GET payment_methods web service VISA, MC, AMEX, DINERS, GOOGLE_PAY, APPLE_PAY, PAYPAL, BANCONTACT, BANCOMAT_PAY, MYBANK, PIS, AMAZON_PAY, ALIPAY etc. String
Example: VISA
paymentInstrumentInfo Payment instrument information. String
Example: ***6152
paymentEndToEndId It is defined by the circuit to uniquely identify the transaction. Required for circuid reconciliation purposes. String
Max. length: 35
Example: e723hedsdew
cancelledOperationId Operation ID to be undone. String
Example: 321312
operationAmount Operation amount in the payment currency. String
Example: 3545
operationCurrency Transaction currency. ISO 4217 alphabetic code. String
Example: EUR
customerInfo Object containing the customer detail. Sending the content of this object increases the security level of the transaction, thus increasing the probability that two-factor authentication will not be requested in the payment. Object
cardHolderName Name and surname of the cardholder. String
Max. length: 255
Example: Mauro Morandi
cardHolderEmail Email of the cardholder. String
Max. length: 255
Example: mauro.morandi@nexi.it
billingAddress Object containing the detail of the customer's address. Object
name Name and surname. String
Max. length: 50
Example: Mario Rossi
street Full address. String
Max. length: 50
Example: Piazza Maggiore, 1
additionalInfo Additional info of address, for example floor. String
Max. length: 50
Example: Quinto Piano, Scala B
city City. String
Min. length: 1
Max. length: 40
Example: Bologna
postCode Postal code. String
Max. length: 16
Example: 40124
province Code of province. String
Max. length: 3
Example: BO
country State in ISO 3166-1 alpha-3 code.
The parameter is required with the following alternative payment methods:
- Bancontact: enhance "country" with "BEL".
- Giropay: enhance "country" with "DEU".
- Multibank: enhance "country" with "PRT".
 String
Min. length: 3
Max. length: 3
Example: ITA
shippingAddress Object containing the detail of the customer's address. Object
name Name and surname. String
Max. length: 50
Example: Mario Rossi
street Full address. String
Min. length: 1
Max. length: 50
Example: Piazza Maggiore, 1
additionalInfo Additional info of address, for example floor. String
Max. length: 50
Example: Quinto Piano, Scala B
city City. String
Min. length: 1
Max. length: 40
Example: Bologna
postCode Postal code. String
Max. length: 16
Example: 40124
province Code of province. String
Max. length: 3
Example: BO
country State in ISO 3166-1 alpha-3 code. String
Min. length: 3
Max. length: 3
Example: ITA
mobilePhoneCountryCode Prefix of the mobile phone. String
Max. length: 4
Example: +39
mobilePhone Mobile phone. String
Max. length: 15
Example: 3280987654
homePhone Home phone number provided by the Cardholder. String
Max. length: 18
Example: +391231234567
workPhone Work phone number provided by the Cardholder. String
Max. length: 18
Example: 391231234567
cardHolderAcctInfo Object containing information about the buyer's account. Object
chAccDate Date of activation of the account on the merchant's website. String
Example: 2019-02-11
chAccAgeIndicator Account age indicator on the merchant site:
01 = No account
02 = Created during this transaction
03 = Created in the last 30 days
04 = Created between 30 and 60 days ago
05 = Created before 60 days ago
 String
Example: 01
chAccChangeDate Date of the last variation of the account on the merchant's website, including Billing or Shipping address, new payment account, or new user(s) added. String
Example: 2019-02-11
chAccChangeIndicator Elapsed time since the last change to the buyer's account information on the merchant site, including Billing or Shipping address, new payment account, or new user(s) added.
01 = Created during this transaction
02 = Created in the last 30 days
03 = Created between 30 and 60 days ago
04 = Created before 60 days ago
 String
Example: 01
chAccPwChangeDate Date of last account password change (including password reset). String
Example: 2019-02-11
chAccPwChangeIndicator Time elapsed since the buyer's account performed a password change or account recovery:
01 = No account
02 = Created during this transaction
03 = In the last 30 days
04 = Between 30 and 60 days ago
05 = Before 60 days ago
 String
Example: 01
nbPurchaseAccount Number of purchases of this account in the last 6 months. Number
Example: 0
destinationAddressUsageDate Date of last use of this delivery address. String
Example: 2019-02-11
destinationAddressUsageIndicator Indicates when the shipping address used for this transaction was used for the first time:
01 = Created during this transaction
02 = Created in the last 30 days
03 = Created between 30 and 60 days ago
04 = Created before 60 days ago
 String
Example: 01
destinationNameIndicator Indicates if the name associated with the account matches the name listed for shipping:
01 = Account name identical to the shipping address name.
02 = Different account name from the shipping address name
 String
Example: 01
txnActivityDay Number of transactions (successful and abandoned) for this account in the previous 24 hours. Number
Example: 0
txnActivityYear Number of transactions (successful and abandoned) for this account in the previous year. Number
Example: 0
provisionAttemptsDay Number of attempts to add a new card in the last 24 hours. Number
Example: 0
suspiciousAccActivity Indicates whether the merchant has detected suspicious activity (including previous fraud) on the buyer's account:
01 = No suspicious activity verified.
02 = Suspicious activity detected
String
Example: 01
paymentAccAgeDate Payment account activation date. String
Example: 2019-02-11
paymentAccIndicator Indicates when the buyer has entered the Payment account on the merchant's site:
01 = No account
02 = created during this transaction
03 = Created in the last 30 days
04 = Created between 30 and 60 days ago
05 = Created before 60 days ago
 String
Example: 0
merchantRiskIndicator Object containing information relating to the purchase made. Object
deliveryEmail In case of purchase of virtual/digital products: email address to which the product is sent. String
Example: john.doe@email.com
deliveryTimeframe Indicator on the delivery period of the goods:
01 = Immediate Delivery (virtual/digital products).
02 = Same day delivery.
03 = Night delivery.
04 = Delivery in two or more days
 String
Example: 01
giftCardAmount Object containing information relating to the amount of gift cards or vouchers. Object
value Value of the gift or prepaid card used for the transaction. The amount must be expressed in cents. Number
Example: 100
currency Transaction currency. ISO 4217 alphabetic code. String
Example: EUR
giftCardCount Total number of individual prepaid or gift cards/codes purchased. Number
Example: 2
preOrderDate For a pre-ordered purchase, the expected date that the merchandise will be available. String
Example: 2019-02-11
preOrderPurchaseIndicator Indicates whether buyer is placing an order for merchandise with a future availability:
01 = Goods available.
02 = Future availability.
 String
Example: 01
reorderItemsIndicator Indicates whether the cardholder is reordering previously purchased merchandise:
01 = First order.
02 = Goods already purchased previously.
 String
Example: 01
shipIndicator Indicator on the type of delivery:
01 = Shipping to the billing address.
02 = Shipping to another address verified by the merchant.
03 = Delivery to a different address than the billing.
04 = Shipment or collection to the store (the address of the store must be indicated in the "destinationAddress" object).
05 = Virtual/digital goods, including online services, electronic gift certificates, recovery codes.
06 = Travel and event tickets (not sent).
07 = Other: for example games, digital services not sent, electronic media subscriptions
 String
Example: 01
warnings Array containing the list of warnings. Array
code Warning code. String
Example: TRA001
description Warning description. String
Example: 3DS warning
paymentLinkId PayByLink ID used for correlating this operation with the original link. String
Example: 234244353
additionalData Map of additional fields specific to the selected payment method.

It is recommended not to introduce constraints on the 'additionalData' object, as maintenance and enhancement activities may result in changes to its parameters.
 Object
Example: {"authorizationCode":"647189","cardCountry":"ITA","threeDS":"FULL_SECURE","schemaTID":"MCS01198U","multiCurrencyConversion":{"amount":"2662","currency":"JPY","exchangeRate":"0.007510523"}}
threeDSAuthResult Object
authenticationValue Completed for the 3-steps flow, obtained from the validation phase. String
Example: AAIBBjhkYQAAAAAKl4FHdAAAAAA=
cavvAlgorithm String
eci Completed for the 3-steps flow, obtained from the validation phase. String
Example: 05
merchantAcquirerBin String
Example: 494330
xid Completed for the 3-steps flow, obtained from the validation phase. String
Example: RExDQXMtS05EJTt6VlBNRnxdOkY=
status String
Example: VALIDATED
vendorcode String
version String
Example: 2.1.0
Arrow RESPONSE 400
Invalid request data - No Header for this response
BODY
NAME DESCRIPTION FORMAT
errors Array containing the errors list. The possible values are shown in the table Error codes. Array
code Error code. String
Example: GW0001
description Error description. String
Example: Invalid merchant URL
Arrow RESPONSE 401
Unauthorized - No Header and Body for this response
Arrow RESPONSE 500
Internal Server Error - No Header for this response
BODY
NAME DESCRIPTION FORMAT
errors Array containing the errors list. The possible values are shown in the table Error codes. Array
code Error code. String
Example: GW0001
description Error description. String
Example: Invalid merchant URL