Skip to content
XPayCEE

    XPay Build APIs

    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

    • X-API-KEYstringrequired
    • 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.

    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("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("x-plugin-name", "SOME_STRING_VALUE");
request.AddHeader("X-API-KEY", "REPLACE_KEY_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

    • X-API-KEYstringrequired
    • 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.

    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("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("X-API-KEY", "REPLACE_KEY_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
    {
    "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

    • X-API-KEYstringrequired
    • 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.

    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("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("X-API-KEY", "REPLACE_KEY_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

    • X-API-KEYstringrequired
    • 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.

    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("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("X-API-KEY", "REPLACE_KEY_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

    • X-API-KEYstringrequired
    • 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.

    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("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("X-API-KEY", "REPLACE_KEY_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

    • X-API-KEYstringrequired
    • 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.

    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("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("X-API-KEY", "REPLACE_KEY_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
      {}