Nexi POS REST API

• created_at string - required

  Time when the transaction was created.

  • Format: date-time
  • Length: 20 characters
  • Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
• external_id string - required

  Client provided identifier for the transaction, see External id.

  • Length: 1-63 characters
  • Pattern: ^[\x21-\x7E]{1,63}$
• id string - required

  Internal identifier for the transaction, see Id.

  • Length: 1-63 characters
  • Pattern: ^[0-9a-zA-Z-]{1,63}$
• state string - required

  State of the transaction, see Transaction flow.

  Value	Description
  AWAITING_CONFIRM	Needs client to send 'confirm' message to continue processing
  AWAITING_CONTINUE	Needs client to send 'continue' message to continue processing
  PROCESSING	Transaction is being processed
  CONFIRMED	Transaction has been confirmed as successful or failed
  COMMITTED	Transaction result has been committed and cannot be changed

• terminal_id string - required

  Identifier of the terminal that processed the transaction, see Terminal id.

  • Length: 1-63 characters
  • Pattern: ^[0-9a-zA-Z-]{1,63}$
• type string - required

  Transaction type.

  Value	Description
  ACCOUNT_CHECK	Account check transaction to check if card is valid
  PURCHASE	Purchase transaction to charge customer for goods
  REFUND	Refund transaction to return money to customer
  UNKNOWN	Transaction type not known, or not representable in this enumeration

• updated_at string - required

  Time when the transaction was last updated.

  • Format: date-time
  • Length: 20 characters
  • Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
• authorized_amount integer - optional

  Amount that was authorized by the acquirer, see Authorized amount.

  • Range: 0-999999999999
• captured_amount integer - optional

  Amount that was captured from customer account, see Captured amount.

  • Range: 0-999999999999
• cashback_amount integer - optional

  Amount of cashback given to the customer, see Cashback amount.

  • Range: 0-999999999999
• confirmed_at string - optional

  Time when the transaction was confirmed. Missing if the transaction hasn’t been confirmed yet.

  • Format: date-time
  • Length: 20 characters
  • Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
• currency string - optional

  Currency of the transaction, see Currency.

  • Length: 3 characters
  • Pattern: ^[A-Z]{3}$
• customer_identity object - optional

  Customer identity information. If the customer was identified somehow by their payment instrument, this information is available in the transaction details. There can be multiple ways utilized at the same time for a single transaction, so this object will contain data for the methods that were used for this transaction.

  • computop object - optional

    Computop specific customer identity information.

    • card_token string - optional

      Computop specific card token. This is a unique identifier for the card that can be used to identify the card in future transactions.

      • Length: 16 characters
      • Pattern: ^[0-9]{16}$
  • par object - optional

    Payment account reference (PAR) as provided by the payment instrument. This is a unique identifier for the card that can be used to identify the card in future transactions.

    • par_value string - optional

      Payment account reference (PAR) as read from the payment instrument.

      • Length: 29 characters
      • Pattern: ^[0-9A-Z]{29}$
• customer_not_present boolean - optional

  Indicator that the transaction was done without the customer being present at the terminal.

• dcc object - optional

  Details of a currency conversion, see DCC. This element only present if the transaction was processed in a different currency for the customer than the one in currency field.

  • customer_amount integer - optional

    Amount that the customer paid in their own currency. This amount is in the currency listed in customer_currency.

    • Range: 0-999999999999
  • customer_currency string - optional

    Currency that customer paid in, see Currency.

    • Length: 3 characters
    • Pattern: ^[A-Z]{3}$
  • exchange_rate integer - optional

    Exchange rate that was used for the DCC transaction. The value is expressed as an integer with exactly four decimal places. That means that a value of 10000 is equal to 1:1 exchange rate.

    • Minimum: 0
  • exchange_rate_date string - optional

    Date when the exchange rate was obtained from the provider.

    • Format: date
    • Length: 1-10 characters
    • Pattern: ^\d{4}-\d{2}-\d{2}$
  • exchange_rate_provider string - optional

    Exchange rate provider that was used for the transaction.

    • Length: 1-63 characters
    • Pattern: ^[\x20-\x7E]{1,63}$
  • markup_fee integer - optional

    Mark-up fee that was charged for the DCC transaction. The value is expressed as an integer in one hundredth of percents, so 100 means a mark-up of 1 %.

    • Range: 0-10000
  • provider string - optional

    DCC provider that was used for the transaction.

    • Length: 1-63 characters
    • Pattern: ^[\x20-\x7E]{1,63}$
