Token Payment Service

Token Payment Service is a functionality that allows Customer to order the one-time payment transactions with card payment token obtained from Google Pay™.

Introduction
Overview
Onboarding
Integration with Token Payment Service

Introduction

Token Payment Service is a functionality that allows Customer to order the one-time payment transactions with card payment token obtained from Google Pay™. This technology provides a backend to backend oriented solution to which Customer should be integrated. By using this solution, Customer's users can easily pay for their purchases using their cards stored in Google Pay™. After selecting the Google Pay as the payment option, the Customer gets encrypted card payment token from Google Pay™. Card payment token is encrypted on the Google Pay™ side with Fenige's public Key. The Customer has to provide this encrypted token to Fenige by using Token Payment Service soution and Fenige handle entire transaction process by his own. The Customer must be registered in Google Pay™ as a merchant to be able to get a card payment token and have an account with some Acquirer with which Fenige will connect when ordering a transaction.

How to connect with us?

Fenige provides Token Payment Service API which is implemented according to the REST model. This API offers methods that allow to order transaction using payment token obtained from Google Pay™ and authenticate the cardholder using 3D Secure protocol. Fenige team actively supports Customer with integration. More informations about Token Payment Service API can be found here.

Overview

This document provides high level description of functionalities offered by Token Payment Service. Token Payment Service supports e-commerce transactions by card payment token received from Google Pay™ thus eliminating the need to use real card details during transactions. As a registered PSP in Google Pay™, Fenige will decrypt the card payment token and perform the transaction on behalf of the Customer.

If the Customer requires the settlement of the transaction by a new Acquirer – to which Fenige is not integrated – there will be required new integration between Fenige and the new Acquirer. The specification of the new Acquirer should be provided by the Customer.

Abbreviation

This section shortly describes abbreviations and acronyms used in the document.

Abbreviation	Description
ACQ	Acquiring Institution / Acquirer
ACS	Access Control Server
OS	Operative System
PCI DSS	Payment Card Industry Data Security Standard
PAN	Permanent Account Number
CVC	Card Verification Code
3DS	3-D Secure
PSP	Payment Service Provider

Terminology

This section explains a meaning of key terms and concepts used in this document.

Name	Description
Customer/Merchant	Institution which uses Fenige products. This institution decides which solution should be used depending on the business requirements and how transaction should be processed.
User	End-User which uses Customer application and pays for Customer's goods using Google Pay™ solution. This is the root of the entity tree. User is an owner of the card stored in Google Pay™ system.
Card Payment Token	Card Payment Token is an entity created by Google Pay™ and returned to the Customer. This token is created when the Customera application user selects the card he wants to pay with Google Pay. Card Token Payment is encrypted and does not contain valid card details. This token is decrypted on the Fenige side and then Fenige orders the payment to the Customer's Acquirer.
Authorization Method	The way of the authentication of the card transaction. Fenige supports followed authorization methods: `PAN_ONLY` and `CRYPTOGRAM_3DS` if Customer's country belongs to the European Union. Authorization method is always provided in the Google Pay™ encrypted payload as `authMethod` parameter.
Gateway Id	Phrase/value that identifies a given Payment Service Provider in the Google Pay™ system. The Merchant provides gateway Id to Google Pay™ to obtain a card payment token. By provided gateway Id, Google Pay™ encrypts the card payment token with the appropriate public key. Fenige is defined by a gateway Id with the value `Fenige`
Gateway Merchant Id	Unique Customer identifier assigned by Fenige during the onboarding process. This identifier is in the form of a `UUID`. Fenige understands and uses this to verify that the message was for the Customer that made the request. Customer passes it to Google Pay™. More information about the Gateway Merchant Id can be found in Google Pay™ documentation.
Payment Service Provider	Payment Service Provider is an entity that helps Merchants transfer sensitive data to Acquirer during the transaction. Payment Service Provider should be PCI DSS compilent. In the Token Payment Service solution, Fenige has the role of PSP.
TerminalUuid	Acquirer settles payments made through terminals in the online store or at the point of sale. Required to process transactions and 3DS via Fenige system.
Card Network	This is the type of card that allows you to make payments using a card payment token. Fenige allows to use `MASTERCARD`, `VISA`cards.
PAN	It is 7-16 digits of the credit / debit card number. These digits contain the Permanent Account Number assigned by the bank to uniquely identify the account holder. It is necessary to provide it when User wants to pay with a card for purchases on the internet.
CVC	It is a type of security code protecting against fraud in remote payments. Card Verification Code is necessary to provide it when User wants to pay with a card for purchases on the internet.
Expiration Date	It is a date of the card validity ending and contains two values – month/year. Card will be valid to the last day of the month of the year showed on it. It is necessary to provide it when User wants to pay with a card for purchases on the internet.
3DS	3-D Secure is a method of authorization of transaction made without the physical use of a card, used by payment organization. The 3DS process in the Merchant Paytool solution is performed internally in the Fenige system.
PCI DSS	It is a security standard used in environments where the data of payment cardholders is processed. The standard covers meticulous data processing control and protection of users against violations.

