No results

POST/v2/svs/3dsPay

PROD
https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v2/svs/3dsPay
TEST
https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v2/svs/3dsPay

Authorize a 3D Secure payment with an external MPI

PARAM HEADER
NAME DESCRIPTION FORMAT
Correlation-Id Mandatory field in UUID v4 format.
The purpose of this field is to trace the request across different systems, making debugging and request tracking easier.
 String
Format: uuid
Example: 123e4567-e89b-12d3-a456-426614174000
Idempotency-Key Idempotency key to ensure idempotent requests. It is used to prevent duplicate operations in case of network issues or retries.
The value must be unique for each request and can be up to 128 characters long.
 String
X-Api-Key Authentication API Key. String
Format: uuid
Example: 625b4884-38f8-11ed-a261-0242ac120002
PARAM PATH
NAME DESCRIPTION FORMAT
No param path
PARAM QUERY
NAME DESCRIPTION FORMAT
No param query
PARAM BODY

Payment authorization request

NAME DESCRIPTION FORMAT
card Object containing the details of the payment card.
 Object
cvv Card Validation Value, when available.
 String
Min. length: 3
Max. length: 4
Example: 123
expiryDate Card expiry date in format mmyy.
 String
Min. length: 4
Max. length: 5
Example: 1225
pan Card PAN.
 String
Min. length: 12
Max. length: 19
Example: 1234567890123456
order Contains the information about the order and additional data needed for specific kind of payments.
 Object
amount Transaction amount in smallest currency unit. 50 EUR is represented
as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
 String
Example: 3545
currency Transaction currency. ISO 4217 alphabetic code
 String
Example: EUR
customField Additional transaction description String
Max. length: 255
Example: weekend promotion
customerId Customer identifier computed by the merchant to match the registered customer on the ecommerce platform.
Use only letters, digits, underscore (_), or hyphen (-).
 String
Max. length: 27
Example: mcid97295873
description Transaction description String
Max. length: 255
Example: TV LG 3423
orderId Merchant order id, unique in the merchant domain String
Max. length: 27
Example: btid2384983
plan Object containing the details of the plan description.
You can see the plan created through the "subscription" menu in your backoffice.
Based on the different `planType` values, the plan can be used for different purposes:
- FIXED: each installment has the same amount and specified due dates.
- VARIABLE: each installment can have a different amount and specified due dates.
- ACQUIRER_AGREEMENT: managed by the acquirer agreement, the number of installments and the amount of each installment is defined by the acquirer.
 Object
contractId Contract identifier.
The value must be between 1 and 18 characters long. To keep it unique, use a stable merchant or channel prefix together with a monotonic sequence, timestamp, or platform contract reference, avoiding reuse for different recurring contracts.
 String
Min. length: 1
Max. length: 18
Example: C2834987
planType Possible values:
- FIXED: each installment has the same amount and specified due dates.
- VARIABLE: each installment can have a different amount and specified due dates.
- ACQUIRER_AGREEMENT: managed by the acquirer agreement, the number of installments and the amount of each installment is defined by the acquirer.
 String
status Possible values:
- ACTIVE: the plan is active and can be used for transactions.
- INACTIVE: the plan is inactive and cannot be used for transactions.
- COMPLETED: the plan has been completed and all installments have been paid.
 String
totalAmount Total amount of the plan in smallest currency unit.
The currency applied is the one from the order.
 String
termsAndConditionsIds Facility T&C identifier array. Insertion of terms and conditions
 Array
paymentSession This is the base payment session object pay endpoint.
It contains the amount, action and capture information.


This is the payment session object for the server-to-server pay endpoint.
It contains the notification url in which the payment session will be notified at the end of the payment process.


Authentication data produced by an MPI (Mastercard SecureCode, Visa Secure)

This is the payment session object for the server-to-server pay endpoint.
It contains the authentication data produced by an MPI (Mastercard SecureCode, Visa Secure).
Data from the MPI (Mastercard SecureCode, Visa Secure) is required to execute the payment.
 Object