• metadata object - optional

  Client provided transaction metadata, see Metadata.

• original_purchase_external_id string - optional

  Original purchase transaction’s external_id, see External id. Only relevant when type is REFUND.

  • Length: 1-63 characters
  • Pattern: ^[\x21-\x7E]{1,63}$
• original_purchase_id string - optional

  Original purchase transaction’s id, see Id. Only relevant when type is REFUND.

  • Length: 1-63 characters
  • Pattern: ^[0-9a-zA-Z-]{1,63}$
• original_purchase_terminal_id string - optional

  Original purchase transaction’s terminal_id, see Terminal id. Only relevant when type is REFUND.

  • Length: 1-63 characters
  • Pattern: ^[0-9a-zA-Z-]{1,63}$
• payment_method_details - optional

  Payment method specific information

  • One of the objects below will be in the payload

    • When payment_method is CARD
      • payment_method string - required

        CARD

      • acquirer_reference string - optional

        Transaction reference number in format YYMMDDNNNNNN. It is set by the terminal at the time the transaction is created and guaranteed to be unique within the terminal. It is transmitted to the acquirer during transaction processing.

        • Length: 12 characters
        • Pattern: ^[0-9]{12}$
      • acquirer_terminal_id string - optional

        Terminal identifier that is used towards the acquirer. It often matches the transaction terminal id, but some acquirers have special rules and limitations that require it to be different.

        • Length: 8 characters
        • Pattern: ^[0-9A-Z]{8}$
      • acquirer_timestamp string - optional

        Local transaction time in format YYMMDDHHMMSS. It is set by the terminal at the time the transaction is created. It is transmitted to the acquirer during transaction processing.

        • Length: 12 characters
        • Pattern: ^[0-9]{12}$
      • application_identifier string - optional

        Application identifier (AID) of the selected card application.

        • Length: 10-32 characters
        • Pattern: ^[0-9A-F]{10,32}$
      • application_name string - optional

        Name of the selected card application.

        • Length: 1-16 characters
        • Pattern: ^[\x20-\x7E]{1,16}$
      • authorization_code string - optional

        Authorization code for the transaction, if received from the acquirer.

        • Length: 6 characters
        • Pattern: ^[0-9A-Z]{6}$
      • authorization_response_code string - optional

        Response code from the acquirer. This is not the same as the result_code of the transaction. This is a code that is used by the acquirer to indicate the result of the authorization. Generally 00 means success.

        • Length: 2 characters
        • Pattern: ^[0-9A-Z]{2}$
      • card_entry_mode string - optional

        Card entry mode is the way the card was read by the terminal. This does not directly tell the form factor of the card, as contactless entry mode is used for anything that is read wirelessly, including mobile phones and smartwatches.

        Value	Description
        CONTACT_EMV	Card was inserted into the terminal and the chip was read
        CONTACTLESS_EMV	Card or phone was tapped on the terminal and the chip was read wirelessly
        MAGNETIC_STRIPE	Card was swiped on the terminal and the magnetic stripe was read
        MANUAL	Card number was typed in manually on the terminal

      • card_number_customer string - optional

        Card primary account number that can be shown to the customer. Generally only the last 4 digits are shown, rest are masked.

        • Length: 13-19 characters
        • Pattern: ^[0-9*]{13,19}$
      • card_number_merchant string - optional

        Card primary account number that can be shown to the merchant. Generally first 6 and last 4 digits are shown, rest are masked.

        • Length: 13-19 characters
        • Pattern: ^[0-9*]{13,19}$
      • card_scheme string - optional

        Card scheme is the payment network the card is provided by. This is not necessarily the card brand which is printed on top of the card. Scheme will never be UNKNOWN for a successful transaction.

        AMEX

        BANKAXEPT

        DANKORT

        DINERS_CLUB

        GIROCARD

        JCB

        MASTERCARD

        UNIONPAY

        VISA

        UNKNOWN

      • card_sequence_number string - optional

        Sequence number for multiple cards with the same card number. Required to be printed on receipts.

        • Length: 2 characters
        • Pattern: ^[0-9]{2}$
      • cardholder_verification string - optional

        Cardholder verification method (CVM) is the way the cardholder was verified to be the owner of the card.

        Value	Description
        NONE	Cardholder has not been verified
        SIGNATURE	Cardholder has given their signature
        PIN	Cardholder typed in a PIN code
        PIN_AND_SIGNATURE	Both `SIGNATURE` and `PIN` were used
        CONSUMER_DEVICE	Cardholder used a consumer device, such as a phone, for verification