Token Payment Service key components

Token Payment Service is a solution that has been created to provide the functionality that allows Customer to process payments using Google Pay™. An additional assumption was that the payment process should be performed outside the Customer's system, which frees him from the need to handle with sensitive data or the transaction itself. The Customer only receives information that the transaction was successful or not. This section provides introduction to technologies which are supported by Token Payment Service. High level architecture diagram is presented to show the place and usage of the each entity in the solution.

Component	Description
Token Payment Service API	Component stores the configuration data of a given Customer such Merchant Name or Merchant Id and also communicates with various Acquirers, collect transaction data and statuses. This component also triggers notifications to the Customer and the end user (depending on the Customer requirements) about successful or unsuccessful transaction.
Notification Service	Component responsible for sending information to the Customer about the transaction status. It is also responsible for sending email to the end user about the transaction. Notification Service is triggered by Token Payment Service API.

Allowed card networks

Listed below are the types of cards supported in transactions using the Token Payment Service and Google Pay™ solution:

Card type

MASTERCARD

VISA

Implementation models

Fenige provides REST API implementation model in Token Payment Service Solution. In this model Customer has his own application which should be integrated with Token Payment Service API. Fenige provides all necessary backend methods. Customer is responsible for integrate provided methods with his own application. Technical information about the integration can be found here. Below diagram shows high level architecture of the solution:

Onboarding

Register in Fenige

The onboarding process takes place mainly on Fenige side. However, in order to perform onboarding, the Customer must provide some information needed to correctly configure account in Token Payment Service. Configuration includes following information:

Customer name	Basically, it's the name of the Customer's company, his online shop and so on.
Postback URL	This is the address to which information will be send to the Customer about the transaction made by a given user. This parameter is not required if the Customer does not want to receive notifications regarding the transaction. For more information about Postback URL please check Use cases chapter.
Notification to the user	It is a flag that defines whether e-mail notifications was sent to the User. Such e-mail contains the transaction status, transaction execution date, transaction identifier, date and amount. The Customer decides whether Fenige will send such e-mails or not.
MerchantUuid	This ID is represending Customer in Acquirer's system. Required to process transactions and 3DS via Fenige system.

After creating an account for the Customer, Fenige provides necessary data to the Customer. This data is required to use the Token Payment Service API. Such data includes:

Basic Authorization	Authorization data for Customer which allow to use the solution. Authorization data are the login and password of the Customer account in the Fenige system. Basic authorization should be provided as Authorization header with Base64 encoded value of login and password.
Gateway Id	This is a constant and unique value that defines the PSP in the Google Pay™ system. When making a call to get a card token, the Customer transfers this value to Google Pay™ in the request. Fenige is defined by Gateway Id with `Fenige` value.
Gateway Merchant Id	This is a unique Customer identifier assigned by Fenige during the onboarding process. This identifier is in the form of a `UUID`. Fenige understands and uses this to verify that the message was for the Customer that made the request. Customer passes it to Google Pay™. More information about the Gateway Merchant Id can be found in Google Pay™ documentation.

Authorization data on STAGING and PROD environments differ in password. The login and the gateway Id is the same on both environments.

Register in Google Pay™

To use the Token Payment Service solution, it is necessary for the Customer to be registered as merchant in the Google Pay™ system. An unregistered Customer will not be able to get the card payment token from Google Pay. To register merchant account in Google Pay™ visit Google Pay for Business quick start guide or contact Google Pay™ support. After completing registration as a merchant, the Customer will receive an access to Google Pay™ documentation enabling technical integration.

Register as Web Merchant

Google Pay Web integration checklist	A checklist presenting the Google Pay integration requirements that must be met by the Customer integrating web application
Google Pay Web developer documentation	Technical documentation describing web integration with the Google Pay solution
Google Pay Web Brand Guidelines	Branding requirements that must be met by the Customer's web application to be able to use the Google Pay solution

