API > POST /orders/virtual_card

POST/orders/virtual_card

PROD

https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/virtual_card

TEST

https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/virtual_card

Server to Server payment (PCI certification required) via virtual card.

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

order

Object containing the detail of the order.

Object

orderId

Merchant order id, unique in the merchant domain.

String
Max. length: 18
Example: btid2384983

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 in ISO 4217 code.

String
Example: EUR

customerId

Customer ID for this transaction.

String
Max. length: 27
Example: mcid97295873

description

Transaction description.

String
Max. length: 255
Example: TV 3423

customField

Additional transaction description.

String
Max. length: 255
Example: weekend promotion

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

transactionSummary

Array containing the transaction summary.

Array

language

Language to be used on the transaction summary details, ISO 639-2.

String
Example: eng

summaryList

Array containing the summary list.

Array

		label	Label of the fields.	String Max. length: 50 Example: Number of people
		value	Value.	String Example: 4

termsAndConditionsIds

Facility T&C identifier array. Insertion of terms and conditions

Array

card

Object containing the details of the payment card.

Object

pan	Card PAN.	String Min. length: 13 Max. length: 19 Example: 23498093745973
expiryDate	Card expiry date in format mmyy.	String Example: 0824
cvv	Card Validation Value, when available.	String Min. length: 3 Max. length: 4 Example: 234

captureType

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 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 null the capture will be IMPLICIT
        c. if the captureType is IMPLICIT the capture will be IMPLICIT

String
Example: EXPLICIT

sessionAmount

Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals). Used when the amount is different by the one present on the order. The currency to consider is the one defined to the amount order.

String
Example: 3545

RESPONSE 200

Payment 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

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

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"}}

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

RESPONSE 401

Unauthorized - No Header and Body for this response

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