XPay Build APIs

C#PHPNodeShell

Scroll down for code samples, example requests and responses.
Select a language for code samples from the tabs or the mobile navigation menu.

Create an order and initiates a payment through build functionality.

POST /api/v1/orders/build

This service is targeted to ecommerce platforms requiring to implement the payment pages in line with their own dedicated UI style guidelines. The service will return a list of fields expressed in JSON format, to be translated into HTML by the ecommerce platform web app. If the paymentService field is valued at CARDS the service will return a list of fields for the CARD_DATA_COLLECTION without going through the PAYMENT_METHOD_SELECTION state and if it's valued with an APM the service will return an url where the customer should be redirected.

Parameters

Authorizationstringrequired
Authorization
Correlation-Idstring (uuid)required
Mandatory field as format of an UUID v4. The purpose of the field is trace the request among different systems to make easier debug or following a trace.
x-plugin-namestringoptional
x-plugin-name

Create an order and initiates a payment through build functionality.

C#
PHP
Node
Shell

var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/build");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("x-plugin-name", "SOME_STRING_VALUE");
request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request body

merchantUrlstringoptional
to be valued with the protocol and domain url of the ecommerce platform front-end, where the html page encompassing the internal frames is downloaded from. By leveraging on CORS functionality, this ensures a secure communication between the main web page and each of the pages running in the internal frames. Pl find more details at https://www.w3.org/wiki/CORS.
example: https://merchanturl.it

Request body

{
    "merchantUrl": "https://merchanturl.it"
}

Responses

200optional
In case of success, the service returns a list of fields to be rendered in the ecomm web app.
- fieldsarrayoptional
  - classstringoptionalexample: cardData
  - idstringoptionalexample: cardholderName
  - srcstringoptionalexample: https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264
  - typestringoptionalexample: text
- securityTokenstringoptionalexample: security token
- sessionIdstringoptionalexample: sessionId
- sriHashstringoptional
- statestringoptional
  It indicates the flow adopted for the ongoing payment. The possible values are:
  
  PAYMENT_METHOD_SELECTION
  
  GDI_VERIFICATION
  
  CARD_DATA_COLLECTION
  
  READY_FOR_PAYMENT
  
  REDIRECTED_TO_EXTERNAL_DOMAIN
  
  PAYMENT_COMPLETE
  
  PAYMENT_INITIALIZATION
  
  CARD_DATA_COLLECTION, GDI_VERIFICATION, PAYMENT_COMPLETE, PAYMENT_METHOD_SELECTION, READY_FOR_PAYMENT, REDIRECTED_TO_EXTERNAL_DOMAIN, PAYMENT_INITIALIZATION
  example: CARD_DATA_COLLECTION
- urlstringoptionalexample: https:apm_url.it
- warningsarrayoptional
201Createdoptional
400Invalid request dataoptional
- timestampstringoptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional
500Internal Server Erroroptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL

{
    "securityToken": "security token",
    "sriHash": "sriHash",
    "warnings": [
        {
            "code": "TRA001",
            "description": "3DS warning"
        },
        {
            "code": "TRA001",
            "description": "3DS warning"
        }
    ],
    "sessionId": "sessionId",
    "state": "CARD_DATA_COLLECTION",
    "fields": [
        {
            "src": "https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264",
            "id": "cardholderName",
            "type": "text",
            "class": "cardData"
        },
        {
            "src": "https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264",
            "id": "cardholderName",
            "type": "text",
            "class": "cardData"
        }
    ],
    "url": "https:apm_url.it"
}

Finalize a payment.

POST /api/v1/build/finalize_payment

This service shall be invoked by the ecommerce platforms to finalize the payment. It is limited to the flow versions 1 and 3.

Parameters

Authorizationstringrequired
Authorization
Correlation-Idstring (uuid)required
Mandatory field as format of an UUID v4. The purpose of the field is trace the request among different systems to make easier debug or following a trace.

Finalize a payment.

C#
PHP
Node
Shell

var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/build/finalize_payment");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("Correlation-Id", "SOME_STRING_VALUE");
request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request body

sessionIdstringoptional

Request body

{
    "sessionId": "sessionId"
}

Responses

200optional
The returned states can be: * PAYMENT_COMPLETE: meaning that the payment flow reached the end, either with success or failure. The operation field describes in detail the payment result. * REDIRECTED_TO_EXTERNAL_DOMAIN: it is required to perform a user authentication on an external domain. This may happen for a 3DS challenge of a card payment or for any payment performed with alternative payment methods. In all cases, the user's browser shall be redirected to the url indicated in the field 'url'.
- fieldSetobjectoptional
  - fieldsarrayoptional
    classstringoptionalexample: cardData
    idstringoptionalexample: cardholderName
    srcstringoptionalexample: https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264
    typestringoptionalexample: text
  - securityTokenstringoptionalexample: security token
  - sessionIdstringoptionalexample: sessionId
  - sriHashstringoptional
  - statestringoptional
    It indicates the flow adopted for the ongoing payment. The possible values are:
    
    PAYMENT_METHOD_SELECTION
    
    GDI_VERIFICATION
    
    CARD_DATA_COLLECTION
    
    READY_FOR_PAYMENT
    
    REDIRECTED_TO_EXTERNAL_DOMAIN
    
    PAYMENT_COMPLETE
    
    PAYMENT_INITIALIZATION
    
    CARD_DATA_COLLECTION, GDI_VERIFICATION, PAYMENT_COMPLETE, PAYMENT_METHOD_SELECTION, READY_FOR_PAYMENT, REDIRECTED_TO_EXTERNAL_DOMAIN, PAYMENT_INITIALIZATION
    example: CARD_DATA_COLLECTION
  - urlstringoptionalexample: https:apm_url.it
  - warningsarrayoptional