action Indicates the type of operation:
* PAY - performs a payment transaction
* VERIFY - performs a verify operation, without any charge, with the sole purpose of confirming the validity of the card data entered by the customer
* PREAUTH - performs a preauthorization operation
 String
Default: PAY
Example: PAY
amount Amount 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)
This works as described in ISO 4217
 String
Example: 5000
capture Overwrites the default confirmation method of the terminal, for card payments only:
* IMPLICIT - automatic confirmation
* EXPLICIT - authorization only
Default value depends on the terminal configuration.
1. Terminal set to EXPLICIT:
a. if the captureType is EXPLICIT the capture will be EXPLICIT
b. if the captureType is not present or null the capture will be EXPLICIT
c. if the captureType is IMPLICIT the capture will be IMPLICIT

2. Terminal set to IMPLICIT:
a. if the captureType is EXPLICIT the capture will be an error
b. if the captureType is not present or null the capture will be IMPLICIT
c. if the captureType is IMPLICIT the capture will be IMPLICIT
 String
Example: EXPLICIT
exemptions NO_PREFERENCE, CHALLENGE_REQUESTED
 String
Example: NO_PREFERENCE
mpiData Authentication data produced by an MPI (Mastercard SecureCode, Visa Secure) Object
authenticationResponse In 3D Secure 2, this is the transStatus from the challenge result.
If the transaction was frictionless, omit this parameter.
 String
authenticationValue The cardholder authentication value (base64 encoded, 20 bytes in a decoded form).
 String
challengeCancel Indicator informing the Access Control Server (ACS)
and the Directory Server (DS) that the authentication has been cancelled.
For possible values:
00 Data element is absent or value has been sent back with the key challengeCancel.
01 Cardholder selected Cancel.
02 3DS Requestor cancelled Authentication.
03 Transaction abandoned.
04 Transaction timed out at ACS — other timeouts.
05 Transaction timed out at ACS — first CReq not received by ACS.
06 Transaction error.
07 Unknown.
08 Transaction timed out at SDK.
 String
directoryResponse In 3D Secure 2, this is the transStatus from the ARes.
 String
dsTransID Supported for 3D Secure 2.
The unique transaction identifier assigned by the Directory Server (DS)
to identify a single transaction.
 String
eci The electronic commerce indicator.
- 05
- 06
- 07
 String
riskScore Risk score calculated by Directory Server (DS).
 String
tokenAuthenticationVerificationValue Network token authentication verification value (TAVV).
The network token cryptogram.
 String
transStatusReason Provides information on why the transStatus field has the specified value.
This is strongly suggested to be sent during authorization.
- 01(Card Authentication failed)
- 02(Unknown Device)
- 03(Unsupported Device)
- 04(Exceeds authentication frequency limit)
- 05(Expired card)
- 06(Invalid card number)
- 07(Invalid transaction)
- 08(No Card record)
- 09(Security failure)
- 10(Stolen card)
- 11(Suspected fraud)
- 12(Transaction not permitted to cardholder)
- 13(Cardholder not enrolled in service)
- 14(Transaction timed out at the ACS)
- 15(Low confidence)
- 16(Medium confidence)
- 17(High confidence)
- 18(Very High confidence)
- 19(Exceeds ACS maximum challenges)
- 20(Non-Payment transaction not supported)
- 21(3RI transaction not supported)
- 22(ACS technical issue)
- 23(Decoupled Authentication required by ACS but not requested by 3DS Requestor)
- 24(3DS Requestor Decoupled Max Expiry Time exceeded)
- 25(Decoupled Authentication was provided insufficient time to authenticatexcardholder. ACS will not make attempt)
- 26(Authentication attempted but not performed by the cardholder)
- 27–79(Reserved for EMVCo future use)
- 80–99(Reserved for DS use)
 String