Register as Mobile Merchant

Mobile integration model is work in progress... The solution will be available for mobile merchants soon. This will allow Customers with mobile applications to integrate to the Token Payment Service Solution.

Google Pay Android integration checklist	A checklist presenting the Google Pay integration requirements that must be met by the Customer integrating mobile application
Google Pay Android developer documentation	Technical documentation describing mobile integration with the Google Pay solution
Google Pay Android brand guidelines	Branding requirements that must be met by the Customer's mobile application to be able to use the Google Pay solution

Integration with Token Payment Service

Overview

This chapter provides the instruction of the integration with the solution of the Token Payment Service using Google Pay™ card payment token. Prior to using this solution the Customer have to proceed onboarding process in Fenige and to have an registered merchant account in Google Pay. To register a merchant in Google Pay, please contact Google Pay™ Support.

Google Pay™ provides a Google Pay Web integration checklist that will help the Customer with integration step by step. The documentation is available after whitelisting in Google Pay™ system. The whitelisting process is performed by Google Pay™ during the Customer's merchant account registration process.

In addition, Google Pay™ provides Google Pay Web Brand Guidelines that presents branding requirements for web merchants registered in Google Pay™. These requirements must be met by the Customer so that he can allow his payers to pay via the Google Pay™ solution.

To create an account in Fenige system follow the instruction in the Onboarding chapter.

Integration

Fenige Token Payment Service provides a method for e-commerce payments using a card payment token. The card payment token is generated by Google Pay™ and returned to the Customer in the form of an encrypted payload. Google Pay™ encrypts the card payment token with Fenige's public key. The Customer transfers the received payload to Fenige, which in turn is decrypted on the Fenige side and then the payment is ordered. To facilitate merchant integration with the solution provided by Google Pay™ and to understand the process of making requests for a card payment token, Google Pay™ provides Google Pay Web developer documentation.

Google Pay Web developer documentation is only available after whitelisting. The whitelisting process is performed by Google Pay™ during the merchant account registration process.

All merchants must adhere to the Google Pay APIs Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.

SDK

Initialization - Add the following script to your website:

<script type="module" src="https://paytool-dev.fenige.pl/paytool.js"></script>

The type="module" attribute is currently required, because the SDK utilizes modern JavaScript code splitting syntax.

Example html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta name="viewport"
                    content="width=device-width,
                        initial-scale=1.0" />
    <script
      type="module"
      src="https://paytool-dev.fenige.pl/paytool.js"
                
    ></script>
  </head>
  <body>
    <paytool-button></paytool-button>
    <script>
      window.addEventListener('DOMContentLoaded',
                    function () {
        var paytool = document.querySelector('paytool-button');
        paytool.data = {
          apiKey: 'YOUR_API_KEY',
          amount: 9999,
          currencyCode: 'CURRENCY_CODE',
          description: 'TRANSACTION_DESCRIPTION'
        };
      });
                
    </script>
                
  </body>
</html>

Endpoints

Endpoints chapter contains description of endpoints for Token Payment Service methods. Fenige provides two implementation environments: test - BETA and production - PROD. Below table presents the addresses of each of the domains:

Methods in API

Token Payment

POST/client/payment/token/google-pay

The method allows e-commerce payment using a token obtained from Google Pay™. The method also accepts additional parameters such as transaction item ID or payer details.

Request body:

POST /client/payment/token/google-pay HTTP/1.1
Content-Length: 1720
Content-Type: application/json
Host: merchant.upaid.pl
{
  "amount": 1000,
  "transactionId": "08ea8e28-0aad-45eb-8368-f15bdadd5eba",
  "description": "SUCCESS",
  "browserIp": "41.11.22.1",
  "currency": "PLN",
  "deposit": false,
  "sender": {
    "firstName": "firstName",
    "lastName": "lastName",
    "email": "emaiL@email.pl"
  },
  "token": {
    "signature": "MEUCIQDx0PjhU6041nIbz6mBagbDUGE9DF8NtLAq1hKyQih9sQIgd5V3ROT5uVXZuYt0i/1RREc1mNnkg0VlnstseI4oN4w\u003d",
    "intermediateSigningKey": {
      "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUj6saq5iwo1JIkLti6dvNFdNJygVoFZUhiKzGwsC2ebD5v58RutdePd2GxMvx8nGuF3YjVKjwk28R5r2hyTqJQ\\u003d\\u003d\",\"keyExpiration\":\"1667554292000\"}",
      "signatures": [
        "MEYCIQDRc5NBd/GC5loetxwL3idIMMsR2vpXicoqlvsPEFIirwIhAMOHvdrHt/sMt5PxS4o0SYO3sCOb6hT9a2t+PMBcM/u7"
      ]
    },
    "protocolVersion": "ECv2",
    "signedMessage": "{\"encryptedMessage\":\"Tlkj3N2bApMJ2x2IUgsoTvqYLDuUNpzWmSQbgAIjG2kr+1buPgh70qeKkZkfZRCvJMV0py1R0RzUyqJujZIqX9tIxPyBX8yQ/bZNOR5AJXDzSLgR2+WuBIa0KRySCwNmzV4U2RVkUdZiIVr8/JL/o7NH768A6rl/GvhqYfpsFtprATFgsFulDS/dnAhJTS4tykk34wZXnyCb94YHmI5rbN8FFkC/BygPVIKgGt5YWngxRZO1yBSSbcyWb3w+WXIOaPT6XZdOqDOtOo5GgzNmYKGIdep+b0+hJsreZCG1yPw3o/QS3nDdem40jrUv/apyY1xPSjib3mjXW0e/hnkL3K43n79po8qmswdPkyOdRh5D10ZElxXRZvI25/WqpsN/jyaeKitDlsOnIGHjiM36S1a4FrTCwmmiV8XDyVzsamW0asemTeJ9nBbEOylF4dz0symXEWJ45l0SSvPEJqc1HMuPljw1EVAA/MF1O8HBVv7iJndyXS8c2wH5eLLCIP3CkT3qb4TjfhhGbhU5JKclYOxHzvIDUaFYljjzlCyvR+PGwaGq0bzmjtki17t2MKNLtXioQBv9rb2WHZF+tPcA3TJLfo8vijZRzFJQb9JPzDQzCJ7N2ORfD/LAJWMkeCcvLwuBWPZd3keI\",\"ephemeralPublicKey\":\"BH6BiZF1XFldmO+8EH13KABs4ttulS68cYHg9HRgYCbV6mdGIa4E2YQuDtsn98MtSQoJ6wA8LtIpa5L6FF9WyCM\\u003d\",\"tag\":\"1BcFY5B7BuSa3cVwRQx58fdHvwWO8zd0BDrOzva6O14\\u003d\"}"
  }
}

Request headers:
Accept-Language	PL	Not required	Response message language
Content-Type	application/json	Required	Content type of the request

Request headers:

Type

Value

Constraints

Description

Accept-Language

Not required

Response message language

Content-Type

application/json

Required

Content type of the request

Request fields
`deposit`	`Boolean`	Optional	By setting this flag, the Customer decides whether the funds will be immediately taken from the payer's account. Default value for this flag is `false`
`browserIp`	`String`	Optional	Browser ip
`amount`	`Number`	Not null	Transaction amount (in pennies)
`transacionId`	`String`	Not empty	Unique transacion id
`currency`	`String`	Not empty	Transaction currency
`description`	`String`	Not empty	Simple description of transaction
`sender`	`Object`	Not null	Sender details
`sender.firstName`	`String`	Not empty	Sender first name
`sender.lastName`	`String`	Not empty	Sender last name
`sender.email`	`String`	Optional	Sender email
`token`	`Object`	Not null	Token obtained from Google
`token.signature`	`String`	Not null	Token signature
`token.intermediateSigningKey`	`Object`	Not null	Token intermediate signing key
`token.intermediateSigningKey.signedKey`	`String`	Not null	Signed key
`token.intermediateSigningKey.signatures[]`	`Array`	Not null	Token signatures
`token.protocolVersion`	`String`	Not null	Protocol version
`token.signedMessage`	`String`	Not null	Signed message

Request fields

Name

Type

Description

deposit

Boolean

Optional

By setting this flag, the Customer decides whether the funds will be immediately taken from the payer's account. Default value for this flag is false

browserIp

String

Optional

Browser ip

amount

Number

Not null

Transaction amount (in pennies)

transacionId

String

Not empty

Unique transacion id

currency

String

Not empty

Transaction currency

description

String

Not empty

Simple description of transaction

sender

Object

Not null

Sender details

sender.firstName