- operationobjectoptional
  - additionalDataobjectoptional
    Map of additional fields specific to the chosen payment method
  - cancelledOperationIdstringoptional
    Operation id to be undone
  - channelstringoptional
    It 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
    example: ECOMMERCE
  - customerInfoobjectoptional
    This object contains information about the customer. It is strongly recommended to provide as much information as possible in order to facilitate the risk assessment, fraud prevention and the payment processing. It also helps to improve the customer experience by reducing the number of fields to be filled in by the customer and raise the chances to avoid Strong Customer Authentication (SCA) when the transaction is subject to the PSD2 regulation.
    billingAddressobjectoptional
    additionalInfostringoptionalexample: Quinto Piano, Scala B
    citystringoptionalexample: Bologna
    countrystringoptional
    ISO 3166-1 alpha-3
    example: ITA
    namestringoptionalexample: Mario Rossi
    postCodestringoptionalexample: 40124
    provincestringoptionalexample: BO
    streetstringoptionalexample: Piazza Maggiore, 1
    cardHolderAcctInfoobjectoptional
    chAccAgeIndicatorstringoptional
    Length of time that the cardholder has had the account with the 3DS Requestor. Values accepted:
    
    01 = Changed during this transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 day EMVCO: ?
    
    example: 01
    chAccChangeDatestringoptional
    Date 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. ISO 8601 format
    example: 2019-02-11T00:00:00.000+0000
    chAccChangeIndicatorstringoptional
    Length of time since the cardholder's account information was last changed on merchant e-comm platform, including Billing or Shipping address, new payment account, or new user(s) added. Values accepted:
    
    01 = Changed during this transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 day EMVCO: chAccChangeInd
    
    example: 01
    chAccDatestringoptional
    Date when the cardholder opened the account with the merchant's e-commerce platform. ISO 8601 format EMVCO: chAccDate
    example: 2019-02-11T00:00:00.000+0000
    chAccPwChangeDatestringoptional
    Date when the cardholder last changed the password on merchant's e-commerce platform. ISO 8601 format EMVCO: chAccPwChange
    example: 2019-02-11T00:00:00.000+0000
    chAccPwChangeIndicatorstringoptional
    Indicates when the cardholder last changed the password or asked for a password reset on merchant's e-commerce platform.
    
    01 = No change
    
    02 = Changed during this transaction
    
    03 = Less than 30 days
    
    04 = 30−60 days
    
    05 = More than 60 days
    
    example: 01
    destinationAddressUsageDatestringoptional
    Date when the shipping address used for this transaction was first used on merchant's e-commerce platform. ISO 8601 format EMVCO: shipAddressUsage
    example: 2019-02-11T00:00:00.000+0000
    destinationAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used on the merchant's e-commerce platform. Values accepted:
    
    01 = This transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 days EMVCO: shipAddressUsageInd
    
    example: 01
    destinationNameIndicatorstringoptional
    Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. Values accepted:
    
    01 = Account Name identical to shipping Name
    
    02 = Account Name different than shipping Name EMVCO: shipNameIndicator
    
    example: 01
    nbPurchaseAccountinteger (int32)optional
    Number of purchases with this cardholder account during the previous six months. EMVCO: nbPurchaseAccount
    example: 0
    paymentAccAgeDatestringoptional
    Date when the payment method has been added to the cardholder's account on the merchant's e-commerce platform. ISO 8601 format EMVCO: paymentAccAge
    example: 2019-02-11T00:00:00.000+0000
    paymentAccIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the cardholder's account with the merchant's e-commerce platform. Values accepted:
    
    01 = This transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 days EMVCO: paymentAccInd
    
    example: 0
    provisionAttemptsDayinteger (int32)optional
    Number of Add Card attempts in the last 24 hours. EMVCO: provisionAttemptsDay
    example: 0
    suspiciousAccActivitystringoptional
    Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the cardholder account. Values accepted:
    
    01 = No suspicious activity has been observed
    
    02 = Suspicious activity has been observed
    
    example: 01
    txnActivityDayinteger (int32)optional
    Number of transactions (successful and abandoned) for this cardholder account on merchant's e-commerce platform across all payment accounts in the previous 24 hours. EMVCO: txnActivityDay
    example: 0
    txnActivityYearinteger (int32)optional
    Number of transactions (successful and abandoned) for this cardholder account on merchant's e-commerce platform across all payment accounts in the previous year. EMVCO: txnActivityYear
    example: 0
    cardHolderEmailstring (email)optionalexample: mauro.morandi@nexi.it
    cardHolderNamestringoptionalexample: Mauro Morandi
    homePhonestringoptional
    The home phone number provided by the Cardholder.
    example: 391231234567
    merchantRiskIndicatorobjectoptional
    deliveryEmailstringoptional
    For Electronic delivery, the email address to which the merchandise was delivered.
    example: john.doe@email.com
    deliveryTimeframestringoptional
    Indicates the merchandise delivery timeframe. Values accepted:
    
    01 = Electronic Delivery
    
    02 = Same day shipping
    
    03 = Overnight shipping
    
    04 = Two-day or more shipping
    
    example: 01
    giftCardAmountobjectoptional
    currencystringoptional
    For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217. EMVCO: giftCardCurr
    example: EUR
    valuestringoptional
    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
    example: 100
    giftCardCountinteger (int32)optional
    For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
    example: 0
    preOrderDatestringoptional
    For a pre-ordered purchase, the expected date that the merchandise will be available. ISO 8601 format
    example: 2019-02-11T00:00:00.000+0000
    preOrderPurchaseIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    example: 01
    reorderItemsIndicatorstringoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    example: 01
    shipIndicatorstringoptional
    Indicates shipping method chosen for the transaction.
    example: 01
    mobilePhonestringoptionalexample: 3280987654
    mobilePhoneCountryCodestringoptionalexample: 39
    shippingAddressobjectoptional
    additionalInfostringoptionalexample: Quinto Piano, Scala B
    citystringoptionalexample: Bologna
    countrystringoptional
    ISO 3166-1 alpha-3
    example: ITA
    namestringoptionalexample: Mario Rossi
    postCodestringoptionalexample: 40124
    provincestringoptionalexample: BO
    streetstringoptionalexample: Piazza Maggiore, 1
    workPhonestringoptional
    The work phone number provided by the Cardholder.
    example: 391231234567
  - omnichannelIdstringoptional
  - operationAmountstringoptional
    Operation amount in the payment currency
    example: 3545
  - operationCurrencystringoptional
    Payment currency
    example: EUR
  - operationIdstringoptionalexample: 3470744
  - operationResultstringoptional
    Transaction 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
    
    DENIED
    
    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, DENIED, THREEDS_VALIDATED, THREEDS_FAILED, PENDING, CANCELED, VOIDED, REFUNDED, FAILED
    example: AUTHORIZED
  - operationTimestring (date-time)optional
    Operation time in ISO 8601 format
  - operationTypestringoptional
    It indicates the purpose of the request:
    
    AUTHORIZATION - any authorization with explicit capture
    
    CAPTURE - a captured authorization or an implicit captured payment
    
    REFUND - refund of a captured amount
    
    CANCEL - the rollback of an capture, refund.
    
    NOSHOW
    
    INCREMENTAL
    
    DELAY_CHARGE
    
    CARD_VERIFICATION
    
    CARD_CHECK
    
    VOID - reversal of an authorization
    
    AUTHORIZATION, CAPTURE, REFUND, CANCEL, NOSHOW, INCREMENTAL, DELAY_CHARGE, CARD_VERIFICATION, CARD_CHECK, VOID
    example: CAPTURE
  - orderIdstringoptional
    Merchant order id, unique in the merchant domain
    example: btid2384983
  - paymentCircuitstringoptional
    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.
    example: VISA
  - paymentEndToEndIdstringoptional
    It is defined by the circuit to uniquely identify the transaction. Required for circuid reconciliation purposes.
    example: e723hedsdew
  - paymentInstrumentInfostringoptional
    Payment instrument information
    example: ***6152
  - paymentLinkIdstringoptional
    PayByLink id used for correlating this operation with the original link.
    example: 234244353
  - paymentMethodstringoptional
    
    CARD - Any card circuit
    
    APM - Alternative payment method
    
    CARD, APM
    example: CARD
  - warningsarrayoptional
