API > GET /build/state | Payment Gateway

GET/build/state

PROD

https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/build/state

TEST

https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1/build/state

Get current payment status via XPay Build solution.

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

sessionId

Session identifier.

String

PARAM BODY

NAME

DESCRIPTION

FORMAT

No param body

RESPONSE 200

Request successfully processed - No Header for this response

BODY

NAME

DESCRIPTION

FORMAT

state

Transaction status. Possible values:
- CARD_DATA_COLLECTION: the customer has chosen payment by card. The "fieldSet" object containing the iframes for collecting the card data is returned.
- PAYMENT_METHOD_SELECTION: the customer must proceed with the choice of payment method. The "fieldSet" object containing the payment method iframes is returned.
- READY_FOR_PAYMENT: payment ready to be executed, it is necessary to call the API POST /build/finalize_payment.
- REDIRECTED_TO_EXTERNAL_DOMAIN - The url to perform 3D Secure authentication has been provided. The "url" parameter is returned.
- PAYMENT_COMPLETE: Payment has been completed. The "operation" object is returned.
- GDI_VERIFICATION: only with version 2 of XPay Build. The GET build/state request has been invoked during the GDI verification. It is necessary to display a page containing the hidden internal frame.

String

url

Address for 3D Secure authentication. This parameter is returned if the "state" parameter is set to "REDIRECTED_TO_EXTERNAL_DOMAIN".

String
Example: https://{3DS-Ares-Url}

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

fieldSet

Object containing the iframes for choosing payment methods or for collecting card data.

Object

sessionId

Session identifier.

String
Example: sessionId

securityToken

Security token for the transaction.

String
Example: security token

fields

Array of objects containing the iframes corresponding to the payment methods active on the merchant's terminal.

Array

type	Type of field, possible values: - ACTION: field that requires an action by the cardholder on the iframe, in this case the click on the component.	String Example: ACTION
class	Field class, possible values: - APM - CARD	String Example: CARD
id	Field identifier.	String Example: PAY_WITH_CARD
src	Iframe URL dedicated to the payment method.	String Example: https:///field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264

state

String

url

Indirizzo per fase 3D Secure.

String
Example: https:apm_url.it

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