String

Not empty

Sender first name

sender.lastName

String

Not empty

Sender last name

sender.email

String

Optional

Sender email

token

Object

Not null

Token obtained from Google

token.signature

String

Not null

Token signature

token.intermediateSigningKey

Object

Not null

Token intermediate signing key

token.intermediateSigningKey.signedKey

String

Not null

Signed key

token.intermediateSigningKey.signatures[]

Array

Not null

Token signatures

token.protocolVersion

String

Not null

Protocol version

token.signedMessage

String

Not null

Signed message

Response body:

HTTP/1.1 200 OK
Content-Length: 209
Content-Type: application/json;charset=UTF-8
{
  "transactionId" : "08ea8e28-0aad-45eb-8368-f15bdadd5eba",
  "itemId" : "f34e8330-99fe-4ca4-8ee7-3628c989a6e2",
  "status" : "APPROVED",
  "externalTransactionId" : "49a91f00-26b4-49a2-9c77-ed37646ddf64"
}

Response fields
`transactionId`	`String`	This is the id of the entire transaction process.
`itemId`	`String`	Merchant’s unique id of transaction. Ensures the idempotency of the transaction.
`status`	`String`	Transaction status
`externalTransactionId`	`String`	External transaction id

Response fields

Name

Description

transactionId

String

This is the id of the entire transaction process.

itemId

String

Merchant’s unique id of transaction. Ensures the idempotency of the transaction.

status

String

Transaction status

externalTransactionId

String

External transaction id

tokenPayment method cURL example:

$ curl 'https://paytool.fenige.pl/client/payment/token/google-pay' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "amount": 1000,
  "transactionId": "08ea8e28-0aad-45eb-8368-f15bdadd5eba",
  "description": "SUCCESS",
  "browserIp": "41.11.22.1",
  "currency": "PLN",
  "deposit": false,
  "sender": {
    "firstName": "firstName",
    "lastName": "lastName",
    "email": "emaiL@email.pl"
  },
  "token": {
    "signature": "MEUCIQDx0PjhU6041nIbz6mBagbDUGE9DF8NtLAq1hKyQih9sQIgd5V3ROT5uVXZuYt0i/1RREc1mNnkg0VlnstseI4oN4w\u003d",
    "intermediateSigningKey": {
      "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUj6saq5iwo1JIkLti6dvNFdNJygVoFZUhiKzGwsC2ebD5v58RutdePd2GxMvx8nGuF3YjVKjwk28R5r2hyTqJQ\\u003d\\u003d\",\"keyExpiration\":\"1667554292000\"}",
      "signatures": [
        "MEYCIQDRc5NBd/GC5loetxwL3idIMMsR2vpXicoqlvsPEFIirwIhAMOHvdrHt/sMt5PxS4o0SYO3sCOb6hT9a2t+PMBcM/u7"
      ]
    },
    "protocolVersion": "ECv2",
    "signedMessage": "{\"encryptedMessage\":\"Tlkj3N2bApMJ2x2IUgsoTvqYLDuUNpzWmSQbgAIjG2kr+1buPgh70qeKkZkfZRCvJMV0py1R0RzUyqJujZIqX9tIxPyBX8yQ/bZNOR5AJXDzSLgR2+WuBIa0KRySCwNmzV4U2RVkUdZiIVr8/JL/o7NH768A6rl/GvhqYfpsFtprATFgsFulDS/dnAhJTS4tykk34wZXnyCb94YHmI5rbN8FFkC/BygPVIKgGt5YWngxRZO1yBSSbcyWb3w+WXIOaPT6XZdOqDOtOo5GgzNmYKGIdep+b0+hJsreZCG1yPw3o/QS3nDdem40jrUv/apyY1xPSjib3mjXW0e/hnkL3K43n79po8qmswdPkyOdRh5D10ZElxXRZvI25/WqpsN/jyaeKitDlsOnIGHjiM36S1a4FrTCwmmiV8XDyVzsamW0asemTeJ9nBbEOylF4dz0symXEWJ45l0SSvPEJqc1HMuPljw1EVAA/MF1O8HBVv7iJndyXS8c2wH5eLLCIP3CkT3qb4TjfhhGbhU5JKclYOxHzvIDUaFYljjzlCyvR+PGwaGq0bzmjtki17t2MKNLtXioQBv9rb2WHZF+tPcA3TJLfo8vijZRzFJQb9JPzDQzCJ7N2ORfD/LAJWMkeCcvLwuBWPZd3keI\",\"ephemeralPublicKey\":\"BH6BiZF1XFldmO+8EH13KABs4ttulS68cYHg9HRgYCbV6mdGIa4E2YQuDtsn98MtSQoJ6wA8LtIpa5L6FF9WyCM\\u003d\",\"tag\":\"1BcFY5B7BuSa3cVwRQx58fdHvwWO8zd0BDrOzva6O14\\u003d\"}"
  }
}'