- statestringoptional
  It indicates the flow adopted for the ongoing payment. The possible values are:
  
  PAYMENT_METHOD_SELECTION
  
  GDI_VERIFICATION
  
  CARD_DATA_COLLECTION
  
  READY_FOR_PAYMENT
  
  REDIRECTED_TO_EXTERNAL_DOMAIN
  
  PAYMENT_COMPLETE
  
  PAYMENT_INITIALIZATION
  
  CARD_DATA_COLLECTION, GDI_VERIFICATION, PAYMENT_COMPLETE, PAYMENT_METHOD_SELECTION, READY_FOR_PAYMENT, REDIRECTED_TO_EXTERNAL_DOMAIN, PAYMENT_INITIALIZATION
  example: CARD_DATA_COLLECTION
- urlstringoptionalexample: https://{3DS-Ares-Url}
201Createdoptional
400Invalid request dataoptional
- timestampstringoptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional
500Internal Server Erroroptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL

200
PAYMENT_COMPLETE
REDIRECTED_TO_EXTERNAL_DOMAIN
400
500

{
    "fieldSet": {
        "securityToken": "security token",
        "sriHash": "sriHash",
        "warnings": [
            {
                "code": "TRA001",
                "description": "3DS warning"
            },
            {
                "code": "TRA001",
                "description": "3DS warning"
            }
        ],
        "sessionId": "sessionId",
        "state": "CARD_DATA_COLLECTION",
        "fields": [
            {
                "src": "https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264",
                "id": "cardholderName",
                "type": "text",
                "class": "cardData"
            },
            {
                "src": "https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264",
                "id": "cardholderName",
                "type": "text",
                "class": "cardData"
            }
        ],
        "url": "https:apm_url.it"
    },
    "state": "CARD_DATA_COLLECTION",
    "operation": {
        "paymentLinkId": "234244353",
        "orderId": "btid2384983",
        "warnings": [
            {
                "code": "TRA001",
                "description": "3DS warning"
            },
            {
                "code": "TRA001",
                "description": "3DS warning"
            }
        ],
        "channel": "ECOMMERCE",
        "customerInfo": {
            "mobilePhone": "3280987654",
            "cardHolderName": "Mauro Morandi",
            "homePhone": "391231234567",
            "mobilePhoneCountryCode": 39,
            "shippingAddress": {
                "country": "ITA",
                "province": "BO",
                "city": "Bologna",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "name": "Mario Rossi",
                "postCode": "40124"
            },
            "cardHolderAcctInfo": {
                "chAccDate": "2019-02-11T00:00:00.000+0000",
                "txnActivityYear": 0,
                "chAccPwChangeDate": "2019-02-11T00:00:00.000+0000",
                "paymentAccAgeDate": "2019-02-11T00:00:00.000+0000",
                "provisionAttemptsDay": 0,
                "destinationAddressUsageDate": "2019-02-11T00:00:00.000+0000",
                "chAccChangeDate": "2019-02-11T00:00:00.000+0000",
                "destinationAddressUsageIndicator": "01",
                "chAccChangeIndicator": "01",
                "nbPurchaseAccount": 0,
                "destinationNameIndicator": "01",
                "chAccPwChangeIndicator": "01",
                "paymentAccIndicator": "0",
                "chAccAgeIndicator": "01",
                "suspiciousAccActivity": "01",
                "txnActivityDay": 0
            },
            "workPhone": "391231234567",
            "billingAddress": {
                "country": "ITA",
                "province": "BO",
                "city": "Bologna",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "name": "Mario Rossi",
                "postCode": "40124"
            },
            "cardHolderEmail": "mauro.morandi@nexi.it",
            "merchantRiskIndicator": {
                "deliveryTimeframe": "01",
                "preOrderDate": "2019-02-11T00:00:00.000+0000",
                "reorderItemsIndicator": "01",
                "shipIndicator": "01",
                "giftCardAmount": {
                    "currency": "EUR",
                    "value": "100"
                },
                "deliveryEmail": "john.doe@email.com",
                "giftCardCount": 0,
                "preOrderPurchaseIndicator": "01"
            }
        },
        "operationTime": "2000-01-23T04:56:07.000Z",
        "paymentCircuit": "VISA",
        "omnichannelId": "omnichannelId",
        "operationAmount": "3545",
        "operationId": "3470744",
        "paymentEndToEndId": "e723hedsdew",
        "paymentMethod": "CARD",
        "operationType": "CAPTURE",
        "additionalData": {
            "authorizationCode": "647189",
            "cardCountry": "ITA",
            "threeDS": "FULL_SECURE",
            "schemaTID": "MCS01198U",
            "multiCurrencyConversion": {
                "amount": "2662",
                "currency": "JPY",
                "exchangeRate": "0.007510523"
            }
        },
        "operationCurrency": "EUR",
        "paymentInstrumentInfo": "***6152",
        "cancelledOperationId": "",
        "operationResult": "AUTHORIZED"
    },
    "url": "https://{3DS-Ares-Url}"
}

Cancel a payment.

POST /api/v1/build/cancel

This service is targeted to ecommerce platforms in order to cancel the current payment session. This is typically required to clean up the collected data in case the user decided to quit the payment before completion.

Parameters

Authorizationstringrequired
Authorization
Correlation-Idstring (uuid)required
Mandatory field as format of an UUID v4. The purpose of the field is trace the request among different systems to make easier debug or following a trace.