• receipt_details_customer string - optional

  Customer receipt details, see Receipt. This is the information that must be printed on the customer receipt.

  • Length: 1-1023 characters
  • Pattern: ^([\x20-\x7E]{0,32}\n){1,31}$
• receipt_details_merchant string - optional

  Merchant receipt details, see Receipt. This is the information that must be printed on the merchant receipt.

  • Length: 1-1023 characters
  • Pattern: ^([\x20-\x7E]{0,32}\n){1,31}$
• reference string - optional

  Unique reference number for the transaction. This is a number that should be printed on the receipt. It can be typed into the terminal to reference the purchase for a refund. All “-” characters are just for visual separation and will not be required on input.

  • Length: 1-63 characters
  • Pattern: ^[0-9-]{1,63}$
• refundable_amount integer - optional

  The total sum of refunds that can still be accepted for this transaction, see Refundable amount.

  • Range: 0-999999999999
• requested_amount integer - optional

  Amount that was requested for the transaction, see Requested amount.

  • Range: 0-999999999999
• result_code string - optional

  Result of the transaction, see Results and errors.

  • Length: 1-255 characters
  • Pattern: ^[0-9A-Z_]{1,255}$
• result_description string - optional

  English language transaction result description for logs and administrative interfaces. It should not be shown to customer and might be too technical to be useful for a cashier.

  • Length: 1-255 characters
  • Pattern: ^[\x20-\x7E]{1,255}$
• surcharge_amount integer - optional

  Amount of surcharge that was added to the transaction, see Surcharge amount.

  • Range: 0-999999999999
• tip_amount integer - optional

  Amount of tip that was added to the transaction, see Tip amount.

  • Range: 0-999999999999
• total_amount integer - optional

  Current total amount for transaction, see Total amount

  • Range: 0-999999999999

Request body

• currency string - required

  Currency of the transaction, see Currency.

  • Length: 3 characters
  • Pattern: ^[A-Z]{3}$
• external_id string - required

  Client provided identifier for the purchase transaction, see External id.

  • Length: 1-63 characters
  • Pattern: ^[\x21-\x7E]{1,63}$
• requested_amount integer - required

  Amount to request from the customer, see Requested amount.

  • Range: 0-999999999999
• terminal_id string - required

  Identifier of the terminal that should perform the purchase, see Terminal id.

  • Length: 1-63 characters
  • Pattern: ^[0-9a-zA-Z-]{1,63}$
• cashback_amount integer - optional

  Amount of cashback that should be given to the customer, see Cashback amount.

  • Range: 0-999999999999
• metadata object - optional

  Client provided transaction metadata, see Metadata.

• options object - optional

  Modify the behaviour of the server side request and transaction handling.

  • on_customer_identified - optional

    Action to be performed when the customer has been identified by their payment instrument but before the actual payment is done, see Pausing a transaction. The field customer_identity is present in the transaction when this action runs, if the customer was identified.

    • One of the objects below will be in the payload

      • Pause
        • pause boolean - optional

          Whether to pause the transaction. If true, the transaction will be paused at this point and the client will need to call /transactions/continue to resume the transaction processing.

  • wait_seconds number - optional

    How many seconds the server should wait for transaction state to change before responding, see Long polling. Will respond immediately if set to 0 or if transaction state is not PROCESSING.

    • Range: 0-180

Request body

• currency string - required

  Currency of the transaction, see Currency.

  • Length: 3 characters
  • Pattern: ^[A-Z]{3}$
• external_id string - required

  Client provided identifier for the refund transaction, see External id.

  • Length: 1-63 characters
  • Pattern: ^[\x21-\x7E]{1,63}$