Google Pay™ does not provide information such as firstName or lastName. Parameters like this, however, are required to make a payment using the tokenPayment method. They must be provided by the Customer together with the card payment token. Basicly the Customer must collect and provide a card payment token from Google Pay and the name of the user of his application.

Transaction statuses

The table below presents all possible transaction statuses:

Name	Description
`PENDING`	Transaction waiting for execution.
`FAILED`	Transaction failed.
`AUTHORIZED`	Entire amount of the order was locked.
`DEPOSITED`	Bank account was charged.

Name

Description

PENDING

Transaction waiting for execution.

FAILED

Transaction failed.

AUTHORIZED

Entire amount of the order was locked.

DEPOSITED

Bank account was charged.

Get transaction details

GET[base-url]/transactions/details/${transactionId}

This method is optional and does not affect the process of the transaction itself. Nevertheless, Fenige recommends using this method. In case of any problem with the connection, it allows the Customer to know the current status of a given transaction. This method is secured by Customer's account credentials (basic authorization). Customer's account is created by Fenige during the onboarding process.

Request headers:
Authorization:	Basic bG9naW46cGFzc3dvcmQ=	Required	Customer's account credentials
Content-Type	application/json	Required	Content type of the request

Request headers:

Type

Value

Constraints

Description

Authorization:

Basic bG9naW46cGFzc3dvcmQ=

Required

Customer's account credentials

Content-Type

application/json

Required

Content type of the request

Response body:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 245
{
  "creationDate" : "2024-01-13T14:11:54.422+01:00",
  "transactionId" : "ee58ef03-d6ed-4a07-8885-d050c439ec6c",
  "transactionState" : "SUCCESS",
  "amount" : 100,
  "currencyCode" : "PLN",
  "description" : "description",
  "currency" : "PLN",
  "sender" : {
        "firstName": "User",
        "lastName": "TestUser",
        "email": "test@fenige.pl",
        "phone": "500500500"
        }
}

Response fields
`transactionId`	`String`	Identifier of transaction.
`amount`	`Number`	Transaction amount in pennies
`currency`	`String`	Transaction currency
`description`	`String`	Transaction description
`status`	`String`	One of the possible transaction statuses
`threeDsMode`	`String`	ThreeDS process mode which informs about

Response fields

Name

Description

transactionId

String

Identifier of transaction.

amount

Number

Transaction amount in pennies

currency

String

Transaction currency

description

String

Transaction description

status

String

One of the possible transaction statuses

threeDsMode

String

ThreeDS process mode which informs about

getTransactionDetails method cURL example:

$ curl --location --request GET 'https://paytool-api-dev.fenige.pl/transactions/details/b578a149-af32-4ebf-r35b-213b7c4f3caf' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ZmVuaWdlOmtyenlrYWN6'

Possible errors

This chapter presents all the errors that can be obtained using the Token Payment Service solution. The chapter lists each of the error statuses with a description, as well as an example JSON body with a given error.

Error examples in JSON format