Cancel a payment.

C#
PHP
Node
Shell

var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/build/cancel");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("Correlation-Id", "SOME_STRING_VALUE");
request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request body

sessionIdstringoptional

Request body

{
    "sessionId": "sessionId"
}

Responses

200optional
In case of success, the service returns the specific status based on the state machine.
- fieldSetobjectoptional
  - fieldsarrayoptional
    classstringoptionalexample: cardData
    idstringoptionalexample: cardholderName
    srcstringoptionalexample: https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264
    typestringoptionalexample: text
  - securityTokenstringoptionalexample: security token
  - sessionIdstringoptionalexample: sessionId
  - sriHashstringoptional
  - statestringoptional
    It indicates the flow adopted for the ongoing payment. The possible values are:
    
    PAYMENT_METHOD_SELECTION
    
    GDI_VERIFICATION
    
    CARD_DATA_COLLECTION
    
    READY_FOR_PAYMENT
    
    REDIRECTED_TO_EXTERNAL_DOMAIN
    
    PAYMENT_COMPLETE
    
    PAYMENT_INITIALIZATION
    
    CARD_DATA_COLLECTION, GDI_VERIFICATION, PAYMENT_COMPLETE, PAYMENT_METHOD_SELECTION, READY_FOR_PAYMENT, REDIRECTED_TO_EXTERNAL_DOMAIN, PAYMENT_INITIALIZATION
    example: CARD_DATA_COLLECTION
  - urlstringoptionalexample: https:apm_url.it
  - warningsarrayoptional
- operationobjectoptional
  - additionalDataobjectoptional
    Map of additional fields specific to the chosen payment method
  - cancelledOperationIdstringoptional
    Operation id to be undone
  - channelstringoptional
    It 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
    example: ECOMMERCE
  - customerInfoobjectoptional
    This object contains information about the customer. It is strongly recommended to provide as much information as possible in order to facilitate the risk assessment, fraud prevention and the payment processing. It also helps to improve the customer experience by reducing the number of fields to be filled in by the customer and raise the chances to avoid Strong Customer Authentication (SCA) when the transaction is subject to the PSD2 regulation.
    billingAddressobjectoptional
    additionalInfostringoptionalexample: Quinto Piano, Scala B
    citystringoptionalexample: Bologna
    countrystringoptional
    ISO 3166-1 alpha-3
    example: ITA
    namestringoptionalexample: Mario Rossi
    postCodestringoptionalexample: 40124
    provincestringoptionalexample: BO
    streetstringoptionalexample: Piazza Maggiore, 1
    cardHolderAcctInfoobjectoptional
    chAccAgeIndicatorstringoptional
    Length of time that the cardholder has had the account with the 3DS Requestor. Values accepted:
    
    01 = Changed during this transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 day EMVCO: ?
    
    example: 01
    chAccChangeDatestringoptional
    Date 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. ISO 8601 format
    example: 2019-02-11T00:00:00.000+0000
    chAccChangeIndicatorstringoptional
    Length of time since the cardholder's account information was last changed on merchant e-comm platform, including Billing or Shipping address, new payment account, or new user(s) added. Values accepted:
    
    01 = Changed during this transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 day EMVCO: chAccChangeInd
    
    example: 01
    chAccDatestringoptional
    Date when the cardholder opened the account with the merchant's e-commerce platform. ISO 8601 format EMVCO: chAccDate
    example: 2019-02-11T00:00:00.000+0000
    chAccPwChangeDatestringoptional
    Date when the cardholder last changed the password on merchant's e-commerce platform. ISO 8601 format EMVCO: chAccPwChange
    example: 2019-02-11T00:00:00.000+0000
    chAccPwChangeIndicatorstringoptional
    Indicates when the cardholder last changed the password or asked for a password reset on merchant's e-commerce platform.
    
    01 = No change
    
    02 = Changed during this transaction
    
    03 = Less than 30 days
    
    04 = 30−60 days
    
    05 = More than 60 days
    
    example: 01
    destinationAddressUsageDatestringoptional
    Date when the shipping address used for this transaction was first used on merchant's e-commerce platform. ISO 8601 format EMVCO: shipAddressUsage
    example: 2019-02-11T00:00:00.000+0000
    destinationAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used on the merchant's e-commerce platform. Values accepted:
    
    01 = This transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 days EMVCO: shipAddressUsageInd
    
    example: 01
    destinationNameIndicatorstringoptional
    Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. Values accepted:
    
    01 = Account Name identical to shipping Name
    
    02 = Account Name different than shipping Name EMVCO: shipNameIndicator
    
    example: 01
    nbPurchaseAccountinteger (int32)optional
    Number of purchases with this cardholder account during the previous six months. EMVCO: nbPurchaseAccount
    example: 0
    paymentAccAgeDatestringoptional
    Date when the payment method has been added to the cardholder's account on the merchant's e-commerce platform. ISO 8601 format EMVCO: paymentAccAge
    example: 2019-02-11T00:00:00.000+0000
    paymentAccIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the cardholder's account with the merchant's e-commerce platform. Values accepted:
    
    01 = This transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 days EMVCO: paymentAccInd
    
    example: 0
    provisionAttemptsDayinteger (int32)optional
    Number of Add Card attempts in the last 24 hours. EMVCO: provisionAttemptsDay
    example: 0
    suspiciousAccActivitystringoptional
    Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the cardholder account. Values accepted:
    
    01 = No suspicious activity has been observed
    
    02 = Suspicious activity has been observed
    
    example: 01
    txnActivityDayinteger (int32)optional
    Number of transactions (successful and abandoned) for this cardholder account on merchant's e-commerce platform across all payment accounts in the previous 24 hours. EMVCO: txnActivityDay
    example: 0
    txnActivityYearinteger (int32)optional
    Number of transactions (successful and abandoned) for this cardholder account on merchant's e-commerce platform across all payment accounts in the previous year. EMVCO: txnActivityYear
    example: 0
    cardHolderEmailstring (email)optionalexample: mauro.morandi@nexi.it
    cardHolderNamestringoptionalexample: Mauro Morandi
    homePhonestringoptional
    The home phone number provided by the Cardholder.
    example: 391231234567
    merchantRiskIndicatorobjectoptional
    deliveryEmailstringoptional
    For Electronic delivery, the email address to which the merchandise was delivered.
    example: john.doe@email.com
    deliveryTimeframestringoptional
    Indicates the merchandise delivery timeframe. Values accepted:
    
    01 = Electronic Delivery
    
    02 = Same day shipping
    
    03 = Overnight shipping
    
    04 = Two-day or more shipping
    
    example: 01
    giftCardAmountobjectoptional
    currencystringoptional
    For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217. EMVCO: giftCardCurr
    example: EUR
    valuestringoptional
    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
    example: 100
    giftCardCountinteger (int32)optional
    For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
    example: 0
    preOrderDatestringoptional
    For a pre-ordered purchase, the expected date that the merchandise will be available. ISO 8601 format
    example: 2019-02-11T00:00:00.000+0000
    preOrderPurchaseIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    example: 01
    reorderItemsIndicatorstringoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    example: 01
    shipIndicatorstringoptional
    Indicates shipping method chosen for the transaction.
    example: 01
    mobilePhonestringoptionalexample: 3280987654
    mobilePhoneCountryCodestringoptionalexample: 39
    shippingAddressobjectoptional
    additionalInfostringoptionalexample: Quinto Piano, Scala B
    citystringoptionalexample: Bologna
    countrystringoptional
    ISO 3166-1 alpha-3
    example: ITA
    namestringoptionalexample: Mario Rossi
    postCodestringoptionalexample: 40124
    provincestringoptionalexample: BO
    streetstringoptionalexample: Piazza Maggiore, 1
    workPhonestringoptional
    The work phone number provided by the Cardholder.
    example: 391231234567
  - omnichannelIdstringoptional
  - operationAmountstringoptional
    Operation amount in the payment currency
    example: 3545
  - operationCurrencystringoptional
    Payment currency
    example: EUR
  - operationIdstringoptionalexample: 3470744
  - operationResultstringoptional
    Transaction 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
    
    DENIED
    
    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, DENIED, THREEDS_VALIDATED, THREEDS_FAILED, PENDING, CANCELED, VOIDED, REFUNDED, FAILED
    example: AUTHORIZED
  - operationTimestring (date-time)optional
    Operation time in ISO 8601 format
  - operationTypestringoptional
    It indicates the purpose of the request:
    
    AUTHORIZATION - any authorization with explicit capture
    
    CAPTURE - a captured authorization or an implicit captured payment
    
    REFUND - refund of a captured amount
    
    CANCEL - the rollback of an capture, refund.
    
    NOSHOW
    
    INCREMENTAL
    
    DELAY_CHARGE
    
    CARD_VERIFICATION
    
    CARD_CHECK
    
    VOID - reversal of an authorization
    
    AUTHORIZATION, CAPTURE, REFUND, CANCEL, NOSHOW, INCREMENTAL, DELAY_CHARGE, CARD_VERIFICATION, CARD_CHECK, VOID
    example: CAPTURE
  - orderIdstringoptional
    Merchant order id, unique in the merchant domain
    example: btid2384983
  - paymentCircuitstringoptional
    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.
    example: VISA
  - paymentEndToEndIdstringoptional
    It is defined by the circuit to uniquely identify the transaction. Required for circuid reconciliation purposes.
    example: e723hedsdew
  - paymentInstrumentInfostringoptional
    Payment instrument information
    example: ***6152
  - paymentLinkIdstringoptional
    PayByLink id used for correlating this operation with the original link.
    example: 234244353
  - paymentMethodstringoptional
    
    CARD - Any card circuit
    
    APM - Alternative payment method
    
    CARD, APM
    example: CARD
  - warningsarrayoptional