Min. length: 2
Max. length: 2
Example: 02
transType Identifies the type of transaction being authenticated (derived from ISO8583).
Values accepted:
- 01 = Goods/ Service Purchase
- 03 = Check Acceptance
- 10 = Account Funding
- 11 = Quasi-Cash Transaction
- 28 = Prepaid Activation and Load
 String
Max. length: 2
version The version of the 3D Secure protocol which the card is enrolled on
This list is subjected to change during time.
- 1.0
- 2.1
- 2.2
- 2.3
 String
notificationUrl This is the url in which the payment session will be notified
at the end of the payment process.
please view the documentation for the notification payload.
 String
Example: https://my.server.com/xpay/notify
recurrence Defines the settings for a recurring payment. The settings are used to create a contract that can be used for subsequent payments.
Content of this object may change based on `contractType`, please refer to the specific contract type for more details.
 Object
contractId The contractId is a unique identifier of the contract.
It is generated by merchants systems and is used to identify the contract in the subsequent payments.
 String
Min. length: 1
Max. length: 18
Example: C2834987
contractType Defines the type of contract that will be used for subsequent payments:
* CIT - the contract can be used only for subsequent payments initiated by the customer.
* MIT_SCHEDULED - the contract can be used for scheduled merchant initiated transactions. The number of day between one payment and another shall be equal or higher than the value of contractFrequency.
* MIT_UNSCHEDULED - the contract can be used for unscheduled merchant initiated transactions. The contractFrequency has no effect in this case.
 String
Example: CIT
recurringAction Defines the action for a recurring payment:
* **SUBSEQUENT_PAYMENT** – “OneClick” payment using an existing contract
* **CONTRACT_CREATION** – Creation of a new contract
* **CARD_SUBSTITUTION** – Replacement of the card linked to an existing contract (Note: only for contracts created with the payment method CARD)
 String
Example: CONTRACT_CREATION
Arrow RESPONSE 200
Deactivation successful - No Header for this response
BODY
NAME DESCRIPTION FORMAT
operation Object containing the details of a payment operation.
 Object
additionalData Map of additional fields specific to the chosen payment method
 Object
cancelledOperationId Operation id to be undone
 String
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
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
billingAddress Object containing the detail of the customer's address.
 Object
additionalInfo Additional info of address, for example floor.
Recommended maximum length: 50 characters.
 String
Example: Quinto Piano, Scala B
city City.
Recommended maximum length: 40 characters.
 String
Example: Bologna
country State in ISO 3166-1 alpha-3 code.
Recommended maximum length: 3 characters.
 String
Example: ITA
name Name and surname.
Recommended maximum length: 50 characters.
 String
Example: Mario Rossi
postCode Postal code.
Recommended maximum length: 16 characters.
 String
Example: 40124
province Code of province.
Recommended maximum length: 3 characters.
 String
Example: BO
street Full address.
Recommended maximum length: 50 characters.
 String
Example: Piazza Maggiore, 1
cardHolderAcctInfo Object containing information about the buyer's account.
 Object
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-11T00:00:00.000+0000
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
chAccDate Date of activation of the account on the merchant's website.
 String
Example: 2019-02-11T00:00:00.000+0000
chAccPwChangeDate Date of last account password change (including password reset).
 String
Example: 2019-02-11T00:00:00.000+0000
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
destinationAddressUsageDate Date of last use of this delivery address.
 String
Example: 2019-02-11T00:00:00.000+0000
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
nbPurchaseAccount Number of purchases of this account in the last 6 months.
 Integer
Example: 0
paymentAccAgeDate Payment account activation date.
 String
Example: 2019-02-11T00:00:00.000+0000
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
provisionAttemptsDay Number of attempts to add a new card in the last 24 hours.
 Integer
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
txnActivityDay Number of transactions (successful and abandoned) for this account in the previous 24 hours.
 Integer
Example: 0
txnActivityYear Number of transactions (successful and abandoned) for this account in the previous year.
 Integer
Example: 0
cardHolderEmail Email of the cardholder.
Recommended maximum length: 255 characters.
 String