HTTP Status	Error Message
400 - Bad Request	STATUS: E8000 - Returned when request is incorrect, required fields are missing or the values are not valid.
401 UNAUTHORIZED	STATUS: E8002 - Returned when there was a problem with authorization to your PSP.
403 FORBIDDEN	STATUS: E8001 - Returned when server understood the request but refuses to authorizeToken it.
404 NOT FOUND	STATUS: E0122 - Returned when merchant is not existing. STATUS: E0132 - Returned when terminal is not existing. STATUS: E0135 - Returned when terminal for merchant not exist or all of them are inactive. STATUS: E0137 - Returned when there is not terminal marked as default
422 UNPROCESSABLE ENTITY	STATUS: E0150 - Returned when transaction is rejected. STATUS: E0151 - Returned when transaction is rejected, because currency is not supported. STATUS: E0152 - Returned when transaction is rejected, because issuer is not supported. STATUS: E0156 - Returned where terminal used for process transaction do not support 3DS STATUS: E0157 - Returned where card used for process transaction do not support 3DS STATUS: E01583 - Returned when transaction is rejected, because outside3ds object was not provided in transaction request STATUS: E0159 - Returned when transaction is rejected, because restricted transaction amount has occurred STATUS: E01596 - Returned when transaction is rejected, because terminal has blocked transaction with card issued in restricted country STATUS: E01597 - Transaction rejected, 3DS version of terminal are not compatible with 3DS version defined in request. Please contact the sales department STATUS: E01598 - Transaction rejected, ECI value is not available for card provider STATUS: E01600 - Transaction rejected, 3DS 2.X flow invoked for other card number than specified in the request STATUS: E01601 - Returned when transaction is rejected, because terminal is blocked for provider STATUS: E01602 - Transaction rejected, geographic scope is not permitted for this transaction STATUS: E01607 - Transaction rejected, internal server error during authorization request generation STATUS: E0200 - Returned when transaction is rejected, because card is blocked in Fenige System STATUS: E0201 - Returned when transaction is rejected, because BIN is blocked in Fenige System STATUS: E0202 - Returned when transaction is rejected, because Terminal is blocked in Fenige System STATUS: E0203 - Returned when transaction is rejected, because Token is blocked in Fenige System STATUS: E0204 - Returned when transaction is rejected, because user’s personal data was found on AML (sanctions) list STATUS: E0205 - Returned when transaction is rejected, because Bank is blocked in Fenige System STATUS: E0206 - Returned when transaction is rejected, because to many reject transactions and card is blocked STATUS: E0207 - Returned when transaction is rejected, bacause to many attempts declined and card is blocked STATUS: E0208 - Transaction rejected, second transaction with merchant advice code 03 or 21 within 30 days STATUS: E0209 - Returned when sender or receiver name contains fraudulent phrase STATUS: E0210 - Returned when sender has suspicious name STATUS: E0211 - Returned when transaction is rejected, because card country is blocked in Fenige System STATUS: E11000 - Returned when transaction processing time set by terminal was exceeded
500 INTERNAL SERVER ERROR	STATUS: E0153 - Returned when transaction is declined, by problem with MIP connection. STATUS: E01599 - Transaction declined, processing timeout. STATUS: E0142 - Returned when commission configuration is not added for terminal. STATUS: E0190 - Returned when currency rate is invalid. STATUS: E9000 - Returned when reason is unknown. STATUS: E9008 - Returned when mpi received 3ds initialize failed.
503 SERVICE UNAVAILABLE	STATUS: E9001 - Returned when is error acquirer connection. STATUS: E9002 - Returned when is error mpi connection.

HTTP Status

Error Message

400 - Bad Request

STATUS: E8000 - Returned when request is incorrect, required fields are missing or the values are not valid.

401 UNAUTHORIZED

STATUS: E8002 - Returned when there was a problem with authorization to your PSP.

403 FORBIDDEN

STATUS: E8001 - Returned when server understood the request but refuses to authorizeToken it.

404 NOT FOUND

STATUS: E0122 - Returned when merchant is not existing.
STATUS: E0132 - Returned when terminal is not existing.
STATUS: E0135 - Returned when terminal for merchant not exist or all of them are inactive.
STATUS: E0137 - Returned when there is not terminal marked as default

422 UNPROCESSABLE ENTITY