- statestringoptional
  It indicates the flow adopted for the ongoing payment. The possible values are:
  
  PAYMENT_METHOD_SELECTION
  
  GDI_VERIFICATION
  
  CARD_DATA_COLLECTION
  
  READY_FOR_PAYMENT
  
  REDIRECTED_TO_EXTERNAL_DOMAIN
  
  PAYMENT_COMPLETE
  
  PAYMENT_INITIALIZATION
  
  CARD_DATA_COLLECTION, GDI_VERIFICATION, PAYMENT_COMPLETE, PAYMENT_METHOD_SELECTION, READY_FOR_PAYMENT, REDIRECTED_TO_EXTERNAL_DOMAIN, PAYMENT_INITIALIZATION
  example: CARD_DATA_COLLECTION
- urlstringoptionalexample: https://{3DS-Ares-Url}
201Createdoptional
400Invalid request dataoptional
- timestampstringoptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional
500Internal Server Erroroptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL

{
    "fieldSet": {
        "securityToken": "security token",
        "sriHash": "sriHash",
        "warnings": [
            {
                "code": "TRA001",
                "description": "3DS warning"
            },
            {
                "code": "TRA001",
                "description": "3DS warning"
            }
        ],
        "sessionId": "sessionId",
        "state": "CARD_DATA_COLLECTION",
        "fields": [
            {
                "src": "https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264",
                "id": "cardholderName",
                "type": "text",
                "class": "cardData"
            },
            {
                "src": "https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264",
                "id": "cardholderName",
                "type": "text",
                "class": "cardData"
            }
        ],
        "url": "https:apm_url.it"
    },
    "state": "CARD_DATA_COLLECTION",
    "operation": {
        "paymentLinkId": "234244353",
        "orderId": "btid2384983",
        "warnings": [
            {
                "code": "TRA001",
                "description": "3DS warning"
            },
            {
                "code": "TRA001",
                "description": "3DS warning"
            }
        ],
        "channel": "ECOMMERCE",
        "customerInfo": {
            "mobilePhone": "3280987654",
            "cardHolderName": "Mauro Morandi",
            "homePhone": "391231234567",
            "mobilePhoneCountryCode": 39,
            "shippingAddress": {
                "country": "ITA",
                "province": "BO",
                "city": "Bologna",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "name": "Mario Rossi",
                "postCode": "40124"
            },
            "cardHolderAcctInfo": {
                "chAccDate": "2019-02-11T00:00:00.000+0000",
                "txnActivityYear": 0,
                "chAccPwChangeDate": "2019-02-11T00:00:00.000+0000",
                "paymentAccAgeDate": "2019-02-11T00:00:00.000+0000",
                "provisionAttemptsDay": 0,
                "destinationAddressUsageDate": "2019-02-11T00:00:00.000+0000",
                "chAccChangeDate": "2019-02-11T00:00:00.000+0000",
                "destinationAddressUsageIndicator": "01",
                "chAccChangeIndicator": "01",
                "nbPurchaseAccount": 0,
                "destinationNameIndicator": "01",
                "chAccPwChangeIndicator": "01",
                "paymentAccIndicator": "0",
                "chAccAgeIndicator": "01",
                "suspiciousAccActivity": "01",
                "txnActivityDay": 0
            },
            "workPhone": "391231234567",
            "billingAddress": {
                "country": "ITA",
                "province": "BO",
                "city": "Bologna",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "name": "Mario Rossi",
                "postCode": "40124"
            },
            "cardHolderEmail": "mauro.morandi@nexi.it",
            "merchantRiskIndicator": {
                "deliveryTimeframe": "01",
                "preOrderDate": "2019-02-11T00:00:00.000+0000",
                "reorderItemsIndicator": "01",
                "shipIndicator": "01",
                "giftCardAmount": {
                    "currency": "EUR",
                    "value": "100"
                },
                "deliveryEmail": "john.doe@email.com",
                "giftCardCount": 0,
                "preOrderPurchaseIndicator": "01"
            }
        },
        "operationTime": "2000-01-23T04:56:07.000Z",
        "paymentCircuit": "VISA",
        "omnichannelId": "omnichannelId",
        "operationAmount": "3545",
        "operationId": "3470744",
        "paymentEndToEndId": "e723hedsdew",
        "paymentMethod": "CARD",
        "operationType": "CAPTURE",
        "additionalData": {
            "authorizationCode": "647189",
            "cardCountry": "ITA",
            "threeDS": "FULL_SECURE",
            "schemaTID": "MCS01198U",
            "multiCurrencyConversion": {
                "amount": "2662",
                "currency": "JPY",
                "exchangeRate": "0.007510523"
            }
        },
        "operationCurrency": "EUR",
        "paymentInstrumentInfo": "***6152",
        "cancelledOperationId": "",
        "operationResult": "AUTHORIZED"
    },
    "url": "https://{3DS-Ares-Url}"
}