Example: mauro.morandi@nexi.it
cardHolderName Name and surname of the cardholder.
Recommended maximum length: 255 characters.
 String
Example: Mauro Morandi
homePhone Home phone number provided by the Cardholder.
Recommended maximum length: 18 characters.
 String
Example: 391231234567
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 the total amount and currency of the prepaid or gift card(s) purchased.
 Object
currency For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.
EMVCO: giftCardCurr
 String
Example: EUR
value For prepaid or gift card purchase, the purchase amount total
of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).
EMVCO: giftCardAmount
 String
Max. length: 18
Example: 100
giftCardCount Total number of individual prepaid or gift cards/codes purchased.
 Integer
Example: 0
preOrderDate For a pre-ordered purchase, the expected date that the merchandise will be available.
 String
Example: 2019-02-11T00:00:00.000+0000
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
mobilePhone Mobile phone.
Recommended maximum length: 15 characters.
 String
Example: 3280987654
mobilePhoneCountryCode Prefix of the mobile phone.
Recommended maximum length: 4 characters.
 String
Example: +39
recontactConsent In certain scenarios, it is possible to collect the payer's consent to be recontacted by the merchant.
This field indicates whether the payer has given such consent.
 Boolean
shippingAddress Object containing the detail of the customer's address.
 Object
additionalInfo Additional info of address, for example floor.
Recommended maximum length: 50 characters.
 String
Example: Quinto Piano, Scala B
city City.
Recommended maximum length: 40 characters.
 String
Example: Bologna
country State in ISO 3166-1 alpha-3 code.
Recommended maximum length: 3 characters.
 String
Example: ITA
name Name and surname.
Recommended maximum length: 50 characters.
 String
Example: Mario Rossi
postCode Postal code.
Recommended maximum length: 16 characters.
 String
Example: 40124
province Code of province.
Recommended maximum length: 3 characters.
 String
Example: BO
street Full address.
Recommended maximum length: 50 characters.
 String
Example: Piazza Maggiore, 1
tin Tax Identification Number is collected in certain scenarios, such as donations, to comply with tax regulations. It is an identifier used in many countries for tax purposes.
 String
Max. length: 32
Example: 12345678901
workPhone Work phone number provided by the Cardholder.
Recommended maximum length: 18 characters.
 String
Example: 391231234567
omnichannelId Omnichannel identifier. It is used to correlate the same operation across different channels.
 String
operationAmount Operation amount in the payment currency
 String
Example: 3545
operationCurrency Payment currency
 String
Example: EUR
operationId Unique identifier of the operation
 String
Example: 852525265182852619
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 in ISO 8601 format
 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
orderId Merchant order identifier, unique in the merchant domain.
The maximum length is 27 characters. To comply with payment circuit specifications, it is strongly recommended to use an orderId of up to 18 characters.
A good uniqueness strategy is to combine a stable merchant or channel prefix with a monotonic sequence, timestamp, or platform order reference, avoiding reuse for different payments.
 String
Max. length: 27
Example: btid2384983
paymentCircuit One of the payment circuit values returned by the GET payment_methods web service.
The list may include (but not limited to) VISA, MC, AMEX, DINERS, GOOGLE_PAY, APPLE_PAY, PAYPAL, BANCONTACT, BANCOMAT_PAY, MYBANK, PIS, AMAZON_PAY, ALIPAY.
 String
Example: VISA
paymentEndToEndId Identifier defined by the circuit to uniquely identify the transaction.
Required for circuit reconciliation purposes.
 String
Min. length: 18
Max. length: 35
Example: e723hedsdew12345678
paymentInstrumentInfo Payment instrument information
 String
Example: ***6152
paymentLinkId PayByLink id used for correlating this operation with the original link.
 String
Example: 234244353
paymentMethod * CARD - Any card circuit
* APM - Alternative payment method
 String
Example: CARD
warnings List of warnings related to the operation.
 Array
code Warning code. String
Example: TRA001
description Warning description. String
Example: 3DS warning