STATUS: E0150 - Returned when transaction is rejected.
STATUS: E0151 - Returned when transaction is rejected, because currency is not supported.
STATUS: E0152 - Returned when transaction is rejected, because issuer is not supported.
STATUS: E0156 - Returned where terminal used for process transaction do not support 3DS
STATUS: E0157 - Returned where card used for process transaction do not support 3DS
STATUS: E01583 - Returned when transaction is rejected, because outside3ds object was not provided in transaction request
STATUS: E0159 - Returned when transaction is rejected, because restricted transaction amount has occurred
STATUS: E01596 - Returned when transaction is rejected, because terminal has blocked transaction with card issued in restricted country
STATUS: E01597 - Transaction rejected, 3DS version of terminal are not compatible with 3DS version defined in request. Please contact the sales department
STATUS: E01598 - Transaction rejected, ECI value is not available for card provider
STATUS: E01600 - Transaction rejected, 3DS 2.X flow invoked for other card number than specified in the request
STATUS: E01601 - Returned when transaction is rejected, because terminal is blocked for provider
STATUS: E01602 - Transaction rejected, geographic scope is not permitted for this transaction
STATUS: E01607 - Transaction rejected, internal server error during authorization request generation
STATUS: E0200 - Returned when transaction is rejected, because card is blocked in Fenige System
STATUS: E0201 - Returned when transaction is rejected, because BIN is blocked in Fenige System
STATUS: E0202 - Returned when transaction is rejected, because Terminal is blocked in Fenige System
STATUS: E0203 - Returned when transaction is rejected, because Token is blocked in Fenige System
STATUS: E0204 - Returned when transaction is rejected, because user’s personal data was found on AML (sanctions) list
STATUS: E0205 - Returned when transaction is rejected, because Bank is blocked in Fenige System
STATUS: E0206 - Returned when transaction is rejected, because to many reject transactions and card is blocked
STATUS: E0207 - Returned when transaction is rejected, bacause to many attempts declined and card is blocked
STATUS: E0208 - Transaction rejected, second transaction with merchant advice code 03 or 21 within 30 days
STATUS: E0209 - Returned when sender or receiver name contains fraudulent phrase
STATUS: E0210 - Returned when sender has suspicious name
STATUS: E0211 - Returned when transaction is rejected, because card country is blocked in Fenige System
STATUS: E11000 - Returned when transaction processing time set by terminal was exceeded

500 INTERNAL SERVER ERROR

STATUS: E0153 - Returned when transaction is declined, by problem with MIP connection.
STATUS: E01599 - Transaction declined, processing timeout.
STATUS: E0142 - Returned when commission configuration is not added for terminal.
STATUS: E0190 - Returned when currency rate is invalid.
STATUS: E9000 - Returned when reason is unknown.
STATUS: E9008 - Returned when mpi received 3ds initialize failed.

503 SERVICE UNAVAILABLE

STATUS: E9001 - Returned when is error acquirer connection.
STATUS: E9002 - Returned when is error mpi connection.

Response status: HTTP/1.1 400 Bad Request

HTTP/1.1 400 Bad Request
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 24 Aug 2023 13:57:59 GMT
Connection: close
Content-Length: 575
{
  "errors" : {
    "expiryDate" : [ "invalid card format expiration date", "must not be null", "must not be blank" ],
    "firstName" : [ "must not be blank", "must not be null" ],
    "lastName" : [ "must not be null", "must not be blank" ],
    "amount" : [ "must not be null" ],
    "merchantUuid" : [ "must not be null" ],
    "terminalLocation" : [ "must not be null" ],
    "requestUuid" : [ "must not be null" ],
    "currency" : [ "must not be null" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "ef829624-7b42-44ab-b558-9308da7da03b"
}

Response status: HTTP/1.1 401 Unauthorized

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Realm"
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 141
Date: Thu, 24 Aug 2023 13:57:59 GMT
{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "7521956d-f77c-44ad-8ed7-a50cc2ca48d4"
}

Response status: HTTP/1.1 403 Forbidden

HTTP/1.1 403 Forbidden
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 135
Date: Thu, 24 Aug 2023 13:58:23 GMT
{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "c8bc5659-f6e1-4a73-98ff-e11b8e80c598"
}

Response status: HTTP/1.1 404 Not Found

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 146
{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "3930d2b4-662d-4c85-820a-6af270a0bde8"
}

Response status: HTTP/1.1 422 Unprocessable Entity

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: 251
{
  "requestUuid" : "c1137dd5-e05c-43fd-9be7-e2c8b675f82e",
  "transactionStatus" : "REJECTED",
  "status" : "E0150",
  "message" : "Transaction rejected",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "c3f73ce5-06db-4e07-aadb-310001702864"
}

Response status: HTTP/1.1 500 Internal Server Error

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 280
{
  "requestUuid" : "c12fb58e-0ec7-4f58-93cd-88cc029686cb",
  "transactionStatus" : "PENDING",
  "status" : "E0153",
  "message" : "Transaction declined, problem with MIP connection",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "fb174931-2eec-4837-be36-7c9c41e3a2b7"
}

Response status: HTTP/1.1 503 Service Unavailable

HTTP/1.1 503 Service Unavailable
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 24 Aug 2023 13:58:51 GMT
Connection: close
Content-Length: 161
{
  "status" : "E9001",
  "message" : "Error acquirer connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "00b20d46-ee72-4ed6-8d98-a734fc095373"
}