Get current payment state.

GET /api/v1/build/state

This service the ecommerce platforms to retrieve the current state of a payment flow.

Parameters

Authorizationstringrequired
Authorization
Correlation-Idstring (uuid)required
Mandatory field as format of an UUID v4. The purpose of the field is trace the request among different systems to make easier debug or following a trace.
sessionIdstringrequired
the value of the payment session identifier

Get current payment state.

C#
PHP
Node
Shell

var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/build/state?sessionId=SOME_STRING_VALUE");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("Correlation-Id", "SOME_STRING_VALUE");
IRestResponse response = client.Execute(request);

Responses

200optional
The service returns the state of the payment flow and all the accessory information.
- fieldSetobjectoptional
  - fieldsarrayoptional
    classstringoptionalexample: cardData
    idstringoptionalexample: cardholderName
    srcstringoptionalexample: https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264
    typestringoptionalexample: text
  - securityTokenstringoptionalexample: security token
  - sessionIdstringoptionalexample: sessionId
  - sriHashstringoptional
  - statestringoptional
    It indicates the flow adopted for the ongoing payment. The possible values are:
    
    PAYMENT_METHOD_SELECTION
    
    GDI_VERIFICATION
    
    CARD_DATA_COLLECTION
    
    READY_FOR_PAYMENT
    
    REDIRECTED_TO_EXTERNAL_DOMAIN
    
    PAYMENT_COMPLETE
    
    PAYMENT_INITIALIZATION
    
    CARD_DATA_COLLECTION, GDI_VERIFICATION, PAYMENT_COMPLETE, PAYMENT_METHOD_SELECTION, READY_FOR_PAYMENT, REDIRECTED_TO_EXTERNAL_DOMAIN, PAYMENT_INITIALIZATION
    example: CARD_DATA_COLLECTION
  - urlstringoptionalexample: https:apm_url.it
  - warningsarrayoptional