• requested_amount integer - required

  Amount that should be refunded from the customer, see Requested amount.

  • Range: 0-999999999999
• terminal_id string - required

  Identifier of the terminal that should perform the refund, see Terminal id.

  • Length: 1-63 characters
  • Pattern: ^[0-9a-zA-Z-]{1,63}$
• customer_not_present boolean - optional

  Whether the customer is present at the terminal during the refund transaction. If the customer is present and the refund refers to an original purchase, they will be asked to present the same payment instrument that was used for the original purchase, and the refund will be authorized.

• metadata object - optional

  Client provided transaction metadata, see Metadata.

• options object - optional

  Modify the behaviour of the server side request and transaction handling.

  • on_customer_identified - optional

    Action to be performed when the customer has been identified by their payment instrument but before the actual payment is done, see Pausing a transaction. The field customer_identity is present in the transaction when this action runs, if the customer was identified.

    • One of the objects below will be in the payload

      • Pause
        • pause boolean - optional

          Whether to pause the transaction. If true, the transaction will be paused at this point and the client will need to call /transactions/continue to resume the transaction processing.

  • wait_seconds number - optional

    How many seconds the server should wait for transaction state to change before responding, see Long polling. Will respond immediately if set to 0 or if transaction state is not PROCESSING.

    • Range: 0-180
• original_purchase_external_id string - optional

  Original purchase transaction’s external_id, see External id.

  • Length: 1-63 characters
  • Pattern: ^[\x21-\x7E]{1,63}$
• original_purchase_terminal_id string - optional

  Original purchase transaction’s terminal_id, see Terminal id.

  • Length: 1-63 characters
  • Pattern: ^[0-9a-zA-Z-]{1,63}$

Request body

• external_id string - required

  Client provided identifier for the transaction that should be confirmed, see External id.

  • Length: 1-63 characters
  • Pattern: ^[\x21-\x7E]{1,63}$
• result_code string - required

  Error code, see Results and errors.

  • Length: 1-255 characters
  • Pattern: ^[0-9A-Z_]{1,255}$
• terminal_id string - required

  Identifier of the terminal of the transaction that should be confirmed, see Terminal id.

  • Length: 1-63 characters
  • Pattern: ^[0-9a-zA-Z-]{1,63}$
• captured_amount integer - optional

  Amount to capture from customer account, see Captured amount.

  • Range: 0-999999999999
• metadata object - optional

  Client provided transaction metadata, see Metadata. Will be merged with any metadata transaction already has.

• result_description string - optional

  Human readable description, only relevant if result_code is not SUCCESS.

  • Length: 1-255 characters
  • Pattern: ^[\x20-\x7E]{1,255}$

Request body

• external_id string - required

  External id of the transaction, see External id.

  • Length: 1-63 characters
  • Pattern: ^[\x21-\x7E]{1,63}$
• terminal_id string - required

  Terminal id of the transaction, see Terminal id.

  • Length: 1-63 characters
  • Pattern: ^[0-9a-zA-Z-]{1,63}$
• options object - optional

  Modify the behaviour of the server side request handling.

  • wait_seconds number - optional

    How many seconds the server should wait for transaction state to change before responding, see Long polling. Will respond immediately if set to 0 or if transaction state is not PROCESSING.

    • Range: 0-180

Request body

• external_id string - required

  Client provided identifier for the transaction that should be continued, see External id.

  • Length: 1-63 characters
  • Pattern: ^[\x21-\x7E]{1,63}$
• terminal_id string - required

  Identifier of the terminal of the transaction that should be continued, see Terminal id.

  • Length: 1-63 characters
  • Pattern: ^[0-9a-zA-Z-]{1,63}$
• metadata object - optional

  Client provided transaction metadata, see Metadata. Will be merged with any metadata transaction already has.

• options object - optional

  Modify the behaviour of the server side request handling.

  • wait_seconds number - optional

    How many seconds the server should wait for transaction state to change before responding, see Long polling. Will respond immediately if set to 0 or if transaction state is not PROCESSING.

    • Range: 0-180
• requested_amount integer - optional

  Override the requested amount of the transaction, changing the amount that the transaction is going to be processed with.

  • Range: 0-999999999999