- operationobjectoptional
  - additionalDataobjectoptional
    Map of additional fields specific to the chosen payment method
  - cancelledOperationIdstringoptional
    Operation id to be undone
  - channelstringoptional
    It 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
    example: ECOMMERCE
  - customerInfoobjectoptional
    This object contains information about the customer. It is strongly recommended to provide as much information as possible in order to facilitate the risk assessment, fraud prevention and the payment processing. It also helps to improve the customer experience by reducing the number of fields to be filled in by the customer and raise the chances to avoid Strong Customer Authentication (SCA) when the transaction is subject to the PSD2 regulation.
    billingAddressobjectoptional
    additionalInfostringoptionalexample: Quinto Piano, Scala B
    citystringoptionalexample: Bologna
    countrystringoptional
    ISO 3166-1 alpha-3
    example: ITA
    namestringoptionalexample: Mario Rossi
    postCodestringoptionalexample: 40124
    provincestringoptionalexample: BO
    streetstringoptionalexample: Piazza Maggiore, 1
    cardHolderAcctInfoobjectoptional
    chAccAgeIndicatorstringoptional
    Length of time that the cardholder has had the account with the 3DS Requestor. Values accepted:
    
    01 = Changed during this transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 day EMVCO: ?
    
    example: 01
    chAccChangeDatestringoptional
    Date 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. ISO 8601 format
    example: 2019-02-11T00:00:00.000+0000
    chAccChangeIndicatorstringoptional
    Length of time since the cardholder's account information was last changed on merchant e-comm platform, including Billing or Shipping address, new payment account, or new user(s) added. Values accepted:
    
    01 = Changed during this transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 day EMVCO: chAccChangeInd
    
    example: 01
    chAccDatestringoptional
    Date when the cardholder opened the account with the merchant's e-commerce platform. ISO 8601 format EMVCO: chAccDate
    example: 2019-02-11T00:00:00.000+0000
    chAccPwChangeDatestringoptional
    Date when the cardholder last changed the password on merchant's e-commerce platform. ISO 8601 format EMVCO: chAccPwChange
    example: 2019-02-11T00:00:00.000+0000
    chAccPwChangeIndicatorstringoptional
    Indicates when the cardholder last changed the password or asked for a password reset on merchant's e-commerce platform.
    
    01 = No change
    
    02 = Changed during this transaction
    
    03 = Less than 30 days
    
    04 = 30−60 days
    
    05 = More than 60 days
    
    example: 01
    destinationAddressUsageDatestringoptional
    Date when the shipping address used for this transaction was first used on merchant's e-commerce platform. ISO 8601 format EMVCO: shipAddressUsage
    example: 2019-02-11T00:00:00.000+0000
    destinationAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used on the merchant's e-commerce platform. Values accepted:
    
    01 = This transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 days EMVCO: shipAddressUsageInd
    
    example: 01
    destinationNameIndicatorstringoptional
    Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. Values accepted:
    
    01 = Account Name identical to shipping Name
    
    02 = Account Name different than shipping Name EMVCO: shipNameIndicator
    
    example: 01
    nbPurchaseAccountinteger (int32)optional
    Number of purchases with this cardholder account during the previous six months. EMVCO: nbPurchaseAccount
    example: 0
    paymentAccAgeDatestringoptional
    Date when the payment method has been added to the cardholder's account on the merchant's e-commerce platform. ISO 8601 format EMVCO: paymentAccAge
    example: 2019-02-11T00:00:00.000+0000
    paymentAccIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the cardholder's account with the merchant's e-commerce platform. Values accepted:
    
    01 = This transaction
    
    02 = Less than 30 days
    
    03 = 30−60 days
    
    04 = More than 60 days EMVCO: paymentAccInd
    
    example: 0
    provisionAttemptsDayinteger (int32)optional
    Number of Add Card attempts in the last 24 hours. EMVCO: provisionAttemptsDay
    example: 0
    suspiciousAccActivitystringoptional
    Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the cardholder account. Values accepted:
    
    01 = No suspicious activity has been observed
    
    02 = Suspicious activity has been observed
    
    example: 01
    txnActivityDayinteger (int32)optional
    Number of transactions (successful and abandoned) for this cardholder account on merchant's e-commerce platform across all payment accounts in the previous 24 hours. EMVCO: txnActivityDay
    example: 0
    txnActivityYearinteger (int32)optional
    Number of transactions (successful and abandoned) for this cardholder account on merchant's e-commerce platform across all payment accounts in the previous year. EMVCO: txnActivityYear
    example: 0
    cardHolderEmailstring (email)optionalexample: mauro.morandi@nexi.it
    cardHolderNamestringoptionalexample: Mauro Morandi
    homePhonestringoptional
    The home phone number provided by the Cardholder.
    example: 391231234567
    merchantRiskIndicatorobjectoptional
    deliveryEmailstringoptional
    For Electronic delivery, the email address to which the merchandise was delivered.
    example: john.doe@email.com
    deliveryTimeframestringoptional
    Indicates the merchandise delivery timeframe. Values accepted:
    
    01 = Electronic Delivery
    
    02 = Same day shipping
    
    03 = Overnight shipping
    
    04 = Two-day or more shipping
    
    example: 01
    giftCardAmountobjectoptional
    currencystringoptional
    For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217. EMVCO: giftCardCurr
    example: EUR
    valuestringoptional
    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
    example: 100
    giftCardCountinteger (int32)optional
    For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
    example: 0
    preOrderDatestringoptional
    For a pre-ordered purchase, the expected date that the merchandise will be available. ISO 8601 format
    example: 2019-02-11T00:00:00.000+0000
    preOrderPurchaseIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    example: 01
    reorderItemsIndicatorstringoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    example: 01
    shipIndicatorstringoptional
    Indicates shipping method chosen for the transaction.
    example: 01
    mobilePhonestringoptionalexample: 3280987654
    mobilePhoneCountryCodestringoptionalexample: 39
    shippingAddressobjectoptional
    additionalInfostringoptionalexample: Quinto Piano, Scala B
    citystringoptionalexample: Bologna
    countrystringoptional
    ISO 3166-1 alpha-3
    example: ITA
    namestringoptionalexample: Mario Rossi
    postCodestringoptionalexample: 40124
    provincestringoptionalexample: BO
    streetstringoptionalexample: Piazza Maggiore, 1
    workPhonestringoptional
    The work phone number provided by the Cardholder.
    example: 391231234567
  - omnichannelIdstringoptional
  - operationAmountstringoptional
    Operation amount in the payment currency
    example: 3545
  - operationCurrencystringoptional
    Payment currency
    example: EUR
  - operationIdstringoptionalexample: 3470744
  - operationResultstringoptional
    Transaction 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
    
    DENIED
    
    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, DENIED, THREEDS_VALIDATED, THREEDS_FAILED, PENDING, CANCELED, VOIDED, REFUNDED, FAILED
    example: AUTHORIZED
  - operationTimestring (date-time)optional
    Operation time in ISO 8601 format
  - operationTypestringoptional
    It indicates the purpose of the request:
    
    AUTHORIZATION - any authorization with explicit capture
    
    CAPTURE - a captured authorization or an implicit captured payment
    
    REFUND - refund of a captured amount
    
    CANCEL - the rollback of an capture, refund.
    
    NOSHOW
    
    INCREMENTAL
    
    DELAY_CHARGE
    
    CARD_VERIFICATION
    
    CARD_CHECK
    
    VOID - reversal of an authorization
    
    AUTHORIZATION, CAPTURE, REFUND, CANCEL, NOSHOW, INCREMENTAL, DELAY_CHARGE, CARD_VERIFICATION, CARD_CHECK, VOID
    example: CAPTURE
  - orderIdstringoptional
    Merchant order id, unique in the merchant domain
    example: btid2384983
  - paymentCircuitstringoptional
    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.
    example: VISA
  - paymentEndToEndIdstringoptional
    It is defined by the circuit to uniquely identify the transaction. Required for circuid reconciliation purposes.
    example: e723hedsdew
  - paymentInstrumentInfostringoptional
    Payment instrument information
    example: ***6152
  - paymentLinkIdstringoptional
    PayByLink id used for correlating this operation with the original link.
    example: 234244353
  - paymentMethodstringoptional
    
    CARD - Any card circuit
    
    APM - Alternative payment method
    
    CARD, APM
    example: CARD
  - warningsarrayoptional
- statestringoptional
  It indicates the flow adopted for the ongoing payment. The possible values are:
  
  PAYMENT_METHOD_SELECTION
  
  GDI_VERIFICATION
  
  CARD_DATA_COLLECTION
  
  READY_FOR_PAYMENT
  
  REDIRECTED_TO_EXTERNAL_DOMAIN
  
  PAYMENT_COMPLETE
  
  PAYMENT_INITIALIZATION
  
  CARD_DATA_COLLECTION, GDI_VERIFICATION, PAYMENT_COMPLETE, PAYMENT_METHOD_SELECTION, READY_FOR_PAYMENT, REDIRECTED_TO_EXTERNAL_DOMAIN, PAYMENT_INITIALIZATION
  example: CARD_DATA_COLLECTION
- urlstringoptionalexample: https://{3DS-Ares-Url}
400Invalid request dataoptional
- timestampstringoptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional
500Internal Server Erroroptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL

{
    "fieldSet": {
        "securityToken": "security token",
        "sriHash": "sriHash",
        "warnings": [
            {
                "code": "TRA001",
                "description": "3DS warning"
            },
            {
                "code": "TRA001",
                "description": "3DS warning"
            }
        ],
        "sessionId": "sessionId",
        "state": "CARD_DATA_COLLECTION",
        "fields": [
            {
                "src": "https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264",
                "id": "cardholderName",
                "type": "text",
                "class": "cardData"
            },
            {
                "src": "https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264",
                "id": "cardholderName",
                "type": "text",
                "class": "cardData"
            }
        ],
        "url": "https:apm_url.it"
    },
    "state": "CARD_DATA_COLLECTION",
    "operation": {
        "paymentLinkId": "234244353",
        "orderId": "btid2384983",
        "warnings": [
            {
                "code": "TRA001",
                "description": "3DS warning"
            },
            {
                "code": "TRA001",
                "description": "3DS warning"
            }
        ],
        "channel": "ECOMMERCE",
        "customerInfo": {
            "mobilePhone": "3280987654",
            "cardHolderName": "Mauro Morandi",
            "homePhone": "391231234567",
            "mobilePhoneCountryCode": 39,
            "shippingAddress": {
                "country": "ITA",
                "province": "BO",
                "city": "Bologna",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "name": "Mario Rossi",
                "postCode": "40124"
            },
            "cardHolderAcctInfo": {
                "chAccDate": "2019-02-11T00:00:00.000+0000",
                "txnActivityYear": 0,
                "chAccPwChangeDate": "2019-02-11T00:00:00.000+0000",
                "paymentAccAgeDate": "2019-02-11T00:00:00.000+0000",
                "provisionAttemptsDay": 0,
                "destinationAddressUsageDate": "2019-02-11T00:00:00.000+0000",
                "chAccChangeDate": "2019-02-11T00:00:00.000+0000",
                "destinationAddressUsageIndicator": "01",
                "chAccChangeIndicator": "01",
                "nbPurchaseAccount": 0,
                "destinationNameIndicator": "01",
                "chAccPwChangeIndicator": "01",
                "paymentAccIndicator": "0",
                "chAccAgeIndicator": "01",
                "suspiciousAccActivity": "01",
                "txnActivityDay": 0
            },
            "workPhone": "391231234567",
            "billingAddress": {
                "country": "ITA",
                "province": "BO",
                "city": "Bologna",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "name": "Mario Rossi",
                "postCode": "40124"
            },
            "cardHolderEmail": "mauro.morandi@nexi.it",
            "merchantRiskIndicator": {
                "deliveryTimeframe": "01",
                "preOrderDate": "2019-02-11T00:00:00.000+0000",
                "reorderItemsIndicator": "01",
                "shipIndicator": "01",
                "giftCardAmount": {
                    "currency": "EUR",
                    "value": "100"
                },
                "deliveryEmail": "john.doe@email.com",
                "giftCardCount": 0,
                "preOrderPurchaseIndicator": "01"
            }
        },
        "operationTime": "2000-01-23T04:56:07.000Z",
        "paymentCircuit": "VISA",
        "omnichannelId": "omnichannelId",
        "operationAmount": "3545",
        "operationId": "3470744",
        "paymentEndToEndId": "e723hedsdew",
        "paymentMethod": "CARD",
        "operationType": "CAPTURE",
        "additionalData": {
            "authorizationCode": "647189",
            "cardCountry": "ITA",
            "threeDS": "FULL_SECURE",
            "schemaTID": "MCS01198U",
            "multiCurrencyConversion": {
                "amount": "2662",
                "currency": "JPY",
                "exchangeRate": "0.007510523"
            }
        },
        "operationCurrency": "EUR",
        "paymentInstrumentInfo": "***6152",
        "cancelledOperationId": "",
        "operationResult": "AUTHORIZED"
    },
    "url": "https://{3DS-Ares-Url}"
}

Get card characteristics.

GET /api/v1/build/cardData

It provides PCI-free non sensitive information about the payment card entered by the user along the current payment session.

Parameters

Authorizationstringrequired
Authorization
Correlation-Idstring (uuid)required
Mandatory field as format of an UUID v4. The purpose of the field is trace the request among different systems to make easier debug or following a trace.
sessionIdstringrequired
the value of the payment session identifier

Get card characteristics.

C#
PHP
Node
Shell

var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/build/cardData?sessionId=SOME_STRING_VALUE");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("Correlation-Id", "SOME_STRING_VALUE");
IRestResponse response = client.Execute(request);

Responses

200optional
In case of success, the service returns the data collected for the given card.
- binstringoptional
  Bank Identification Number. It corresponds to the first 6 digits of the payment card number.
  example: 123456
- circuitstringoptional
  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.
  example: VISA
- expiringDatestringoptional
  Expiration date of the card, in the format MM/YY.
  example: 0423
- lastFourDigitsstringoptional
  Last 4 digits of the payment card number.
  example: 1234
400Invalid request dataoptional
- timestampstringoptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional
500Internal Server Erroroptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL

{
    "circuit": "VISA",
    "lastFourDigits": "1234",
    "bin": "123456",
    "expiringDate": "0423"
}

Confirm a payment.

POST /api/v1/build/confirm_payment

This service shall be invoked by the ecommerce platforms to finalize the payment. It is limited to the flow version 2.

Parameters

Authorizationstringrequired
Authorization
Correlation-Idstring (uuid)required
Mandatory field as format of an UUID v4. The purpose of the field is trace the request among different systems to make easier debug or following a trace.

Confirm a payment.

C#
PHP
Node
Shell

var client = new RestClient("https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/build/confirm_payment");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("Correlation-Id", "SOME_STRING_VALUE");
request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request body

amountstringoptional
This value allows changing the initial amount specified during the post orders/build. It shall be expressed in the lower unit required by the involved currency. I.e.: 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals).
example: 3545
sessionIdstringoptional
it must be set with the sessionId value returned by the post orders/build
example: 052211e8/+54cc/4e0a

Request body

{
    "amount": "3545",
    "sessionId": "052211e8/+54cc/4e0a"
}

Responses

200OKoptional
201Createdoptional
400Invalid request dataoptional
- timestampstringoptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL
401Unauthorizedoptional
403Forbiddenoptional
404Not Foundoptional
500Internal Server Erroroptional
- errorsarrayoptional
  - codestringoptionalexample: GW0001
  - descriptionstringoptionalexample: Invalid merchant URL

{}