1. Changelog

Version Date Description

1.0

2018-10-01

First release of documentation

1.1

2018-11-13

Partial clearing method describe added

1.2

2018-12-18

Documentation update

1.3

2019-01-16

Fields validation changes

1.4

2019-02-04

Optional IP address field added in transaction request body

1.5

2019-03-20

Fields validation changes

1.6

2019-04-25

Endpoint (base url) changed to https://ecom-staging.fenige.pl

1.7

2019-05-10

Methods descriptions modified and statuses description improved

1.8

2019-07-18

Clearing amount field has been added to the details method

1.9

2019-09-10

A flow diagrams updated

2.0

2019-09-23

New payment method with token description added

2.1

2019-09-26

Monitoring statuses added
2.6.8. Monitoring

2.2

2019-11-15

Monitoring status added (E0203)
2.6.8. Monitoring

2.3

2019-11-26

Monitoring status added (E0204)
2.6.8. Monitoring

2.4

2020-01-30

New transaction status, amount limit per terminal (E0158)
2.6.4. Payment

2.5

2020-01-31

Information about certification process added

2.6

2020-02-18

Deleted refund status (S0012, S0013), changed refund status (E0184) and added new status (E0186) to refund. Changed response status for refund (2.6.7)
2.6.7. Refund

2.7

2020-02-24

Outside 3DS transactions documentation added
5.2. Payment - request

2.8

2020-02-28

3DS Verification method
6. 3DS 1.0 verification methods - the change will be available on production from 12.03.2020.

2.9

2020-03-02

ERROR_MPI_CONNECTION status is replaced by the following statuses:

Error mpi - 3ds initialize failed

Error mpi connection

- the change will be available on production from 12.03.2020.

3.0

2020-03-04

Removed commission and merchantCommission from transaction details response body.

3.1

2020-03-05

Monitoring status added (E0205)
2.6.8. Monitoring
5.5. Payment
5.7. Token payment

3.2

2020-03-26

Release API with Credential on File (CoF) functionality
5.8.1 Cof payment - initial transaction
5.8.4 Cof payment - subsequent transaction

3.3

2020-04-27

Release API with Recurring Payments functionality
5.9.1 Recurring Payment - initial transaction
5.9.4 Recurring Payment - subsequent transaction

3.4

2020-05-13

New reversal status (S0005, S0006) and changed response
5.11.2 Reversal - response

3.5

2020-06-05

Documentation updated. Change value and description about field "md" in Initialize and Finalize methods:
6.2. Initialize
6.3. Finalize

3.6

2020-06-08

New status E0163 added
2.6.6. Reversal

3.7

2020-06-10

Documentation updated. Currency Rate method will be deprecated on 30.09.2020 and will be replaced by a new version of the Currency Rate method. 5.2. Currency Rate

3.8

2020-06-18

Response status E0141 replaced with E0190 when currency rate cannot be found

3.9

2020-06-30

Update Mastercard statuses table

4.0

2020-07-01

New method "Card Provider" added

4.1

2020-07-09

Add 3DS 2.X

4.2

2020-07-23

Add new response status E0187 during refund processing to notify that chargeback was reported for transaction

4.3

2020-08-28

Add new response status E01595 - Returned when terminal MCC configuration is QUASI-CASH.

4.4

2020-09-1

Add new method MO/TO payment 5.6. MO/TO Payment

4.5

2020-09-1

Add new method Currency for card 5.3. Currency for card

4.6

2020-09-16

Add new fields in details: authorizeRRN, authorizeStan, reversalRRN, reversalStan, arn

4.7

2020-09-23

Add new VISA response code value 80

4.8

2020-10-26

New transaction status added (E01596) for transactions performed using terminal restricted card country + 5.5. Payment + 5.6. MO/TO payment + 5.7. Token payment + 5.7. CoF payment + 5.7. Recurring payment

4.9

2020-11-06

Add Installment Payment API methods 5.10. Installment Payment

4.10

2020-11-06

Change in outside 3DS, authentication status required Y or A value

4.11

2020-11-17

3DS version enforcement configuration

4.12

2020-11-20

Cards management methods added 5. Cards

5.0

2020-12-06

DataCenter card transaction functionality release for Payment API methods + 6.4. Payment + 6.5. MO/TO payment + 6.6. Token payment + 6.7. CoF payment + 6.8. Recurring payment + 6.9. Installment Payment

5.1

2020-12-30

Update for 3DS 2.X

5.2

2021-01-01

New status E8004 for Clearing and Reversal method. Locks the method call until the ongoing task for a given Request Uuid is completed.

5.3

2021-01-15

Update for 3DS 1.0 Add merchantUuid for verify and initialize method. Optional fields to get merchant configuration.

5.4

2021-01-18

New field 'terminalUrl' in Ecommerce Payment requests added. The field is optional now, but it is recommended to include it in your request body. From 2021-05-03 the 'terminalUrl' and 'addressIp' fields will be required.

5.5

2021-01-20

Internal functionality to restrict access to specific method for PSP.

5.6

2021-03-10

Remove status E01595 and allow processing of all types of payment transactions using quasi-cash terminals

5.7

2021-04-01

Introduction of a new webhook functionality. Now it is possible to handle information about transaction status without polling API. 9. Webhooks

5.8

2021-04-09

Monitoring status added (E0206) 2.7.9. Monitoring

5.9

2021-04-09

Added card Id support from Datacenter for methods with 3ds 2.x/3ds 1.0

6.0

2021-04-19

New error status: E01600 in response for 3DS 2.X payment method

6.1

2021-05-05

An implementation of CODE_65 transaction rejection logic for MASTERCARD and VISA. More details can be found here: 6.4 Payments

6.2

2021-05-18

New filed on 3DS 1.0 Initialize method to process Token PAN transaction

6.3

2021-06-09

Added Payment API field 'transactionRef' for determining merchant additional transaction identifier

2. Introduction

Fenige e-commerce API service allows to easily and safely perform operations realated to e-commerce. You can authorize payments and show details about completed transactions. Also you can make reversals, clearings and refunds.

Transaction process:

1. Fenige registers the PSP in his system.

2. PSP creates a Merchant and Terminals.

3. Fenige activates the Merchant and Terminals (by default inactive).

4. The Partner can use all available methods in the API.

2.1. Certification

In order to access the Moneysend API, you must successfully pass the certification process in our dedicated application. The application is available at https://certification.fenige.pl/
The new partner will receive login data from the Fenige employee, who is responsible for introducing new customers. After a positive result, the user receives access to the production environment. Be adviced that the entire process takes place in a staging environment.

2.2. Transaction types

In Ecommerce Service we have two various transaction types

Transaction type Description

Domestic

This transaction type can be execute only if card’s country of sender, receiver and merchant are all the same.

Crossborder

This transaction type is executed if one or more conditions of Domestic Transaction type is not fulfill.

ecommerce flow
Figure 1. E-commerce flow

2.3. Endpoints

Environment Endpoint (base url)

Staging

https://ecom-staging.fenige.pl

2.4. HTTP verbs

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update specific resource

DELETE

Used to delete a resource

2.5. Language

If you want to select your language, add Accept-Language header to request JSON and set its value to, for example, pl, en, cs or sk. In case of a successful transaction for the send money method you will receive a email confirmation in the language which you set.

Accept-Language

en

2.6. General methods

All api methods require the delivery of appropriate headers.

List of methods headers used in Fenige REST API:

Key Value Validation Description

Content-Type

application/json

Required

Used to indicate the media type of the resource

Authorization

Basic cHNwbmFtZTpwYXNzd29yZA==

Required

Used to resolve PSP context of user. Basic Auth from PSP data (PSP name and password). Consist of keyword Basic and string obtained from Base64 coding method for PSP name and password parameter

2.7. HTTP status codes

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

202 ACCEPTED

The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.

203 NON-AUTHORITATIVE INFORMATION

The request with 3ds has been registered for processing. Check status in a while.

400 BAD REQUEST

The request was malformed. The response body will include an error providing further information

404 NOT FOUND

The requested resource did not exist

500 INTERNAL SERVER ERROR

Message occur when an unexpected condition was encountered

2.7.1. Merchant

Table 1. Response status for Merchant
Code Messages HTTP Code HTTP STATUS

S0000

SUCCESS

200

OK

E0121

Adding Merchant to database was failed, Merchant already exists

409

CONFLICT

E0122

Merchant not exists

404

NOT FOUND

E0123

List of Merchant is empty

200

OK

E0124

Get List of Merchant was failed

500

INTERNAL SERVER ERROR

E0125

List of Config Merchant is empty.

404

NOT FOUND

2.7.2. Terminal

Table 2. Response status for Terminal
Code Messages HTTP Code HTTP STATUS

S0000

SUCCESS

200

OK

E0130

Adding Terminal to database was failed, Terminal with the given name already exists

409

CONFLICT

E0131

Adding Terminal to database was failed, Terminal already exists

409

CONFLICT

E0132

Terminal not exists

404

NOT FOUND

E0133

List of Terminal is empty

200

OK

E0135

Terminals for merchant not exists

404

NOT FOUND

E0136

Merchant not exists

404

NOT FOUND

E0137

Default terminal not exist

422

UNPROCESSABLE ENTITY

E0138

Can’t deactivate default terminal if is not last

422

UNPROCESSABLE ENTITY

E0139

Adding terminal to database failed. Currency not supported by PSP

409

CONFLICT

E0140

Update Terminal failed, You can only enable 3ds

409

CONFLICT

2.7.3. Currency rate

Table 3. Response status for Currency rate method
Code Messages HTTP Code HTTP STATUS

E0190

Failed to get currency rates

500

INTERNAL_SERVER_ERROR

2.7.4. Currency for card

Table 4. Response status for Currency for card method
Code Messages HTTP Code HTTP STATUS

E0400

Failed to get currency for card

500

INTERNAL_SERVER_ERROR

E0401

Issuer card is not supported

422

UNPROCESSABLE_ENTITY

2.7.5. Payment

Table 5. Response status for Payment
Code Messages HTTP Code HTTP STATUS

S0000

SUCCESS

200

OK

S0001

SUCCESS

204

NO CONTENT

S0002

Success transaction

200

OK

S0003

Transaction declined, check response code for reason

200

OK

S0004

PENDING

202

ACCEPTED

E0150

Transaction rejected

422

UNPROCESSABLE ENTITY

E0151

Transaction rejected, currency not supported

422

UNPROCESSABLE ENTITY

E0152

Transaction rejected, issuer not supported

422

UNPROCESSABLE ENTITY

E0153

Transaction declined, problem with MIP connection

500

INTERNAL SERVER ERROR

E0154

Failed to fetch transaction details

500

INTERNAL SERVER ERROR

E0155

Transaction not exist

404

NOT FOUND

E0156

Transaction rejected, terminal not supported 3ds

422

UNPROCESSABLE ENTITY

E0157

Transaction rejected, card not supported 3ds

422

UNPROCESSABLE ENTITY

E0158

Transaction rejected, maximum transaction amount limit exceeded

422

UNPROCESSABLE ENTITY

E01580

Transaction rejected. Data center card is expired.

422

UNPROCESSABLE ENTITY

E01581

Transaction rejected. Not found Card Authentication (3DS 2.X)

422

UNPROCESSABLE ENTITY

E01582

Transaction rejected. Card Authentication not match to transaction type (3DS 2.X)

422

UNPROCESSABLE ENTITY

E01590

Transaction rejected, cof card not found in db

422

UNPROCESSABLE ENTITY

E01591

Transaction rejected, initial cof transaction not approved

422

UNPROCESSABLE ENTITY

E01592

Transaction rejected, recurring card not found in db

422

UNPROCESSABLE ENTITY

E01593

Transaction rejected, initial recurring transaction not approved

422

UNPROCESSABLE ENTITY

E01594

Transaction rejected, transactionXId parameter had registered for another transaction

422

UNPROCESSABLE ENTITY

E01596

Transaction rejected, terminal blocks transactions with card issued in given card country

422

UNPROCESSABLE ENTITY

E01597

Transaction rejected, 3DS version of terminal are not compatible with 3DS version defined in request

422

UNPROCESSABLE ENTITY

E01598

Transaction rejected, ECI value is not available for card provider

422

UNPROCESSABLE ENTITY

E01599

Transaction declined, processing timeout

500

INTERNAL_SERVER_ERROR

E01600

Transaction declined, 3DS 2.X flow invoked for other card number than specified in the request

422

UNPROCESSABLE ENTITY

E05000

Installment Payment initial not found

500

INTERNAL SERVER ERROR

E05001

Installment Payment already confirmed

500

INTERNAL SERVER ERROR

E05002

Installment Payment already cancelleded

500

INTERNAL SERVER ERROR

E05003

Installment Payment already pay in full

500

INTERNAL SERVER ERROR

E05004

Installment Payment not confirmed in required time

500

INTERNAL SERVER ERROR

E05005

Installment Payment Initial was failed

500

INTERNAL SERVER ERROR

E05006

Installment Payment could not find valid installment plan for requested uuid

500

INTERNAL SERVER ERROR

E05007

Installment Payment Option not allowed for transaction

500

INTERNAL SERVER ERROR

E05008

Installment Payment missing plan uuid

500

INTERNAL SERVER ERROR

E05009

Installment Payment missing request number of installments

500

INTERNAL SERVER ERROR

E05010

Installment Payment requested number of installments is outside of allowed range

500

INTERNAL SERVER ERROR

E05011

Installment Payment operation not allowed, installment type allows ISSUER_FINANCED installments

500

INTERNAL SERVER ERROR

E05014

Installment Payment outside 3ds request is required for terminal

500

INTERNAL SERVER ERROR

E05015

Installment Payment unsupported card provider VISA

500

INTERNAL SERVER ERROR

2.7.6. Clearing

Table 6. Response status for Clearing
Code Messages HTTP Code HTTP STATUS

E0170

Clearing of the payment is procesing

422

UNPROCESSABLE ENTITY

E0171

Can’t clear payment

422

UNPROCESSABLE ENTITY

E0172

Can’t clear payment, the time is over

422

UNPROCESSABLE ENTITY

E0173

Payment is automatically cleared

422

UNPROCESSABLE ENTITY

E0174

Payment is already cleared

422

UNPROCESSABLE ENTITY

E0175

Can’t clear payment, clearing amount is to low

503

UNPROCESSABLE ENTITY

E0176

Can’t clear payment, clearing amount is to high

503

UNPROCESSABLE ENTITY

2.7.7. Reversal

Table 7. Response status for Reversal
Code Messages HTTP Code HTTP STATUS

S0005

Success reverse transaction

200

OK

S0006

Reverse transaction declined, check response code for reason

200

OK

E0160

Reversal of the payment is procesing

422

UNPROCESSABLE ENTITY

E0161

Can’t reversal payment

422

UNPROCESSABLE ENTITY

E0162

Payment is already reversed

422

UNPROCESSABLE ENTITY

E0163

Payment is already refunded

422

UNPROCESSABLE ENTITY

E05012

Installment Payment reverse not allowed

500

INTERNAL SERVER ERROR

2.7.8. Refund

Table 8. Response status for Refund
Code Messages HTTP Code HTTP STATUS

E0180

Refund rejected, no MC/VISA response

500

INTERNAL SERVER ERROR

E0181

Refund rejected by MC/VISA

500

INTERNAL SERVER ERROR

E0182

Refund transaction amount to low

400

BAD REQUEST

E0183

Refund transaction amount to high

400

BAD REQUEST

E0184

Transaction is refunded

422

UNPROCESSABLE ENTITY

E0185

Transaction not cleared, can’t refund

422

UNPROCESSABLE ENTITY

E0186

Refund is already processing

422

UNPROCESSABLE ENTITY

E0187

Transaction is chargeback reported

422

UNPROCESSABLE ENTITY

E05013

Installment Payment refund not allowed

500

INTERNAL SERVER ERROR

2.7.9. Monitoring

Table 9. Monitoring response status
Code Messages HTTP Code HTTP STATUS

E0200

Transaction rejected, card is blocked

422

UNPROCESSABLE ENTITY

E0201

Transaction rejected, bin is blocked

422

UNPROCESSABLE ENTITY

E0202

Transaction rejected, terminal is blocked

422

UNPROCESSABLE ENTITY

E0203

Transaction rejected, token is blocked

422

UNPROCESSABLE ENTITY

E0204

Transaction rejected, user is on aml list

422

UNPROCESSABLE ENTITY

E0205

Transaction rejected, bank is blocked

422

UNPROCESSABLE ENTITY

E0206

Transaction rejected, to many reject transactions and card is blocked

422

UNPROCESSABLE ENTITY

2.7.10. 3DS 2.X

Table 10. Response status for 3DS 2.X
Code Messages HTTP Code HTTP STATUS

S0000

SUCCESS

200

OK

E0300

Error mpi V2 - failed internal

500

INTERNAL_SERVER_ERROR

E0301

Three DS Method Data mismatch

422

UNPROCESSABLE_ENTITY

E0302

Error on parsing Three DS Method Data

422

UNPROCESSABLE_ENTITY

E0303

Card number not Enrolled in 3DS v2

422

UNPROCESSABLE_ENTITY

E0304

Invalid card authentication id

422

UNPROCESSABLE_ENTITY

E0305

Issuer card is not supported

422

UNPROCESSABLE_ENTITY

E0306

Invalid card number

422

UNPROCESSABLE_ENTITY

E0307

Card Authentication not found

404

NOT_FOUND

E0132

Terminal not exists

404

NOT_FOUND

E0309

Protocol version is not supported

422

UNPROCESSABLE_ENTITY

E0310

Invalid Three DS Method Data

422

UNPROCESSABLE_ENTITY

2.7.11. Global

Table 11. Global response status
Code Messages HTTP Code HTTP STATUS

E8000

Bad Request

400

BAD REQUEST

E8001

Forbidden

403

FORBIDDEN

E8002

Unauthorized

401

UNAUTHORIZED

E8003

Scale of amount is different than the scale of currency

422

UNPROCESSABLE ENTITY

E8004

Some operation for this requestUuid is processing

422

UNPROCESSABLE ENTITY

2.7.12. Fatal Errors

Table 12. Fatal errors response status
Code Messages HTTP Code HTTP STATUS

E9000

Domain error

500

INTERNAL SERVER ERROR

E9001

Error acquirer connection

503

SERVICE UNAVAILABLE

E9002

Error mpi connection

503

SERVICE_UNAVAILABLE

E9003

Error monitoring connection

503

SERVICE_UNAVAILABLE

E9007

Error mpi - 3ds verify failed

500

INTERNAL_SERVER_ERROR

E9008

Error mpi - 3ds initialize failed

500

INTERNAL_SERVER_ERROR

E9009

Error mpi - 3ds finalize failed

500

INTERNAL_SERVER_ERROR

E9010

Error data center connection

503

SERVICE_UNAVAILABLE

2.8. Mastercard/VISA statuses

Table 13. Statuses in accordance with ISO-8583
Status code Usage

CODE_00

Approved or completed successfully

CODE_01

Refer to card issuer

CODE_02

Refer to card issuer, special condition

CODE_03

Invalid merchant or service provider

CODE_04

Capture card/Pick up card (no fraud)

CODE_05

Do not honor

CODE_06

General error

CODE_07

Pickup card, special condition (other than lost/stolen card)

CODE_08

Honor with ID

CODE_10

Partial approval

CODE_11

Approved (V.I.P)

CODE_12

Invalid transaction

CODE_13

Invalid amount or currency conversion field overflow

CODE_14

Invalid account number (no such number)

CODE_15

Invalid issuer/No such issuer

CODE_19

Re-enter transaction

CODE_21

No action taken

CODE_25

Unable to locate record in file

CODE_28

File temporarily not available for update or inquiry

CODE_30

Format error

CODE_39

No credit account

CODE_41

Lost card, pick up (fraud account)

CODE_43

Stolen card, pick up (fraud account)

CODE_44

No investment account

CODE_46

Closed account

CODE_51

Insufficient funds/over credit limit

CODE_52

No checking account

CODE_53

No savings account

CODE_54

Expired card or expiration date is missing

CODE_55

Incorrect PIN or PIN missing

CODE_57

Transaction not permitted to issuer/cardholder

CODE_58

Transaction not permitted to acquirer/terminal

CODE_59

Suspected fraud

CODE_61

Exceeds withdrawal amount limit/Exceeds approval amount limit

CODE_62

Restricted card (card invalid in this region or country)

CODE_63

Security violation (source is not correct issuer)

CODE_64

Transaction does not fulfill AML requirement

CODE_65

Exceeds withdrawal frequency limit

CODE_68

Response received too late

CODE_70

Contact Card Issuer

CODE_71

PIN Not Changed

CODE_75

Allowable number of PIN tries exceeded

CODE_76

Invalid/nonexistent “To Account” specified

CODE_77

Invalid/nonexistent “From Account” specified

CODE_78

Invalid/nonexistent account specified(general)/Blocked, first used—transaction from new cardholder, and card not properly unblocked (Visa)

CODE_79

Already reversed (by Switch)

CODE_80

No financial impact

CODE_81

Domestic Debit Transaction Not Allowed (Regional use only)/Cryptographic error found in PIN(Visa)

CODE_82

Negative CAM, dCVV, iCVV, or CVV results/Offline PIN authentication interrupted

CODE_84

Invalid Authorization Life Cycle

CODE_85

No reason to decline a request for address verification, CVV2 verification, or a credit voucher or merchandise return

CODE_86

PIN Validation not possible

CODE_87

Purchase Amount Only, No Cash Back

CODE_88

Cryptographic failure

CODE_89

Card verification value (CVV) verification failed (no pickup)/Ineligible to receive financial position information (GIV)

CODE_91

Authorization Platform or issuer system inoperative

CODE_92

Unable to route transaction

CODE_93

Transaction cannot be completed - violation of law

CODE_94

Duplicate transmission detected

CODE_95

Reconcile error

CODE_96

System malfunction or certain field error conditions

CODE_B1

Surcharge amount not permitted on Visa cards (U.S. acquirers only)

CODE_B2

Surcharge amount not supported by debit network issuer.

CODE_N0

Force STIP

CODE_N3

Cash service not available

CODE_N4

Cashback request exceeds issuer limit

CODE_N5

Ineligible for resubmission

CODE_N7

Decline for CVV2 failure

CODE_N8

Transaction amount exceeds preauthorized approval amount

CODE_P2

Invalid biller information

CODE_P5

PIN Change/Unblock request declined

CODE_P6

Unsafe PIN

CODE_Q1

Card Authentication failed

CODE_R0

Stop Payment Order

CODE_R1

Revocation of authorization order

CODE_R3

Revocation of all authorizations order

CODE_XA

Forward to issuer

CODE_XD

Forward to issuer

CODE_Z3

Unable to go online

CODE_TBA

Customer ID verification failed")

2.9. Response statuses

2.9.1. Transaction statuses

Status Description

PENDING

Transaction is processing

APPROVED

Transaction complete successfully

DECLINED

Transaction was declined by Mastercard, look at response code

REVERSED

Transaction was reversed successfully - money will return to cardholder’s account

CLEARED

Transaction is cleared correctly

WAITING_ON_3DS_CONFIRMATION

Transaction is waiting for login to bank by cardholder and confirm transaction

NO_3DS_AUTHENTICATION

Cardholder did not login to bank in 15 minutes since transaction initiated

REJECTED

Something went wrong and some validation error occurred

2.9.2. Reversal statuses

Status Description

APPROVED

A reversal complete successfully

DECLINED

A reversal was declined by Mastercard, look at response code

ERROR

Something went wrong and reversal cannot be processed

CANNOT_REVERSAL

Reversal could not be processed and it is not possible

2.9.3. Clearing statuses

Status

Description

APPROVED

A clearing complete successfully

DECLINED

A clearing is declined

ERROR

Something went wrong and clearing cannot be processed

TO_CLEARING

Transaction was registered correctly and will processing soon

WAITING_FOR_SENDING_FILE_TO_MASTERCARD

Clearing was processed with success and now it is waiting for send to Mastercard

CANNOT_CLEAR

Clearing is not possible

CLEARING_TRANSACTION_NOT_FOUND

Clearing transaction is not found

TIME_IS_OVER

Time for clearing is over (7 days when manual clearing is enabled)

PENDING

Clearing is pending

PROCESSING

Clearing is processing

2.9.4. Refund statuses

Status Description

APPROVED

Refund complete successfully

DECLINED

A refund is declined by MasterCard, look at response code

REFUND_PROCESSING

An attempt to transaction refund was registered and refund is processing

REFUND_TRANSACTION_NOT_FOUND

Transaction not found

REFUND_ALREADY_APPROVED

Transaction is just correctly refund when user make request again with same requestUuid

TRANSACTION_NOT_CLEARED

Transaction in not cleared yet

CHARGEBACK_REPORTED

Transaction is chargeback reported

3. Merchants

3.1. Add merchant

POST /merchants Content Type: application/json, Authorization: Basic Auth
Using this method, we can create a merchant that will be assigned to the currently authenticated PSP.
Notice that in order to make Merchant object transaction ready, you have to inform us when Merchant will added.
Next our employee will activate this Merchant object.

3.1.1. Request

HTTP Request
POST /merchants HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 374
Host: ecom-staging.fenige.pl

{
  "name" : "merchant_name",
  "companyName" : "merchant_company_name",
  "email" : "merchant_mail@example.com",
  "accountNumber" : "11124000013372880300945921",
  "vatIn" : "3936558874",
  "address" : {
    "city" : "Lublin",
    "country" : "PL",
    "homeNumber" : "10",
    "street" : "Karola Olszewskiego",
    "streetNumber" : "11",
    "postalCode" : "24-110"
  }
}
Table 14. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 15. Add merchant request fields
Path Type Constraints Description

name

String

@Length must be between 3 and 50 inclusive, @Must not be blank, @Must not be null

The merchant’s name

companyName

String

@Length must be between 3 and 22 inclusive, @Must not be blank, @Must not be null

The merchant’s company name

email

String

@Must not be null

The merchant’s email

accountNumber

String

@Length must be between 3 and 34 inclusive, @Must not be blank, @Must not be null

Merchant’s account number

vatIn

String

@Length must be between 1 and 15 inclusive, @Must not be blank

Merchant’s vatIn number

address.city

String

@Length must be between 1 and 13 inclusive, @Must not be blank, @Must not be null

The merchant’s city

address.country

String

@Must match the regular expression ^[A-Z]{2}$, @Must not be null

The merchant’s country in accordance with ISO 3166-1

address.homeNumber

String

@Length must be between 1 and 5 inclusive, @Must match the regular expression ^[a-zA-Z0-9 ]*$, @Nullable

The merchant’s home number

address.street

String

@Length must be between 1 and 48 inclusive, @Must match the regular expression (s[s]+)*$, @Must not be blank, @Must notbe null

The merchant’s street

address.streetNumber

String

@Length must be between 1 and 5 inclusive, @Must match the regular expression ^[a-zA-Z0-9]+$, @Must not be blank, @Must not be null

The merchant’s street number

address.postalCode

String

@Length must be between 1 and 10 inclusive, @Must not be blank, @Must not be null

The merchant’s postal code

3.1.2. Response

Response status
Status Description

200 OK

Returned when merchant was successfully create.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

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

409 CONFLICT

STATUS: E0121 - Returned when merchant is already existing.

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:19 GMT
Content-Length: 872

{
  "uuid" : "0c5ab87d-0e15-40b9-9015-a0eb4544d822",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "_links" : {
    "self" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants/0c5ab87d-0e15-40b9-9015-a0eb4544d822",
      "title" : "Get merchant",
      "type" : "GET"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants/0c5ab87d-0e15-40b9-9015-a0eb4544d822",
      "title" : "Update merchant",
      "type" : "PUT"
    } ],
    "deactivate" : {
      "href" : "https://ecom-staging.fenige.pl/merchants/0c5ab87d-0e15-40b9-9015-a0eb4544d822/deactivate",
      "title" : "Deactivate merchant",
      "type" : "PUT"
    },
    "terminals" : {
      "href" : "https://ecom-staging.fenige.pl/merchants/0c5ab87d-0e15-40b9-9015-a0eb4544d822/terminals",
      "title" : "Add terminal to merchant",
      "type" : "POST"
    }
  }
}
Table 16. Hateoas links
Relation Description

self

Available methods for this resource

terminals

Available methods for merchants’s terminals

deactivate

Merchant deactivation methods

Table 17. Response fields
Path Type Description

uuid

String

Merchant’s unique uuid in system

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:21 GMT
Connection: close
Content-Length: 431

{
  "errors" : {
    "vatIn" : [ "must not be blank" ],
    "address" : [ "must not be null" ],
    "companyName" : [ "must not be blank", "must not be null" ],
    "name" : [ "must not be blank", "must not be null" ],
    "accountNumber" : [ "must not be blank" ],
    "email" : [ "errors.validation.invalid-email" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "cf52a661-1134-4901-9bf4-8ef06dda6a9b"
}
Table 18. Response fields
Path Type Description

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:15:19 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "1841b9fd-718e-4278-bc06-334a5ea7f4b1",
  "links" : [ ]
}
Table 19. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:15:24 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "9c0b260e-96e0-4822-baa7-21aa8dacd606",
  "links" : [ ]
}
Table 20. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

409 CONFLICT
HTTP Response - STATUS: E0121
HTTP/1.1 409 Conflict
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:22 GMT
Content-Length: 188

{
  "status" : "E0121",
  "message" : "Adding Merchant to database was failed, Merchant already exists",
  "httpStatus" : "CONFLICT",
  "traceId" : "8b3521cd-9758-4d80-8ac8-6a803118d0ea"
}
Table 21. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:18 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "05addb3d-1ebd-455f-9ab1-85525d98bdca"
}
Table 22. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

3.2. Deactivate merchant

PUT /merchants/{uuid}/deactivate Content Type: application/json, Authorization: Basic Auth
This method allows to deactivate an existing merchant. Even if merchant is deactivated you should receive empty response body.

3.2.1. Request

HTTP Request
PUT /merchants/d1d6405b-26b7-4abe-a75d-9472c6948d45/deactivate HTTP/1.1
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Host: ecom-staging.fenige.pl
Table 23. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 24. merchants/{uuid}/deactivate
Parameter Description

uuid

Merchant’s unique uuid in system

3.2.2. Response

Response status
Status Description

204 NO CONTENT

Returned when the merchant was successfully updated.

401 UNAUTHORIZED

STATUS: E8002 - Returned when you are the problem with authorized to your PSP.

403 FORBIDDEN

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

404 NOT FOUND

STATUS: E0122 - Returned when merchant not exist.

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

204 NO CONTENT
HTTP Response
HTTP/1.1 204 No Content
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=UTF-8
Date: Thu, 22 Jul 2021 22:15:13 GMT
401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:15:13 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "93bb28b5-004f-4bdc-9578-3da622f48951",
  "links" : [ ]
}
Table 25. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:15:16 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "c9266c0d-b706-4f0c-8a73-be0dcbdd9974",
  "links" : [ ]
}
Table 26. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0122
HTTP/1.1 404 Not Found
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:15 GMT
Content-Length: 146

{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "8cef0c7b-41f4-4d1c-9ccd-d49c700044e2"
}
Table 27. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:11 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "e0bd25c5-b2d1-4ac1-b157-fd78de7bee10"
}
Table 28. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

3.3. Get merchant for uuid

GET /merchants/{uuid} Authorization: Basic Auth
Using this method, we can get a merchant with a unique uuid. We send uuid in url as a param. In response, we receive detailed information about the merchant.

3.3.1. Request

HTTP Request
GET /merchants/83a4be6e-df01-4efa-a2a1-800ab03611e7 HTTP/1.1
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Host: ecom-staging.fenige.pl
Table 29. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 30. merchants/{uuid}
Parameter Description

uuid

Merchant’s unique uuid in system

3.3.2. Response

Response status
Status Description

200 OK

Returned when the merchant is already existing. In response are details about the merchant.

401 UNAUTHORIZED

STATUS: E8002 - Returned when you are the problem with authorized to your PSP.

403 FORBIDDEN

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

404 NOT FOUND

STATUS: E0122 - Returned when merchant not exist.

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:32 GMT
Content-Length: 1435

{
  "uuid" : "83a4be6e-df01-4efa-a2a1-800ab03611e7",
  "name" : "merchant_name",
  "companyName" : "merchant_company_name",
  "email" : "merchant_mail@example.com",
  "merchantStatus" : "ACTIVE",
  "address" : {
    "city" : "Lublin",
    "country" : "PL",
    "homeNumber" : "10",
    "street" : "Karola Olszewskiego",
    "streetNumber" : "11",
    "postalCode" : "24-110"
  },
  "accountNumber" : "11124000013372880300945921",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "_links" : {
    "self" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants/83a4be6e-df01-4efa-a2a1-800ab03611e7",
      "title" : "Get merchant",
      "type" : "GET"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants/83a4be6e-df01-4efa-a2a1-800ab03611e7",
      "title" : "Update merchant",
      "type" : "PUT"
    } ],
    "deactivate" : {
      "href" : "https://ecom-staging.fenige.pl/merchants/83a4be6e-df01-4efa-a2a1-800ab03611e7/deactivate",
      "title" : "Deactivate merchant",
      "type" : "PUT"
    },
    "terminals" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants/83a4be6e-df01-4efa-a2a1-800ab03611e7/terminals",
      "title" : "Get terminals for merchant",
      "type" : "GET"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants/83a4be6e-df01-4efa-a2a1-800ab03611e7/terminals",
      "title" : "Add terminal to merchant",
      "type" : "POST"
    } ]
  }
}
Table 31. Hateoas links
Relation Description

self

Available methods for this resource

terminals

Available methods for merchants’s terminals

deactivate

Merchant deactivation methods

Table 32. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

uuid

String

Merchant’s unique uuid in system

name

String

The merchant’s name

companyName

String

The merchant’s company name

email

String

The merchant’s email

address.city

String

The merchant’s city

address.country

String

The merchant’s country in accordance with ISO 3166-1

address.homeNumber

String

The merchant’s home number

address.street

String

The merchant’s street

address.streetNumber

String

The merchant’s street number

address.postalCode

String

The merchant’s postal code

httpStatus

String

Response http status

merchantStatus

String

The merchant’s status

accountNumber

String

The merchant’s account number

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:15:32 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "6dd6e3e0-c41b-44a5-bbf2-15c9f1987d42",
  "links" : [ ]
}
Table 33. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:15:34 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "521d3e48-8299-4d9c-8c23-be4e7c5d56c6",
  "links" : [ ]
}
Table 34. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0122
HTTP/1.1 404 Not Found
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:32 GMT
Content-Length: 146

{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "d39d6222-b974-4e17-9de0-0ad0524548e1"
}
Table 35. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:29 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "c3c1887a-1491-490f-9bf9-7a0882d5cbd5"
}
Table 36. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

3.4. Get merchant list

GET /merchants Authorization: Basic Auth
Using this method, we can get a list of merchants who are assigned to the authenticated PSP.

3.4.1. Request

HTTP Request
GET /merchants HTTP/1.1
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Host: ecom-staging.fenige.pl
Table 37. Request headers
Name Description

Authorization

Basic auth credentials for PSP

3.4.2. Response

Response status
Status Description

200 OK

Returned when the authorized PSP has at least one merchant. In response, he receives a list of merchants with details about each of them.

200 OK

STATUS: E0123 - Returned when merchant list is empty.

401 UNAUTHORIZED

STATUS: E8002 - Returned when you are the problem with authorized to your PSP.

403 FORBIDDEN

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

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:25 GMT
Content-Length: 1662

{
  "merchants" : {
    "content" : [ {
      "uuid" : "2a1926f0-b0d7-4a1b-ac1f-051feb8f7694",
      "name" : "merchant_name",
      "companyName" : "merchant_company_name",
      "email" : "merchant_mail@example.com",
      "merchantStatus" : "ACTIVE",
      "address" : {
        "city" : "Lublin",
        "country" : "PL",
        "homeNumber" : "10",
        "street" : "Karola Olszewskiego",
        "streetNumber" : "11",
        "postalCode" : "24-110"
      },
      "accountNumber" : "11124000013372880300945921"
    } ],
    "pageable" : {
      "sort" : {
        "sorted" : false,
        "unsorted" : true
      },
      "pageSize" : 20,
      "pageNumber" : 0,
      "offset" : 0,
      "paged" : true,
      "unpaged" : false
    },
    "last" : true,
    "totalElements" : 1,
    "totalPages" : 1,
    "first" : true,
    "numberOfElements" : 1,
    "sort" : {
      "sorted" : false,
      "unsorted" : true
    },
    "size" : 20,
    "number" : 0
  },
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "_links" : {
    "self" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants",
      "title" : "Get list of merchants",
      "type" : "GET"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants",
      "title" : "Add merchant",
      "type" : "POST"
    } ],
    "first" : {
      "href" : "https://ecom-staging.fenige.pl/merchants?page=0&size=20",
      "title" : "Get first page with merchants",
      "type" : "GET"
    },
    "last" : {
      "href" : "https://ecom-staging.fenige.pl/merchants?page=0&size=20",
      "title" : "Get last page with merchants",
      "type" : "GET"
    }
  }
}
Table 38. Hateoas links
Relation Description

self

Available methods for this resource

last

Redirecting to last page with merchants

first

Redirecting to first page with merchants

Table 39. Response fields
Path Type Description

merchants.content.[].name

String

The merchant’s name

merchants.content.[].companyName

String

The merchant’s company name

merchants.content.[].email

String

The merchant’s email

merchants.content.[].merchantStatus

String

The merchant’s status

merchants.content.[].uuid

String

Merchant’s unique uuid in system

merchants.content.[].address.city

String

The merchant’s city

merchants.content.[].address.country

String

The merchant’s country in accordance with ISO 3166-1

merchants.content.[].address.homeNumber

String

The merchant’s home number

merchants.content.[].address.street

String

The merchant’s street

merchants.content.[].address.streetNumber

String

The merchant’s street number

merchants.content.[].address.postalCode

String

The merchant’s postal code

merchants.content.[].accountNumber

String

The merchant’s account number

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

_links

Object

Links to other resources

200 OK
HTTP Response - STATUS: E0123
HTTP/1.1 200 OK
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:27 GMT
Content-Length: 379

{
  "status" : "E0123",
  "message" : "List of Merchant is empty.",
  "httpStatus" : "OK",
  "_links" : {
    "self" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants",
      "title" : "Get list of merchants",
      "type" : "GET"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants",
      "title" : "Add merchant",
      "type" : "POST"
    } ]
  }
}
Table 40. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:15:27 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "5579dda8-11c4-4427-b5a0-cb6180e5fae7",
  "links" : [ ]
}
Table 41. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:15:29 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "baa8c09d-49ae-46c2-a2b4-2e5dbe08ce09",
  "links" : [ ]
}
Table 42. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:25 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "884671ce-caa7-4277-9279-78e9724f4b38"
}
Table 43. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

3.5. Update merchant

PUT /merchants/{uuid} Content Type: application/json, Authorization: Basic Auth
By using this method, we can update existing merchant. We need to know its unique uuid and be authenticated to the correct PSP.

3.5.1. Request

HTTP Request
PUT /merchants/dc3430ed-8bf9-46cc-81f5-1f0c620e413c HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 298
Host: ecom-staging.fenige.pl

{
  "email" : "newaddress@fenige.pl",
  "accountNumber" : "73124000013833390258788811",
  "vatIn" : "3936558874",
  "address" : {
    "city" : "Lublin",
    "country" : "PL",
    "homeNumber" : "10",
    "street" : "Karola Olszewskiego",
    "streetNumber" : "11",
    "postalCode" : "24-110"
  }
}
Table 44. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 45. Update merchant request fields
Path Type Constraints Description

email

String

@Must not be null

The merchant’s email

accountNumber

String

@Length must be between 3 and 34 inclusive, @Must not be blank, @Must not be null

Merchant’s account number

vatIn

String

@Length must be between 1 and 15 inclusive, @Must not be blank

Merchant’s vatIn number

address.city

String

@Length must be between 1 and 13 inclusive, @Must not be blank, @Must not be null

The merchant’s city

address.country

String

@Must match the regular expression ^[A-Z]{2}$, @Must not be null

The merchant’s country in accordance with ISO 3166-1

address.homeNumber

String

@Length must be between 1 and 5 inclusive, @Must match the regular expression ^[a-zA-Z0-9 ]*$, @Nullable

The merchant’s home number

address.street

String

@Length must be between 1 and 48 inclusive, @Must match the regular expression (s[s]+)*$, @Must not be blank, @Must notbe null

The merchant’s street

address.streetNumber

String

@Length must be between 1 and 5 inclusive, @Must match the regular expression ^[a-zA-Z0-9]+$, @Must not be blank, @Must not be null

The merchant’s street number

address.postalCode

String

@Length must be between 1 and 10 inclusive, @Must not be blank, @Must not be null

The merchant’s postal code

3.5.2. Response

Response status
Status Description

200 OK

Returned when the merchant exist. In response is details about the merchant.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

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

404 NOT FOUND

STATUS: E0122 - Returned when merchant not exist.

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:36 GMT
Content-Length: 1058

{
  "uuid" : "dc3430ed-8bf9-46cc-81f5-1f0c620e413c",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "_links" : {
    "self" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants/dc3430ed-8bf9-46cc-81f5-1f0c620e413c",
      "title" : "Update merchant",
      "type" : "PUT"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants/dc3430ed-8bf9-46cc-81f5-1f0c620e413c",
      "title" : "Get merchant",
      "type" : "GET"
    } ],
    "deactivate" : {
      "href" : "https://ecom-staging.fenige.pl/merchants/dc3430ed-8bf9-46cc-81f5-1f0c620e413c/deactivate",
      "title" : "Deactivate merchant",
      "type" : "PUT"
    },
    "terminals" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants/dc3430ed-8bf9-46cc-81f5-1f0c620e413c/terminals",
      "title" : "Get terminals for merchant",
      "type" : "GET"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants/dc3430ed-8bf9-46cc-81f5-1f0c620e413c/terminals",
      "title" : "Add terminal to merchant",
      "type" : "POST"
    } ]
  }
}
Table 46. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

uuid

String

Merchant’s unique uuid in system

httpStatus

String

Response http status

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:42 GMT
Connection: close
Content-Length: 318

{
  "errors" : {
    "vatIn" : [ "errors.validation.not-blank" ],
    "address" : [ "must not be null" ],
    "accountNumber" : [ "must not be blank" ],
    "email" : [ "errors.validation.invalid-email" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "dd20c6d4-594b-4fda-89b0-b4c57e80a658"
}
Table 47. Response fields
Path Type Description

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:15:37 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "04c17182-bfce-481f-a5a3-a6bcbdf93d6b",
  "links" : [ ]
}
Table 48. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:15:44 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "e7fd6a6c-3e44-467a-8015-9bc43323e0e2",
  "links" : [ ]
}
Table 49. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0122
HTTP/1.1 404 Not Found
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:40 GMT
Content-Length: 146

{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "74204e24-61cf-4223-bfb0-fb028dc00c3c"
}
Table 50. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:34 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "d68f4b12-6c38-4a49-9d6a-c072e2f4815a"
}
Table 51. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

4. Terminals

4.1. Add terminal

POST /merchants/{merchantUUID}/terminals Content Type: application/json, Authorization: Basic Auth
Using this method, we can create a terminal that will be assigned to the currently merchant.
You cannot add two terminals that have the same settlement currency.
Notice that in order to make Terminal object transaction ready, you have to inform us when Terminal will added correctly.
Next our employee will activate this Terminal object.

4.1.1. Request

HTTP Request
POST /merchants/9ef9f018-d6d0-471d-bac9-18e35eae587b/terminals HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 384
Host: ecom-staging.fenige.pl

{
  "name" : "terminal_name",
  "isDefault" : true,
  "is3dsEnable" : true,
  "termUrl" : "https:\\/\\/www.fenige.com",
  "settlementCurrency" : "UAH",
  "calculateCommissionType" : "STANDARD",
  "commission" : {
    "domestic" : {
      "percent" : 15,
      "min" : 0,
      "max" : 10
    },
    "crossborder" : {
      "percent" : 15,
      "min" : 0,
      "max" : 10
    }
  }
}
Table 52. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 53. Add terminal request fields
Path Type Constraints Description

name

String

@Length must be between 3 and 50 inclusive, @Must not be blank, @Must not be null

The terminal’s name

isDefault

Boolean

@Must not be null

Terminal is default if 'isDefault' is set as 'true'

is3dsEnable

Boolean

@Must not be null

Is 3DS enabled for transactions. Enabled if true, if 'false' 3DS is disabled

termUrl

String

@Must not be null if is3dsEnable is true

Merchant URL to be redirected from Fenige after user login in the bank. This URL must accept request-uuid parameter, that tells which transaction is begin processed. Remember to add protocol prefix to URL (https://)

commission

Object

@Must not be null

This is commission that has been added to the transaction

commission.domestic

Object

@Must not be null

This is domestic commission that has been added to the transaction

commission.domestic.percent

Number

@Must be at least 0, @Must be at most 100, @Must not be null

This is percent domestic commission that has been added to the transaction

commission.domestic.min

Number

@Must be at least 0, @Must not be null

This is minimum domestic commission that has been added to the transaction

commission.domestic.max

Number

@Must be at least 0, @Must not be null

This is maximum domestic commission that has been added to the transaction

commission.crossborder

Object

@Must not be null

This is crossborder commission that has been added to the transaction

commission.crossborder.percent

Number

@Must be at least 0, @Must be at most 100, @Must not be null

This is percent crossborder commission that has been added to the transaction

commission.crossborder.min

Number

@Must be at least 0, @Must not be null

This is minimum crossborder commission that has been added to the transaction

commission.crossborder.max

Number

@Must be at least 0, @Must not be null

This is maximum crossborder commission that has been added to the transaction

settlementCurrency

String

@Must not be null

Settlement currency for terminal (in accordance with ISO-4217)

calculateCommissionType

String

@Must not be null

Commission type for terminal (STANDARD - percentage commission, SUMMARIZE - percentage commission and fixed amount)

4.1.2. Response

Response status
Status Description

200 OK

Returned when terminal was successfully create.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

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

409 CONFLICT

STATUS: E0131 Returned when terminal is already existing.

STATUS: E0139 Adding terminal to database failed. Currency not supported by PSP

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:56 GMT
Content-Length: 631

{
  "uuid" : "31403953-4304-4d0c-8515-c57e6dbae5bf",
  "merchantUUID" : "9ef9f018-d6d0-471d-bac9-18e35eae587b",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "_links" : {
    "self" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants/9ef9f018-d6d0-471d-bac9-18e35eae587b/terminals/31403953-4304-4d0c-8515-c57e6dbae5bf",
      "title" : "Get terminal",
      "type" : "GET"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants/9ef9f018-d6d0-471d-bac9-18e35eae587b/terminals/31403953-4304-4d0c-8515-c57e6dbae5bf",
      "title" : "Update terminal",
      "type" : "PUT"
    } ]
  }
}
Table 54. Hateoas links
Relation Description

self

Available methods for this resource

Table 55. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

uuid

String

The terminal’s identifier in the database

merchantUUID

String

The merchant’s identifier in the database

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:57 GMT
Connection: close
Content-Length: 423

{
  "errors" : {
    "calculateCommissionType" : [ "must not be null" ],
    "isDefault" : [ "must not be null" ],
    "is3dsEnable" : [ "must not be null" ],
    "settlementCurrency" : [ "must not be null" ],
    "name" : [ "must not be null", "must not be blank" ],
    "commission" : [ "must not be null" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "7cf0f78b-ced2-4c3c-8431-afba13835302"
}
Table 56. Response fields
Path Type Description

status

String

Response code from Fenige system

traceId

String

Unique id for this http request register in system

httpStatus

String

Response http status

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:14:02 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "2acad7ab-b9d8-42c5-b436-c7b23def4055",
  "links" : [ ]
}
Table 57. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:14:01 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "3dcf8880-7f09-41c0-819a-fc8177d8a7be",
  "links" : [ ]
}
Table 58. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

409 CONFLICT
HTTP Response - STATUS: E0131
HTTP/1.1 409 Conflict
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:58 GMT
Content-Length: 188

{
  "status" : "E0131",
  "message" : "Adding Terminal to database was failed, Terminal already exists",
  "httpStatus" : "CONFLICT",
  "traceId" : "06d6de86-e422-4f3a-ad24-569bb63a8957"
}
HTTP Response - STATUS: E0139
HTTP/1.1 409 Conflict
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:58 GMT
Content-Length: 190

{
  "status" : "E0139",
  "message" : "Adding terminal to database failed. Currency not supported by PSP",
  "httpStatus" : "CONFLICT",
  "traceId" : "9f689343-38fb-4caa-9893-46870f775b3a"
}
Table 59. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:14:00 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "cd6487f8-98ea-4da7-b47b-b2ee805c2afa"
}
Table 60. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

4.2. Deactivate terminal

PUT merchants/{merchantUUID}/terminals/{uuid}/deactivate Content Type: application/json, Authorization: Basic Auth
Method allows to deactivate an existing terminal. We can deactivate terminal. Even if terminal is deactivated you should receive empty response body.

4.2.1. Request

HTTP Request
PUT /merchants/4f46ce10-2a12-438a-8f4e-a3aab5b73a3f/terminals/c2582897-a74d-478d-bd5a-dc1c2c6b7190/deactivate HTTP/1.1
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Host: ecom-staging.fenige.pl
Table 61. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 62. merchants/{merchantUUID}/terminals/{uuid}/deactivate
Parameter Description

merchantUUID

Merchant’s unique uuid in system

uuid

Terminal’s unique uuid in system

4.2.2. Response

Response status
Status Description

204 NO CONTENT

Returned when the terminal was successfully updated.

401 UNAUTHORIZED

STATUS: E8002 - Returned when you are the problem with authorized to your PSP.

403 FORBIDDEN

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

404 NOT FOUND

STATUS: E0122 - Returned when merchant not exist.

STATUS: E0132 - Returned when terminal not exist.

422 UNPROCESSABLE ENTITY

STATUS: E0138 - Returned when can’t deactivate default terminal if is not last.

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

204 NO CONTENT
HTTP Response
HTTP/1.1 204 No Content
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=UTF-8
Date: Thu, 22 Jul 2021 22:14:05 GMT
401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:14:07 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "814f099a-82cc-4297-b659-17a6ad3b47bc",
  "links" : [ ]
}
Table 63. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:14:11 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "b3cfecc3-73cc-49c3-8ca7-db801b8ab336",
  "links" : [ ]
}
Table 64. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0132
HTTP/1.1 404 Not Found
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:14:09 GMT
Content-Length: 146

{
  "status" : "E0132",
  "message" : "Terminal not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "06cad5bb-2426-4b0f-8fa2-8a939427bafc"
}
HTTP Response - STATUS: E0122
HTTP/1.1 404 Not Found
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:14:05 GMT
Content-Length: 146

{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "a3a53048-3036-4f95-be32-60a94d914119"
}
Table 65. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E0138
HTTP/1.1 422 Unprocessable Entity
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:14:10 GMT
Content-Length: 185

{
  "status" : "E0138",
  "message" : "Can't deactivate default terminal if is not last",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "050abb84-6674-45da-95cd-3159e67d872d"
}
Table 66. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:14:04 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "5c57a621-3342-4fb5-b16f-3a855124aa85"
}
Table 67. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

4.3. Get terminal for uuid

GET /merchants/{merchantUUID}/terminals/{uuid} Authorization: Basic Auth
Using this method, we can get a terminal with a unique uuid. We send merchant uuid and terminal uuid in url as a params. In response, we receive detailed information about the
terminal.

4.3.1. Request

HTTP Request
GET /merchants/0e79c862-c3f8-4f78-aa2d-8ec675a1954b/terminals/a5dad45c-611c-4904-a37f-8047620bae4a HTTP/1.1
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Host: ecom-staging.fenige.pl
Table 68. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 69. merchants/{merchantUUID}/terminals/{uuid}
Parameter Description

merchantUUID

Merchant’s unique uuid in system

uuid

Terminal’s unique uuid in system

4.3.2. Response

Response status
Status Description

200 OK

Returned when the terminal is already existing. In response are details about the terminal.

401 UNAUTHORIZED

STATUS: E8002 - Returned when you are the problem with authorized to your PSP.

403 FORBIDDEN

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

404 NOT FOUND

STATUS: E0132 - Returned when terminal not exist.

404 NOT FOUND

STATUS: E0122 - Returned when merchant not exist.

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:36 GMT
Content-Length: 806

{
  "uuid" : "a5dad45c-611c-4904-a37f-8047620bae4a",
  "name" : "terminal_name",
  "merchantUUID" : "0e79c862-c3f8-4f78-aa2d-8ec675a1954b",
  "terminalStatus" : "ACTIVE",
  "settlementCurrency" : "PLN",
  "calculateCommissionType" : "STANDARD",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "3dsEnable" : true,
  "default" : true,
  "_links" : {
    "self" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants/0e79c862-c3f8-4f78-aa2d-8ec675a1954b/terminals/a5dad45c-611c-4904-a37f-8047620bae4a",
      "title" : "Get terminal",
      "type" : "GET"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants/0e79c862-c3f8-4f78-aa2d-8ec675a1954b/terminals/a5dad45c-611c-4904-a37f-8047620bae4a",
      "title" : "Update terminal",
      "type" : "PUT"
    } ]
  }
}
Table 70. Hateoas links
Relation Description

self

Available methods for this resource

Table 71. Response fields
Path Type Description

merchantUUID

String

The merchant’s identifier in the database

name

String

The terminal’s name

uuid

String

The terminal’s identifier in the database

3dsEnable

Boolean

Is 3DS enabled for transaction. Enabled if true, is not enabled if false

terminalStatus

String

The terminals’s status (NEW - terminal is waiting for activation in Fenige system, ACTIVE - terminal is active, INACTIVE - terminal is not active)

default

Boolean

Is default terminal. Default if true, is not default if false

calculateCommissionType

String

Commission type for terminal (STANDARD - percentage commission, SUMMARIZE - percentage commission and fixed amount)

settlementCurrency

String

Settlement currency for terminal (in accordance with ISO-4217)

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:13:33 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "642d9edb-b142-4337-9f73-96325c2f4c5d",
  "links" : [ ]
}
Table 72. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:13:39 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "ed086328-205a-4883-a116-e74ee4dc5051",
  "links" : [ ]
}
Table 73. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0132
HTTP/1.1 404 Not Found
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:39 GMT
Content-Length: 146

{
  "status" : "E0132",
  "message" : "Terminal not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "4dd562a7-1922-4b24-871e-8b308a83e1be"
}
Table 74. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

404 NOT FOUND
HTTP Response - STATUS: E0136
HTTP/1.1 404 Not Found
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:32 GMT
Content-Length: 146

{
  "status" : "E0136",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "f3ed8994-50f4-497a-b211-2e56c8125bd9"
}
Table 75. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:31 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "0348e4c9-6df5-44cf-9dbf-95e8681c8831"
}
Table 76. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

4.4. Get terminals list

GET /merchants/{merchantUUID}/terminals Authorization: Basic Auth
Using this method, we can get a list of terminals who are assigned to the merchant.

4.4.1. Request

HTTP Request
GET /merchants/fa3d094d-93f2-455b-aaad-4e3e422f598c/terminals HTTP/1.1
Accept: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Host: ecom-staging.fenige.pl
Table 77. Request headers
Name Description

Authorization

Basic auth credentials for PSP

4.4.2. Response

Response status
Status Description

200 OK

Returned when the merchant has at least one terminal. In response, he receives a list of terminals with details about each of them.

200 OK

STATUS: E0133 - Returned when terminal list is empty.

401 UNAUTHORIZED

STATUS: E8002 - Returned when you are the problem with authorized to your PSP.

403 FORBIDDEN

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

404 NOT FOUND

STATUS: E0122 - Returned when merchant not exist.

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:53 GMT
Content-Length: 1219

{
  "terminals" : {
    "content" : [ {
      "uuid" : "5549a761-b3f6-462f-95f9-91570194c510",
      "name" : "terminal_name",
      "merchantUUID" : "fa3d094d-93f2-455b-aaad-4e3e422f598c",
      "terminalStatus" : "ACTIVE",
      "settlementCurrency" : "PLN",
      "3dsEnable" : true,
      "default" : true
    } ],
    "pageable" : {
      "sort" : {
        "sorted" : false,
        "unsorted" : true
      },
      "pageSize" : 20,
      "pageNumber" : 0,
      "offset" : 0,
      "paged" : true,
      "unpaged" : false
    },
    "last" : true,
    "totalElements" : 1,
    "totalPages" : 1,
    "first" : true,
    "numberOfElements" : 1,
    "sort" : {
      "sorted" : false,
      "unsorted" : true
    },
    "size" : 20,
    "number" : 0
  },
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "_links" : {
    "self" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants/{merchantUUID}/terminals",
      "title" : "Get list of terminals",
      "type" : "GET",
      "templated" : true
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants/{merchantUUID}/terminals",
      "title" : "Add terminal",
      "type" : "POST",
      "templated" : true
    } ]
  }
}
Table 78. Hateoas links
Relation Description

self

Available methods for this resource

Table 79. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

terminals.content.[].uuid

String

The terminal’s identifier in the database

terminals.content.[].name

String

The terminal’s name

terminals.content.[].merchantUUID

String

Merchant’s unique uuid in system

terminals.content.[].3dsEnable

Boolean

Is 3DS enabled for transaction. Enabled if true, is not enabled if false

terminals.content.[].terminalStatus

String

The terminals’s status (NEW - terminal is waiting for activation in Fenige system, ACTIVE - terminal is active, INACTIVE - terminal is not active)

terminals.content.[].default

Boolean

Is default terminal. Default if true, is not default if false

terminals.content.[].settlementCurrency

String

Settlement currency for terminal (in accordance with ISO-4217)

_links

Object

Links to other resources

200 OK
HTTP Response - STATUS: E0133
HTTP/1.1 200 OK
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:51 GMT
Content-Length: 532

{
  "merchantUuid" : "d05824f9-f25b-44d2-b6bc-be5820e4494e",
  "status" : "E0133",
  "message" : "List of Terminal is empty.",
  "httpStatus" : "OK",
  "_links" : {
    "self" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants/d05824f9-f25b-44d2-b6bc-be5820e4494e/terminals",
      "title" : "Get list of terminals",
      "type" : "GET"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants/d05824f9-f25b-44d2-b6bc-be5820e4494e/terminals",
      "title" : "Add terminal",
      "type" : "POST"
    } ]
  }
}
Table 80. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

merchantUuid

String

The merchant’s identifier in the database

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:13:51 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "23d3b9de-b556-4c4f-bad1-211828560f78",
  "links" : [ ]
}
Table 81. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:13:54 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "39673b93-0b08-43f8-b15f-b77498deaf89",
  "links" : [ ]
}
Table 82. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0136
HTTP/1.1 404 Not Found
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:49 GMT
Content-Length: 146

{
  "status" : "E0136",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "40a7f3ba-b75f-4317-8046-a46369f6d4da"
}
Table 83. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:49 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "61efeff9-f609-42d3-85a2-6a7f6b4a888e"
}
Table 84. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

4.5. Update terminal

PUT /merchants/{merchantUUID}/terminals/{uuid} Content Type: application/json, Authorization: Basic Auth
By using this method, we can update existing terminal. We need to know its unique merchant uuid and terminal uuid.

4.5.1. Request

HTTP Request
PUT /merchants/7d4ca3e2-334c-401b-a370-bbb2356b7b03/terminals/ca08db43-2161-4154-8e74-619a17993e18 HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 264
Host: ecom-staging.fenige.pl

{
  "is3dsEnable" : true,
  "termUrl" : "https:\\/\\/www.fenige.com",
  "commission" : {
    "domestic" : {
      "percent" : 15,
      "min" : 0.1,
      "max" : 10
    },
    "crossborder" : {
      "percent" : 15,
      "min" : 0.1,
      "max" : 10
    }
  }
}
Table 85. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 86. Update terminal request fields
Path Type Constraints Description

is3dsEnable

Boolean

Is 3DS enabled for transaction. Enabled if true, disabled is unavailable, null if no modification

termUrl

String

@Must not be null if is3dsEnable is true

Merchant URL to be redirected from Fenige after user login in the bank. This URL must accept request-uuid parameter, that tells which transaction is begin processed. Remember to add protocol prefix to URL (https://)

commission

Object

This is commission that has been added to the transaction

commission.domestic

Object

@Must not be null

This is domestic commission that has been added to the transaction

commission.domestic.percent

Number

@Must be at least 0, @Must be at most 100, @Must not be null

This is percent domestic commission that has been added to the transaction

commission.domestic.min

Number

@Must be at least 0, @Must not be null

This is minimum domestic commission that has been added to the transaction

commission.domestic.max

Number

@Must be at least 0, @Must not be null

This is maximum domestic commission that has been added to the transaction

commission.crossborder

Object

@Must not be null

This is crossborder commission that has been added to the transaction

commission.crossborder.percent

Number

@Must be at least 0, @Must be at most 100, @Must not be null

This is percent crossborder commission that has been added to the transaction

commission.crossborder.min

Number

@Must be at least 0, @Must not be null

This is minimum crossborder commission that has been added to the transaction

commission.crossborder.max

Number

@Must be at least 0, @Must not be null

This is maximum crossborder commission that has been added to the transaction

4.5.2. Response

Response status
Status Description

200 OK

Returned when the terminal exist. In response is details about the terminal.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

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

404 NOT FOUND

STATUS: E0122 - Returned when merchant not exist.

STATUS: E0132 - Returned when terminal not exist.

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:44 GMT
Content-Length: 631

{
  "uuid" : "ca08db43-2161-4154-8e74-619a17993e18",
  "merchantUUID" : "7d4ca3e2-334c-401b-a370-bbb2356b7b03",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "_links" : {
    "self" : [ {
      "href" : "https://ecom-staging.fenige.pl/merchants/7d4ca3e2-334c-401b-a370-bbb2356b7b03/terminals/ca08db43-2161-4154-8e74-619a17993e18",
      "title" : "Update terminal",
      "type" : "PUT"
    }, {
      "href" : "https://ecom-staging.fenige.pl/merchants/7d4ca3e2-334c-401b-a370-bbb2356b7b03/terminals/ca08db43-2161-4154-8e74-619a17993e18",
      "title" : "Get terminal",
      "type" : "GET"
    } ]
  }
}
Table 87. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

uuid

String

The terminal’s identifier in the database

merchantUUID

String

The merchant’s identifier in the database

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:44 GMT
Connection: close
Content-Length: 168

{
  "errors" : {
    "termUrl" : [ "may not be null" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "c009f339-f1f4-4bf0-b46d-e4682222c833"
}
Table 88. Response fields
Path Type Description

status

String

Response code from Fenige system

traceId

String

Unique id for this http request register in system

httpStatus

String

Response http status

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:13:43 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "f6491eb4-6317-44c1-b311-2b850cbe7e85",
  "links" : [ ]
}
Table 89. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:13:47 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "f1a18213-c420-4a40-9157-4439774cf684",
  "links" : [ ]
}
Table 90. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0122
HTTP/1.1 404 Not Found
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:42 GMT
Content-Length: 146

{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "57127d01-0f4e-4752-aef0-a1981567b4f9"
}
HTTP Response - STATUS: E0132
HTTP/1.1 404 Not Found
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:47 GMT
Content-Length: 146

{
  "status" : "E0132",
  "message" : "Terminal not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "0b4e4c93-95b6-47b7-bb67-2d8ad7310afd"
}
Table 91. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:13:41 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "261887eb-6084-4ff8-a52d-d2075457883e"
}
Table 92. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

5. Cards

5.1. Add card

POST /client/card Content Type: application/json, Authorization: Basic Auth
Using this method, we can create a new Card in Fenige Datacenter.
Cards in the Ecommerce system are stored securely and are assigned to the PSP object.
Each PSP (object you authenticate in API with) has access to store cards in separated secure database.

5.1.1. Request

HTTP Request
POST /client/card HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 149
Host: ecom-staging.fenige.pl

{
  "cardNumber" : "5453131785534417",
  "expirationDate" : "10/24",
  "firstName" : "John",
  "lastName" : "Doe",
  "email" : "john.doe@fenige.pl"
}
Table 93. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 94. Add Card request fields
Path Type Constraints Description

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expirationDate

String

@Must match the regular expression ^(0[1-9]|1[0-2])\/?([0-9]{2})$, @Must not be empty, @Must not be null

Expiration date of card mm/yy

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null, @Must not be empty

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null, @Must not be empty

Last name of card holder

email

String

@Length must be between 1 and 128 inclusive, @Must be a well-formed email address, @Must not be blank, @Must not be null, @Must not be empty

Cardholder’s email

5.1.2. Response

Response status
Status Description

200 OK

Returned when terminal was successfully create.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

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

422 UNPROCESSABLE ENTITY

STATUS: E06007 - Returned when there was issue with internal Datacenter flow.

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown. + STATUS: E06000 - Critical error occurred while connecting to Datacenter.

200 OK
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 105

{
  "cardId" : 1,
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 95. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

cardId

Number

Id numeric value of added card

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:16:00 GMT
Connection: close
Content-Length: 483

{
  "errors" : {
    "firstName" : [ "length must be between 2 and 35" ],
    "lastName" : [ "length must be between 2 and 35" ],
    "email" : [ "must be a well-formed email address" ],
    "cardNumber" : [ "card number length must be between 12 and 19", "card number must be numeric", "invalid card number" ],
    "expirationDate" : [ "invalid card expiration date" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "7f25f457-0ef7-4ab2-9e84-55fbe9f0588b"
}
Table 96. Response fields
Path Type Description

errors.firstName

Array

First name validation error

errors.lastName

Array

Last name validation error

errors.email

Array

Email validation error

errors.cardNumber

Array

Card number validation error

errors.expirationDate

Array

Expiration date validation error

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:15:58 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "05be3488-c6be-4950-ba63-b8e090d9ca15",
  "links" : [ ]
}
Table 97. Response fields
Path Type Description

message

String

Message for response code from Fenige system

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E06007
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 208

{
  "status" : "E06007",
  "message" : "Exception occurred while trying to add ecommerce card",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "729015ca-f5b4-4371-9cc2-c7888a8af924",
  "links" : [ ]
}
Table 98. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:59 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "d91fa4e4-3b73-4af2-872d-a53f08850e9b"
}
HTTP Response - STATUS: E06000
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 214

{
  "status" : "E06000",
  "message" : "Unrecognized error occurred while connection to Datacenter",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "421a5508-a95d-4e13-965c-eb0090bb9761",
  "links" : [ ]
}
Table 99. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

5.2. Get card

GET /client/card/{cardId} Content Type: application/json, Authorization: Basic Auth
This method can be use for fetch Card object by 'cardId' parameter.

5.2.1. Request

HTTP Request
GET /client/card/1 HTTP/1.1
Authorization: Basic dXNlcjpwYXNzd29yZA==
Host: ecom-staging.fenige.pl
Table 100. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 101. client/card/{cardId}
Parameter Description

cardId

Id numeric value of card existing in database

5.2.2. Response

Response status
Status Description

200 OK

Returned when card was successfully fetched.

401 UNAUTHORIZED

STATUS: E8002 - Returned when you are the problem with authorized to your PSP.

403 FORBIDDEN

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

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 325

{
  "cardId" : 1,
  "hiddenCardNumber" : "545313******4417",
  "firstName" : "John",
  "lastName" : "Doe",
  "email" : "john.doe@fenige.pl",
  "createdDate" : "2021-07-23T00:15:56.195Z",
  "lastModifiedDate" : "2021-07-23T00:15:56.195Z",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 102. Response fields
Path Type Description

hiddenCardNumber

String

Full cardholder’s masked card number must be between 12-digits and 19-digits

firstName

String

First name of card holder

lastName

String

Last name of card holder

email

String

Cardholder’s email

createdDate

String

Card creation date

lastModifiedDate

String

Last card edit date

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

cardId

Number

Id numeric value of added card

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:15:58 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "05be3488-c6be-4950-ba63-b8e090d9ca15",
  "links" : [ ]
}
Table 103. Response fields
Path Type Description

message

String

Message for response code from Fenige system

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

404 NOT FOUND
HTTP Response - STATUS: E06003
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 169

{
  "status" : "E06003",
  "message" : "Datacenter card not found",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "fc64d9c6-6aa0-4dac-83ac-07c7f1827b2c",
  "links" : [ ]
}
Table 104. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:59 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "d91fa4e4-3b73-4af2-872d-a53f08850e9b"
}
HTTP Response - STATUS: E06000
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 214

{
  "status" : "E06000",
  "message" : "Unrecognized error occurred while connection to Datacenter",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "421a5508-a95d-4e13-965c-eb0090bb9761",
  "links" : [ ]
}
Table 105. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

5.3. Get cards page

POST /client/card/search Content Type: application/json, Authorization: Basic Auth
This method can be use for get a paginated list of Cards object.
Notice that max size of page is equal 100.

5.3.1. Request

HTTP Request
POST /client/card/search?page=0&size=10 HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 149
Host: ecom-staging.fenige.pl

{
  "cardNumber" : "5453131785534417",
  "expirationDate" : "10/24",
  "firstName" : "John",
  "lastName" : "Doe",
  "email" : "john.doe@fenige.pl",
  "createdDateFrom": "2021-05-06T23:24:25.694Z",
  "createdDateTo": "2021-05-06T23:24:25.694Z",
  "lastModifiedDateFrom": "2021-05-06T23:24:25.694Z",
  "lastModifiedDateTo": "2021-05-06T23:24:25.694Z"
}
Table 106. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 107. Search filter request fields
Path Type Constraints Description

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null, @Must not be empty, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expirationDate

String

@Must match the regular expression ^(0[1-9]|1[0-2])\/?([0-9]{2})$, @Must not be empty, @Must not be null

Expiration date of card mm/yy

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null, @Must not be empty, @Must not be null

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null, @Must not be empty, @Must not be null

Last name of card holder

email

String

@Length must be between 1 and 128 inclusive, @Must be a well-formed email address, @Must not be blank, @Must not be null, @Must not be empty, @Must not be null

Cardholder’s email

createdDateFrom

String

@Date in format: yyyy-MM-dd’T’HH:mm:ss.SSS’Z' example: 2020-11-20T13:56:27.156Z

Date of card creation. All Cards will be found that were created after this date

createdDateTo

String

@Date in format: yyyy-MM-dd’T’HH:mm:ss.SSS’Z' example: 2020-11-20T13:56:27.156Z

Date of card creation. All Cards will be found that were created before this date

lastModifiedDateFrom

String

@Date in format: yyyy-MM-dd’T’HH:mm:ss.SSS’Z' example: 2020-11-20T13:56:27.156Z

Date of card edit. All Cards will be found that were edited after this date

lastModifiedDateTo

String

@Date in format: yyyy-MM-dd’T’HH:mm:ss.SSS’Z' example: 2020-11-20T13:56:27.156Z

Date of card edit. All Cards will be found that were edited before this date

Table 108. client/card/search?page={pageNumber}&size={pageSize}
Parameter Description

pageNumber

Number of page starting from zero

pageSize

Size of page, max equal to 100

5.3.2. Response

Response status
Status Description

200 OK

Returned when page was correctly found

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 you are the problem with authorized to your PSP.

422 UNPROCESSABLE ENTITY

STATUS: E06006 - Returned when there was issue with internal Datacenter flow.

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 105

{
    "cards": {
        "content": [
            {
                "cardId": 1,
                "hiddenCardNumber": "545313******4417",
                "firstName": "John",
                "lastName": "Doe",
                "email": "john.doe@fenige.pl",
                "createdDate": "2021-11-19T10:55:56.836Z"
            }
        ],
        "number": 0,
        "size": 10,
        "totalElements": 1,
        "pageable": {
            "sort": {
                "sorted": false,
                "unsorted": true
            },
            "pageSize": 10,
            "pageNumber": 0,
            "offset": 0,
            "unpaged": false,
            "paged": true
        },
        "last": true,
        "totalPages": 1,
        "sort": {
            "sorted": false,
            "unsorted": true
        },
        "first": true,
        "numberOfElements": 1
    },
    "status": "S0000",
    "message": "SUCCESS",
    "httpStatus": "OK"
}
Table 109. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

cards.content[].cardId

Number

Id numeric value of added card

cards.content[].hiddenCardNumber

String

Full cardholder’s masked card number must be between 12-digits and 19-digits

cards.content[].firstName

String

First name of card holder

cards.content[].lastName

String

Last name of card holder

cards.content[].email

String

Cardholder’s email

cards.content[].createdDate

String

Card creation date

cards.content[].lastModifiedDate

String

Last card edit date

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:16:02 GMT
Connection: close
Content-Length: 586

{
  "errors" : {
    "firstName" : [ "length must be between 2 and 35", "must not be blank", "must match \"^[^0-9]+$\"", "must be null" ],
    "lastName" : [ "length must be between 2 and 35", "must be null", "must match \"^[^0-9]+$\"", "must not be blank" ],
    "email" : [ "must be a well-formed email address", "must be null" ],
    "cardNumber" : [ "must be null", "card number must be numeric", "card number length must be between 12 and 19", "invalid card number" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "1ab79f3b-8fa9-4def-9333-7e3acf46eeb0"
}
HTTP Response - STATUS: E06001
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 355

{
    "status": "E06001",
    "message": "Max page size equal to 100",
    "httpStatus": "BAD_REQUEST",
    "traceId": "854dcdce-e784-487c-8a34-f578d5a1c25a"
}
HTTP Response - STATUS: E06002
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
Content-Length: 355

{
    "status": "E06002",
    "message": "Datacenter rejected request. The parameters in the URL seems to be invalid",
    "httpStatus": "BAD_REQUEST",
    "traceId": "854dcdce-e784-487c-8a34-f578d5a1c25a"
}
Table 110. Response fields
Path Type Description

errors.firstName

Array

First name validation error

errors.lastName

Array

Last name validation error

errors.email

Array

Email validation error

errors.cardNumber

Array

Card number validation error

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:15:58 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "05be3488-c6be-4950-ba63-b8e090d9ca15",
  "links" : [ ]
}
Table 111. Response fields
Path Type Description

message

String

Message for response code from Fenige system

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E06006
HTTP/1.1 422 UNPROCESSABLE ENTITY
Content-Type: application/json;charset=UTF-8
Content-Length: 355

{
    "status": "E06006",
    "message": "Exception occurred while trying to paginate ecommerce cards",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "854dcdce-e784-487c-8a34-f578d5a1c25a"
}
Table 112. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:59 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "d91fa4e4-3b73-4af2-872d-a53f08850e9b"
}
HTTP Response - STATUS: E06000
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 214

{
  "status" : "E06000",
  "message" : "Unrecognized error occurred while connection to Datacenter",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "421a5508-a95d-4e13-965c-eb0090bb9761",
  "links" : [ ]
}
Table 113. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

5.4. Update card

PUT /client/card Content Type: application/json, Authorization: Basic Auth
This method allows you to edit the details of a Card that has been added previously.
The request body requires a 'cardId' and any data set. All data is optional.

5.4.1. Request

HTTP Request
PUT /client/card HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 165
Host: ecom-staging.fenige.pl

{
  "cardId" : 1,
  "cardNumber" : "5453131785534417",
  "expirationDate" : "10/24",
  "firstName" : "John",
  "lastName" : "Doe",
  "email" : "john.doe@fenige.pl"
}
Table 114. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 115. Update Card request fields
Path Type Constraints Description

cardId

Number

@Must not be null, @Numeric value

Id numeric value of card existing in database

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expirationDate

String

@Must match the regular expression ^(0[1-9]|1[0-2])\/?([0-9]{2})$, @Must not be empty, @Must not be null

Expiration date of card mm/yy

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null, @Must not be empty

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null, @Must not be empty

Last name of card holder

email

String

@Length must be between 1 and 128 inclusive, @Must be a well-formed email address, @Must not be blank, @Must not be null, @Must not be empty

Cardholder’s email

5.4.2. Response

Response status
Status Description

200 OK

Returned when card was successfully updated.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

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

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 105

{
  "cardId" : 1,
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 116. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

cardId

Number

Id numeric value of added card

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:16:00 GMT
Connection: close
Content-Length: 684

{
  "errors" : {
    "lastName" : [ "must be null", "must not be blank", "must match \"^[^0-9]+$\"", "length must be between 2 and 35" ],
    "firstName" : [ "must match \"^[^0-9]+$\"", "must not be blank", "length must be between 2 and 35", "must be null" ],
    "cardId" : [ "must not be null" ],
    "cardNumber" : [ "invalid card number", "must be null", "card number must be numeric", "card number length must be between 12 and 19" ],
    "email" : [ "must be a well-formed email address", "must be null" ],
    "expirationDate" : [ "invalid card expiration date" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "c077eda0-27af-4c5d-ab69-7740fa01918d"
}
Table 117. Response fields
Path Type Description

errors.cardId

Array

cardId validation error

errors.firstName

Array

First name validation error

errors.lastName

Array

Last name validation error

errors.email

Array

Email validation error

errors.cardNumber

Array

Card number validation error

errors.expirationDate

Array

Expiration date validation error

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:15:58 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "05be3488-c6be-4950-ba63-b8e090d9ca15",
  "links" : [ ]
}
Table 118. Response fields
Path Type Description

message

String

Message for response code from Fenige system

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E06005
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 202

{
  "status" : "E06005",
  "message" : "Update of ecommerce card failed, card not found",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "04a33f11-6469-4193-bea7-cf306c17c72b",
  "links" : [ ]
}
Table 119. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:59 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "d91fa4e4-3b73-4af2-872d-a53f08850e9b"
}
HTTP Response - STATUS: E06000
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 214

{
  "status" : "E06000",
  "message" : "Unrecognized error occurred while connection to Datacenter",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "421a5508-a95d-4e13-965c-eb0090bb9761",
  "links" : [ ]
}
Table 120. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

5.5. Delete card

DELETE /client/card/{cardId} Content Type: application/json, Authorization: Basic Auth
This method is used to remove a card from the Datacenter database that is assigned to the PSP with which you have logged in.

5.5.1. Request

HTTP Request
DELETE /client/card/1 HTTP/1.1
Authorization: Basic dXNlcjpwYXNzd29yZA==
Host: ecom-staging.fenige.pl
Table 121. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 122. client/card/{cardId}
Parameter Description

cardId

Id numeric value of card existing in database

5.5.2. Response

Response status
Status Description

200 OK

Returned when card was successfully removed.

401 UNAUTHORIZED

STATUS: E8002 - Returned when you are the problem with authorized to your PSP.

403 FORBIDDEN

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

500 INTERNAL SERVER ERROR

STATUS: E9000 - Returned when reason is unknown.

200 OK
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 113

{
  "cardRemoved" : true,
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 123. Response fields
Path Type Description

cardRemoved

Boolean

Indicates is card was removed or not

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:15:58 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "05be3488-c6be-4950-ba63-b8e090d9ca15",
  "links" : [ ]
}
Table 124. Response fields
Path Type Description

message

String

Message for response code from Fenige system

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

404 NOT FOUND
HTTP Response - STATUS: E06004
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 202

{
  "status" : "E06004",
  "message" : "Delete of ecommerce card failed, card not found",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "33005a2c-5b4d-4e48-8c06-3e7eca5643cc",
  "links" : [ ]
}
Table 125. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:59 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "d91fa4e4-3b73-4af2-872d-a53f08850e9b"
}
HTTP Response - STATUS: E06000
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 214

{
  "status" : "E06000",
  "message" : "Unrecognized error occurred while connection to Datacenter",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "421a5508-a95d-4e13-965c-eb0090bb9761",
  "links" : [ ]
}
Table 126. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

UUID that helps to identify request in system

6. Payment API

6.1. Currency rate

POST /client/payments/currency-rate Content Type: application/json, Authorization: Basic Auth
This method can be used for calculate Mastercard/Visa currency rates between two values depends on terminal and provider.
Notice that `higherRate` is used to transaction processing.

6.1.1. Request

Mastercard
HTTP request
POST /client/payments/currency-rate HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 124
Host: ecom-staging.fenige.pl

{
  "terminalUuid" : "0bf30810-1e4a-41f0-b86b-0cb232bd0fcb",
  "provider" : "MASTERCARD",
  "from" : "USD",
  "to" : "PLN"
}
Table 127. CURRENCY RATE REQUEST FIELDS
Path Type Constraints Description

terminalUuid

String

@Must not be null

Terminal’s unique uuid in system

provider

String

@Must not be null

VISA or MASTERCARD or MAESTRO

from

String

@Must not be null

Currency code for conversion

to

String

@Must not be null

Target currency of conversion

VISA
HTTP request
POST /client/payments/currency-rate HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 118
Host: ecom-staging.fenige.pl

{
  "terminalUuid" : "0bf30810-1e4a-41f0-b86b-0cb232bd0fcb",
  "provider" : "VISA",
  "from" : "USD",
  "to" : "PLN"
}
Table 128. CURRENCY RATE REQUEST FIELDS
Path Type Constraints Description

terminalUuid

String

@Must not be null

Terminal’s unique uuid in system

provider

String

@Must not be null

VISA or MASTERCARD or MAESTRO

from

String

@Must not be null

Currency code for conversion

to

String

@Must not be null

Target currency of conversion

6.1.2. Response

200 OK
HTTP Response - STATUS: S0000
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 146

{
  "lowerRate" : 0.88000011,
  "higherRate" : 0.89801726,
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 129. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

links

Array

Hateoas links

lowerRate

Number

Lower currency rate

higherRate

Number

Higher currency rate used for process transaction

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 158

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "4957a09e-d1cf-43d2-815b-dc4cfedc43d2",
  "links" : [ ]
}
Table 130. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

links

Array

Hateoas links

traceId

String

Id of trace

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E0190
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 183

{
  "status" : "E0190",
  "message" : "Failed to get currency rates",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "6773f0cb-7f30-487e-9255-7c35f6dc8f5b",
  "links" : [ ]
}
Table 131. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

links

Array

Hateoas links

traceId

String

Id of trace

6.2. Currency for card

POST /client/currency-for-card Content Type: application/json, Authorization: Basic Auth
Method is used to determine currencies applied for given card. If merchant has stored card in DataCenter can you use this method by cardId rather than cardNumber.

6.2.1. Request

Plain card Mastercard
Table 132. CURRENCY FOR CARD REQUEST FIELDS
Path Type Constraints Description

cardNumber

String

@Card number length must be between 12 and 19, @Luhn, @Must not be blank, @Must not be null

Card number

HTTP request
POST /client/currency-for-card HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 39
Host: ecom-staging.fenige.pl

{
  "cardNumber" : "5575168861324712"
}
Table 133. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Plain card Visa
Table 134. CURRENCY FOR CARD REQUEST FIELDS
Path Type Constraints Description

cardNumber

String

@Card number length must be between 12 and 19, @Luhn, @Must not be blank, @Must not be null

Card number

HTTP request
POST /client/currency-for-card HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 39
Host: ecom-staging.fenige.pl

{
  "cardNumber" : "4761340000000050"
}
Table 135. Request headers
Name Description

Authorization

Basic auth credentials for PSP

DataCenter card
Table 136. CURRENCY FOR CARD REQUEST FIELDS
Path Type Constraints Description

cardId

Number

@Must not be null, @Numeric

DataCenter card id.

HTTP request
POST /client/currency-for-card HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 18
Host: ecom-staging.fenige.pl

{
  "cardId" : 1
}
Table 137. Request headers
Name Description

Authorization

Basic auth credentials for PSP

6.2.2. Response

Response status
Status Description

200 OK

STATUS: S0000 Returned when SUCCESS.

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 you are the problem with authorized to your PSP.

422 UNPROCESSABLE ENTITY

STATUS: E0401 - Issuer card is not supported.

500 INTERNAL SERVER ERROR

STATUS: E0400 - Returned when failed to get currency for card.

200 OK
HTTP Response - STATUS: S0000
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 224

{
  "defaultCurrency" : "PLN",
  "currencyCodes" : [ "PLN", "EUR", "USD" ],
  "provider" : "MASTERCARD",
  "countryCodeNumeric" : "616",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "links" : [ ]
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 216

{
  "defaultCurrency" : "UNDEFINED",
  "currencyCodes" : [ "UNDEFINED" ],
  "provider" : "VISA",
  "countryCodeNumeric" : "616",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "links" : [ ]
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 190

{
  "defaultCurrency" : "UNDEFINED",
  "currencyCodes" : [ "UNDEFINED" ],
  "provider" : "MASTERCARD",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 138. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

links

Array

Hateoas links

currencyCodes

Array

Currencies supported by card

defaultCurrency

String

Default currency code for card

provider

String

Card’s provider: MASTERCARD, MAESTRO, VISA, UNKNOWN

countryCodeNumeric

String

Country code numeric for Mastercard/Visa:

- ISO 3166-1 Numeric

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:05 GMT
Connection: close
Content-Length: 214

{
  "errors" : {
    "cardNumber" : [ "must not be blank", "must not be empty", "must not be null" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "cd3ee71b-479e-4cfa-a975-de2f178521ed"
}
Table 139. Response fields
Path Type Description

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 158

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "cd65f5af-ef80-496a-a97a-df5d8583ceba",
  "links" : [ ]
}
Table 140. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

links

Array

Hateoas links

traceId

String

Id of trace

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E8002
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 168

{
"status": "E0401",
"message": "Issuer card is not supported",
"httpStatus": "UNPROCESSABLE_ENTITY",
"traceId": "cf77afc8-f41b-425c-ab6a-de4eb9a69136",
"links" : [ ]
}
Table 141. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

links

Array

Hateoas links

traceId

String

Id of trace

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9001
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:03 GMT
Connection: close
Content-Length: 161

{
  "status" : "E9001",
  "message" : "Error acquirer connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "4574e22f-d368-46d0-91d5-42208ddb9e44"
}
Table 142. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

6.3. Card provider

POST /client/card/provider Content Type: application/json, Authorization: Basic Auth
    This method is used to check the card provider, for example: VISA or MASTERCARD. If merchant has stored card in DataCenter can you use this method by cardId rather than
cardNumber.

6.3.1. Request

Table 143. Request fields
Path Type Constraints Description

cardNumber

String

@Card number length must be between 12 and 19, @Luhn, @Must not be blank, @Must not be null

PAN card number

HTTP request
POST /client/card/provider HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 58
Host: ecom-staging.fenige.pl

{
  "cardNumber" : "5117964247989169",
  "cardId" : null
}
Table 144. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Plain card
Table 145. Request fields
Path Type Constraints Description

cardNumber

String

@Card number length must be between 12 and 19, @Luhn, @Must not be blank, @Must not be null

PAN card number

HTTP request
POST /client/card/provider HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 58
Host: ecom-staging.fenige.pl

{
  "cardNumber" : "5117964247989169",
  "cardId" : null
}
Table 146. Request headers
Name Description

Authorization

Basic auth credentials for PSP

DataCenter card
Table 147. Request fields
Path Type Constraints Description

cardId

Number

@Must not be null, @Numeric

DataCenter card id.

HTTP request
POST /client/card/provider HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 43
Host: ecom-staging.fenige.pl

{
  "cardNumber" : null,
  "cardId" : 231
}
Table 148. Request headers
Name Description

Authorization

Basic auth credentials for PSP

6.3.2. Response

200 OK
HTTP Response - STATUS: S0000
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 118

{
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "provider" : "MASTERCARD",
  "links" : [ ]
}
Table 149. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

links

Array

Hateoas links

provider

String

Card’s provider: MASTERCARD, MAESTRO, VISA, UNKNOWN

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=ISO-8859-1
Content-Length: 158

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "77106b49-330c-4063-936f-859a58d3c325",
  "links" : [ ]
}
Table 150. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

links

Array

Hateoas links

traceId

String

Id of trace

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "cef3379a-4e1a-4ac2-a553-edf732dd57e2",
  "links" : [ ]
}
Table 151. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

links

Array

Hateoas links

traceId

String

Id of trace

503 SERVICE UNAVAILABLE
HTTP Response - STATUS: E90002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 173

{
  "status" : "E9002",
  "message" : "Error mpi connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "38b3db63-ad54-43d6-acf1-408c04cdf2e4",
  "links" : [ ]
}
Table 152. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

links

Array

Hateoas links

traceId

String

Id of trace

6.4. Payment

POST /client/payments/auth Content Type: application/json, Authorization: Basic Auth
The method is used to charge the cardholder.
Using this method, we can authorize and process entire transaction. This method supports both 3DS and without 3DS transactions. You can also use this method using the outside 3ds authorization.
How the transaction will be initiated depends on the terminal settings (look at 'is3dsEnable' field).
This endpoint is idempotent so if you execute more than one requests with the same data even at the same time, only first registered transaction will be processed further. In
response, we receive transaction status.
The Fenige Payment API methods optionally allows merchants to store card data and sensitive personal data in order to allow performing subsequent transactions.
If merchant decides to use DataCenter transaction flow then is required to provide the card id of the card previously stored in the Fenige DataCenter, from which card the
relevant required parameters will be downloaded and used for authorization.
Card data and sensitive personal data according to the Fenige API specification are: cardNumber, expiryDate, firstName, lastName and email.
All card data are stored securely on Fenige DataCenter servers in accordance with applicable security requirements.

From January 2021, there is an internal functionality to restrict access for the PSP to specific method. The Fenige employee can disable access to a given endpoint, then the HTTP status 403 FORBIDDEN will be returned. The PSP will be informed about each access restriction action.

Mastercard and Visa requires for intra-European Economic Area (EEA), plus United Kingdom, for which EMV 3DS must be used subsequent to a valid authorization soft decline DE39=65. To perform a transaction for which the card has previously received CODE_65, the transaction must be processed with full EMV 3DS (3DS 2.x) and the authentication status must be 'Y'.

Correct flow:

  • 3DS 2.x → Challenge → Authentication status Y → Transaction (Recommended)

  • 3DS 2.x → Card number not Enrolled in 3DS v2 → 3DS 1.0 → Transaction (Recommended)

  • 3DS 1.0 → Authentication status Y/A → Transaction → CODE_65 → 3DS 2.x → Challenge → Authentication status Y → Transaction (Not recommended)

  • non3DS → Transaction → CODE_65 → 3DS 2.x → Challenge → Authentication status Y → Transaction (Available only to selected merchants)

soft decline Code 65 EMV 3DS
E-commerce payment with outside 3DS flow
ecommerce trx flow with outside3ds
E-commerce payment payment with DataCenter and outside 3DS flow
ecommerce datacenter trx flow
E-commerce payment flow
ecommerce trx flow
E-commerce payment with DataCenter card flow
ecommerce data center trx flow
E-commerce payment with 3ds flow
ecommerce trx 3ds flow

6.4.1. Request

Request - outside 3DS 2.X
HTTP Request
POST /client/payments/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 680
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "ef93a03f-5e83-497f-b106-c804f197b6cb",
  "requestUuid" : "6924344b-01cf-4126-b019-0408f040716a",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "outside3ds" : {
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
    "cavvAlgorithm" : "01",
    "eci" : "02",
    "authenticationStatus" : "Y",
    "transactionXId" : "d543820d-683e-4589-86d9-6c9e40db4b53"
  },
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 153. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 154. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

Last name of card holder

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

outside3ds

Object

There are outside 3ds data authorization that have been send to our API

outside3ds.cavv

String

@Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value.

outside3ds.transactionXId

String

Server transaction Id generated by DS. Required for 3DS 2.x version. The transactionXId is the field that defines the 3DS version. The presence of this field in the HTTP request specifies that the transaction will be processed with 3DS 2.x. TransactionXId can be obtained by executing the /authentication method.

outside3ds.cavvAlgorithm

String

@Length must be between 1 and 2 inclusive, @Must match the regular expression ^\d+$

Indicates the algorithm used to generate the AuthenticationCAVV value

0 - HMAC

1 - CVV

2 - CVV with ATN

3 - MasterCard SPA algorithm

outside3ds.eci

String

@Length must be between 1 and 2 inclusive, @Must match 01 or 02 or 05 or 06, @Must not be null

Electronic Commerce Indicator: 5 (Visa) or 2 (SecureCode) - The cardholder was successfully authenticated. 6 (Visa) or 1 (SecureCode) - Authentication was attempted, but the cardholder was not enrolled. Chargeback protection applies.

outside3ds.authenticationStatus

String

@Must match Y or A, @Must not be null

Authentication status:

Y - (Full Authentication) - The customer was successfully authenticated.

A - (Successful Attempted Authentication) - Authentication was not available, but functionality was available to generate a proof of authentication attempt.

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Request - outside 3DS 2.X with forced terminal
HTTP Request
POST /client/payments/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 739
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "ef93a03f-5e83-497f-b106-c804f197b6cb",
  "terminalUuid" : "9f4054f0-197b-4869-92a9-f60f7946a268",
  "requestUuid" : "1f46e414-eae3-405f-b41b-82be1931d2b5",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "outside3ds" : {
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
    "cavvAlgorithm" : "01",
    "eci" : "02",
    "authenticationStatus" : "Y",
    "transactionXId" : "d543820d-683e-4589-86d9-6c9e40db4b53"
  },
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 155. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 156. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

terminalUuid

String

Request’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

Last name of card holder

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

outside3ds

Object

There are outside 3ds data authorization that have been send to our API

outside3ds.cavv

String

@Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3ds.transactionXId

String

Cardholder Authentication Verification Value. The transactionXId is the field that defines the 3DS version.The presence of this field in the HTTP request specifies that the transaction will be processed with 3DS 2.x.TransactionXId can be obtained by executing the /authentication method.

outside3ds.cavvAlgorithm

String

@Length must be between 1 and 2 inclusive, @Must match the regular expression ^\d+$

Indicates the algorithm used to generate the AuthenticationCAVV value

0 - HMAC

1 - CVV

2 - CVV with ATN

3 - MasterCard SPA algorithm

outside3ds.eci

String

@Length must be between 1 and 2 inclusive, @Must match 01 or 02 or 05 or 06, @Must not be null

Electronic Commerce Indicator: 5 (Visa) or 2 (SecureCode) - The cardholder was successfully authenticated. 6 (Visa) or 1 (SecureCode) - Authentication was attempted, but the cardholder was not enrolled. Chargeback protection applies.

outside3ds.authenticationStatus

String

@Must match Y or A, @Must not be null

Authentication status:

Y - (Full Authentication) - The customer was successfully authenticated.

A - (Successful Attempted Authentication) - Authentication was not available, but functionality was available to generate a proof of authentication attempt.

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03.

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Request - outside 3DS 1.0
HTTP Request
POST /client/payments/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 617
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "ef93a03f-5e83-497f-b106-c804f197b6cb",
  "requestUuid" : "2b7b237a-1cf1-49a7-b45b-0f179a8582b4",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "outside3ds" : {
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
    "cavvAlgorithm" : "01",
    "eci" : "02",
    "authenticationStatus" : "Y"
  },
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 157. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 158. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

Last name of card holder

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

outside3ds

Object

There are outside 3ds data authorization that have been send to our API

outside3ds.cavv

String

@Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value.

outside3ds.cavvAlgorithm

String

@Length must be between 1 and 2 inclusive, @Must match the regular expression ^\d+$

Indicates the algorithm used to generate the AuthenticationCAVV value

0 - HMAC

1 - CVV

2 - CVV with ATN

3 - MasterCard SPA algorithm

outside3ds.eci

String

@Length must be between 1 and 2 inclusive, @Must match 01 or 02 or 05 or 06, @Must not be null

Electronic Commerce Indicator: 5 (Visa) or 2 (SecureCode) - The cardholder was successfully authenticated. 6 (Visa) or 1 (SecureCode) - Authentication was attempted, but the cardholder was not enrolled. Chargeback protection applies.

outside3ds.authenticationStatus

String

@Must match Y or A, @Must not be null

Authentication status:

Y - (Full Authentication) - The customer was successfully authenticated.

A - (Successful Attempted Authentication) - Authentication was not available, but functionality was available to generate a proof of authentication attempt.

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Request - outside 3DS 1.0 with forced terminal
HTTP Request
POST /client/payments/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 676
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "ef93a03f-5e83-497f-b106-c804f197b6cb",
  "terminalUuid" : "9f4054f0-197b-4869-92a9-f60f7946a268",
  "requestUuid" : "6ebc97da-4966-451e-b61c-8007e8d2124f",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "outside3ds" : {
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
    "cavvAlgorithm" : "01",
    "eci" : "02",
    "authenticationStatus" : "Y"
  },
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 159. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 160. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

terminalUuid

String

Request’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

Last name of card holder

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

outside3ds

Object

There are outside 3ds data authorization that have been send to our API

outside3ds.cavv

String

@Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3ds.cavvAlgorithm

String

@Length must be between 1 and 2 inclusive, @Must match the regular expression ^\d+$

Indicates the algorithm used to generate the AuthenticationCAVV value

0 - HMAC

1 - CVV

2 - CVV with ATN

3 - MasterCard SPA algorithm

outside3ds.eci

String

@Length must be between 1 and 2 inclusive, @Must match 01 or 02 or 05 or 06, @Must not be null

Electronic Commerce Indicator: 5 (Visa) or 2 (SecureCode) - The cardholder was successfully authenticated. 6 (Visa) or 1 (SecureCode) - Authentication was attempted, but the cardholder was not enrolled. Chargeback protection applies.

outside3ds.authenticationStatus

String

@Must match Y or A, @Must not be null

Authentication status:

Y - (Full Authentication) - The customer was successfully authenticated.

A - (Successful Attempted Authentication) - Authentication was not available, but functionality was available to generate a proof of authentication attempt.

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03.

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Request - inside 3DS 1.0
HTTP Request
POST /client/payments/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 469
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "9c37fcca-00bc-4a4c-a311-0e76eefe3c2c",
  "requestUuid" : "e502635e-694d-417c-afe5-49a5fa602153",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 161. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 162. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

First name of card holder

lastName

String

Last name of card holder

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardNumber

String

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Request - forced Terminal
HTTP Request
POST /client/payments/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 547
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "ef93a03f-5e83-497f-b106-c804f197b6cb",
  "terminalUuid" : "93a81ea5-87d3-4448-a274-be030eb51b9c",
  "requestUuid" : "05307b23-df1a-49f4-8796-25bfab3df7a1",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "cardId" : null,
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 163. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 164. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

First name of card holder

lastName

String

Last name of card holder

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardNumber

String

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

terminalUuid

String

Terminals’s unique uuid in system

Request - DataCenter card
HTTP Request
POST /client/payments/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 347
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "3f957dab-1dcb-43b8-b7e6-546a72b04b56",
  "requestUuid" : "3fdd0f9a-c4fe-455b-934f-27940d60908b",
  "amount" : 1000,
  "currency" : "USD",
  "cardId" : 1906455,
  "cvc2" : "123",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 165. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 166. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardId

Number

@Must not be null, @Numeric

DataCenter card id. Required to obtain card information data from DataCenter such as (cardNumber, expiryDate, firstName, lastName, email)

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

6.4.2. Response

Response status
Status Description

200 OK

Returned when transaction was successfully authorized.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

STATUS: E8001 - Returned when server understood the request but refuses to authorize 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

STATUS: E06003 - Returned when DataCenter card was not found.

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: E01580 - Returned when transaction is rejected, because DataCenter card was expired.

STATUS: E01581 - Returned when transaction is rejected, because not found Card Authentication (3DS 2.X)

STATUS: E01582 - Returned when transaction is rejected, because Card Authentication not match to transaction type (3DS 2.X)

STATUS: E01594 - Returned when transaction is rejected, because transactionXId parameter had registered for another transaction

STATUS: E01596 - Returned when transaction is rejected, because terminal has blocked transaction with card issued in restricted country

STATUS: E01597 - Returned when transaction is rejected, because 3DS version of terminal are not compatible with 3DS version defined in request

STATUS: E01600 - Transaction declined, 3DS 2.X flow invoked for other card number than specified in the request

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: 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

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.

STATUS: E9010 - Returned when is error DataCenter connection.

200 OK
HTTP Response - transaction without 3DS and with outside3DS
{
  "requestUuid" : "38f8212b-c192-4e92-8e47-439c77a54ff5",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "status" : "S0002",
  "message" : "Success transaction",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 167. Response fields
Path Type Description

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

responseCode

String

Response code

links

Array

Links to other resources

200 OK (with 3DS)
HTTP Response - transaction with 3DS
{
  "requestUuid" : "48849be7-9f13-409a-8fb9-77ffb07ea0b0",
  "transactionStatus" : "WAITING_ON_3DS_CONFIRMATION",
  "pareq" : "eJxlkltvwjAMhf8K4p3m0qRUlYnE4GHVxMQuT3uLWguK2lDSFsG/n8NlbFqkSD6Oe+p8DnxuPeLyA4vBo4EVdp3d4KgqZ2M5lWpsYD1/x4OBI/qu2jsjIh5JYHdJX/hia11vwBaHp/zVaCVEooDdJDTo86XhtCa0BbBrApxt0HToStUgsIuCYj+43p9NIhJgdwGDr82279suY2xnj3ZS4hFrEQ2trcqorbNUqZgVdYWuBxaqgT3aWg8h6sj9VJUmX8w3//Yyj1e7txmwUAGl7dFILlIeSz4SOlM60ymwSx5sE9oyi6+XUax5xDnd9JqCNvxpfhV0Fo5+p4AQe3TFmcxjut5dAZ7avaPeDXH9iYE9Gl88B7pFT9jiADIsRSxpQKlKtNRqmsiUkN2KgmNF5CTn+mIZBLBgw27jJECXSVP05wV8A1/aqWQ=",
  "acsUrl" : "https://ecom-staging.fenige.pl/fenige-mpi",
  "md" : "ZTkwYjU3N2YtNzU5Ny00ZWM5LWE2MDAtZjQ4YWVmZDgzMjhm",
  "formBase64" : "PGh0bWw+PFNDUklQVCBMQU5HVUFHRT0iSmF2YXNjcmlwdCI+ZnVuY3Rpb24gT25Mb2FkRXZlbnQoKXsgZG9jdW1lbnQuZG93bmxvYWRGb3JtLnN1Ym1pdCgpOyB9PC9TQ1JJUFQ+PGJvZHkgT25Mb2FkPSJPbkxvYWRFdmVudCgpOyI+PGZvcm0gbmFtZT0iZG93bmxvYWRGb3JtIiBhY3Rpb249Imh0dHBzOi8vamF2YS1kZXZlbC5mZW5pZ2UucGw6ODE4MS9mZW5pZ2UtbXBpIiBtZXRob2Q9IlBPU1QiPjxJTlBVVCB0eXBlPSJoaWRkZW4iIG5hbWU9IlBhUmVxIiB2YWx1ZT0iZUp4bGtsdHZ3akFNaGY4SzRwM20wcVJVbFluRTRHSFZ4TVF1VDN1TFdndUsybERTRnNHL244TmxiRnFrU0Q2T2UrcDhEbnh1UGVMeUE0dkJvNEVWZHAzZDRLZ3FaMk01bFdwc1lEMS94NE9CSS9xdTJqc2pJaDVKWUhkSlgvaGlhMTF2d0JhSHAvelZhQ1ZFb29EZEpEVG84NlhodENhMEJiQnJBcHh0MEhUb1N0VWdzSXVDWWorNDNwOU5JaEpnZHdHRHI4MjI3OXN1WTJ4bmozWlM0aEZyRVEydHJjcW9yYk5VcVpnVmRZV3VCeGFxZ1QzYVdnOGg2c2o5VkpVbVg4dzMvL1l5ajFlN3R4bXdVQUdsN2RGSUxsSWVTejRTT2xNNjB5bXdTeDVzRTlveWk2K1hVYXg1eERuZDlKcUNOdnhwZmhWMEZvNStwNEFRZTNURm1jeGp1dDVkQVo3YXZhUGVEWEg5aVlFOUdsODhCN3BGVDlqaUFESXNSU3hwUUtsS3ROUnFtc2lVa04yS2dtTkY1Q1RuK21JWkJMQmd3MjdqSkVDWFNWUDA1d1Y4QTEvYXFXUT0iPjxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9IlRlcm1VcmwiIHZhbHVlPSJodHRwOi8vbG9jYWxob3N0OjgwODEvY2xpZW50L3BheW1lbnRzL3Rlcm1pbmF0ZSI+PGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iTUQiIHZhbHVlPSJaVGt3WWpVM04yWXROelU1TnkwMFpXTTVMV0UyTURBdFpqUTRZV1ZtWkRnek1qaG0iPjwvZm9ybT48L2JvZHk+PC9odG1sPg==",
  "enrolledStatus" : "Y",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 168. Response fields
Path Type Description

status

String

Status of transaction

message

String

Message describe transaction result

httpStatus

String

Status of request

requestUuid

String

Unique request UUID

transactionStatus

String

Transaction status

pareq

String

Payer Authentication Request

acsUrl

String

Fully qualified URL of an Access Control Server

md

String

Correlation id in base64 format

formBase64

String

HTML form encoded by Base64 algorithm

enrolledStatus

String

Status of 3DS transaction

links

Array

Links to other resources

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:12:20 GMT
Connection: close
Content-Length: 621

{
  "errors" : {
    "expiryDate" : [ "invalid card expiration date" ],
    "lastName" : [ "must not be null", "must not be blank" ],
    "firstName" : [ "must not be null", "must not be blank" ],
    "amount" : [ "must not be null" ],
    "merchantUuid" : [ "must not be null" ],
    "requestUuid" : [ "must not be null" ],
    "currency" : [ "must not be null" ],
    "cvc2" : [ "must not be null", "must not be blank" ],
    "cardNumber" : [ "must not be blank", "must not be null", "must not be empty" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "9e066c07-6c24-4a2d-8fcc-571f2854cc16"
}
Table 169. Response fields
Path Type Description

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

HTTP Response - STATUS: E8000 - DataCenter 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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:12:19 GMT
Connection: close
Content-Length: 679

{
  "errors" : {
    "expiryDate" : [ "Card id was provided, expiryDate is obtained from data center card: 1906455" ],
    "firstName" : [ "Card id was provided, firstName is obtained from data center card: 1906455" ],
    "lastName" : [ "Card id was provided, lastName is obtained from data center card: 1906455" ],
    "cardId" : [ "Please provide cardId for DATACENTER transaction or fields: cardNumber, expiryDate, firstName, lastName for PLAIN transaction" ],
    "cardNumber" : [ "Card id was provided, cardNumber is obtained from data center card: 1906455" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "4fe993fc-7478-4126-904c-972a0b0e0318"
}
Table 170. Response fields
Path Type Description

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:12:19 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "75202170-339c-4534-8a34-90f78b7c32b0",
  "links" : [ ]
}
Table 171. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:12:20 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "05bd3c6e-339d-4781-b263-ecd0a815ac1b",
  "links" : [ ]
}
Table 172. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0122
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 163

{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "d43b81d3-b406-468b-9eb1-7c7f145b8999",
  "links" : [ ]
}
HTTP Response - STATUS: E0132
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 163

{
  "status" : "E0132",
  "message" : "Terminal not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "14be948d-be15-4b8a-a9ad-a8a8c36cf36f",
  "links" : [ ]
}
Table 173. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

HTTP Response - STATUS: E0135
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 180

{
  "status" : "E0137",
  "message" : "Default terminal not exist",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "4c190474-4ebd-4057-bc35-490cb4319671",
  "links" : [ ]
}
Table 174. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

HTTP Response - STATUS: E0137
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 176

{
  "status" : "E0135",
  "message" : "Terminals for merchant not exists",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "bfda7781-fbf1-4556-9eaf-ef724981f19c",
  "links" : [ ]
}
Table 175. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

HTTP Response - STATUS: E06003
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 263

{
  "requestUuid" : "3da57bbd-eca6-49e9-9622-b14e2382d9b1",
  "transactionStatus" : "REJECTED",
  "status" : "E06003",
  "message" : "Datacenter card not found",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "21e9d507-3def-4e22-a44d-2593b5a327ca",
  "links" : [ ]
}
Table 176. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E0150
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 268

{
  "requestUuid" : "ea24c2cc-741e-4452-b3cb-d66e25d6d422",
  "transactionStatus" : "REJECTED",
  "status" : "E0150",
  "message" : "Transaction rejected",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "cb8c4aad-5eed-408f-a4b9-8bb04d4d81b7",
  "links" : [ ]
}
HTTP Response - STATUS: E0151
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 292

{
  "requestUuid" : "8f8dd814-bffb-4d81-b5cc-3d496a22c678",
  "transactionStatus" : "REJECTED",
  "status" : "E0151",
  "message" : "Transaction rejected, currency not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "1cba1c9e-fad8-4b9b-97ca-6d3bf6509b22",
  "links" : [ ]
}
HTTP Response - STATUS: E0152
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 295

{
  "requestUuid" : "5cd5be1e-f031-4ae9-a009-7b289a1d7b1a",
  "transactionStatus" : "REJECTED",
  "status" : "E0152",
  "message" : "Transaction rejected, issuer card not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "07d66c5b-f1fa-46b4-a512-ac4ad76d8fab",
  "links" : [ ]
}
HTTP Response - STATUS: E01580
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 299

{
  "requestUuid" : "980ab5f0-b0f0-491f-8b31-bd1c2e6f32db",
  "transactionStatus" : "REJECTED",
  "status" : "E01580",
  "message" : "Transaction rejected. Data center card is expired.",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "094a12ac-0f3b-4362-8b3d-728f8934b045",
  "links" : [ ]
}
HTTP Response - STATUS: E0200
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "requestUuid" : "5581fb89-14c6-4ddb-951f-d3ef2836eb4f",
  "transactionStatus" : "REJECTED",
  "status" : "E0200",
  "message" : "Transaction rejected, card is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "879d328c-5d06-4278-8b6d-ea1319fdd7de",
  "links" : [ ]
}
HTTP Response - STATUS: E0201
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 284

{
  "requestUuid" : "5c895673-9743-4407-8dc2-b067640557d6",
  "transactionStatus" : "REJECTED",
  "status" : "E0201",
  "message" : "Transaction rejected, bin is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "0fdc01c1-6ce1-469f-8cf5-dddfdbc9b6b9",
  "links" : [ ]
}
HTTP Response - STATUS: E0202
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 289

{
  "requestUuid" : "b37804d3-4bb7-4b52-9a32-7b521e4f7b21",
  "transactionStatus" : "REJECTED",
  "status" : "E0202",
  "message" : "Transaction rejected, terminal is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "35c7955c-6e51-4886-a933-aaecc47123f0",
  "links" : [ ]
}
HTTP Response - STATUS: E0204
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 289

{
  "requestUuid" : "adcbe33c-19a5-4516-ab4a-a06d79f726aa",
  "transactionStatus" : "REJECTED",
  "status" : "E0204",
  "message" : "Transaction rejected, user is on aml list",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "c73df32a-8037-4f1e-8aed-5160994a611c",
  "links" : [ ]
}
HTTP Response - STATUS: E0205
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "requestUuid" : "7fc10d32-72df-42df-991e-7fcd4ae7a8fd",
  "transactionStatus" : "REJECTED",
  "status" : "E0205",
  "message" : "Transaction rejected, bank is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "591dcb51-4d85-4289-9ee2-cb402c60ce3c",
  "links" : [ ]
}
HTTP Response - STATUS: E0206
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 317

{
  "requestUuid" : "6158b027-e4bc-4a86-9814-79467cba2190",
  "transactionStatus" : "REJECTED",
  "status" : "E0206",
  "message" : "Transaction rejected, to many reject transactions and card is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "5d28d1bf-742e-4e09-9fa1-5cad9d78b8e9",
  "links" : [ ]
}
HTTP Response - STATUS: E01594
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 334

{
  "requestUuid" : "f0997ede-b53a-4e48-8552-096153301226",
  "transactionStatus" : "REJECTED",
  "status" : "E01594",
  "message" : "Transaction rejected, transactionXId parameter had registered for another transaction",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "e1b4f7e6-2111-4830-abfb-2bbce3a62d83",
  "links" : [ ]
}
HTTP Response - STATUS: E01596
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 338

{
  "requestUuid" : "48406b13-8fdd-41d7-b2ad-ca9df2ef745c",
  "transactionStatus" : "REJECTED",
  "status" : "E01596",
  "message" : "Transaction rejected, terminal blocks transactions with card issued in given card country",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "427ab048-cf59-4897-a356-4f8c45dad24a",
  "links" : [ ]
}
HTTP Response - STATUS: E01597
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 386

{
  "requestUuid" : "5360881b-9dcc-44b9-94b8-95d336b9a9b2",
  "transactionStatus" : "REJECTED",
  "status" : "E01597",
  "message" : "Transaction rejected, 3DS version of terminal are not compatible with 3DS version defined in request. Please contact the sales department",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "2db61b2a-312a-4adc-8617-ffebd9db6298",
  "links" : [ ]
}
HTTP Response - STATUS: E01598
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 315

{
  "requestUuid" : "01c123c6-4857-461c-94f0-308cc0f0cb95",
  "transactionStatus" : "REJECTED",
  "status" : "E01598",
  "message" : "Transaction rejected, ECI value is not available for card provider",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "540fecdb-4538-4f62-ba82-1806ab9aae62",
  "links" : [ ]
}
Table 177. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

HTTP Response - STATUS: E01600
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 343

{
  "requestUuid" : "e4b9e04b-9924-4bfd-869a-1c887233d2c4",
  "transactionStatus" : "REJECTED",
  "status" : "E01600",
  "message" : "Transaction declined, 3DS 2.X flow invoked for other card number than specified in the request",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "a4ec5eaa-5cfe-4929-acf8-b3a240ca2cf0",
  "links" : [ ]
}
Table 178. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E0142
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 200

{
  "status" : "E0142",
  "message" : "Commission configuration not add for terminal",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "f582af57-f24c-4e40-91cf-57b31720fd53",
  "links" : [ ]
}
HTTP Response - STATUS: E0153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 297

{
  "requestUuid" : "f7e86dc5-27e9-469d-b74c-d807cdb6ce82",
  "transactionStatus" : "PENDING",
  "status" : "E0153",
  "message" : "Transaction declined, problem with MIP connection",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "7e1ad37d-3a34-4088-9745-b37aef53aa2f",
  "links" : [ ]
}
HTTP Response - STATUS: E01599
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 290

{
  "requestUuid" : "a23ca570-bc2b-43e4-b3a8-b4c73a72d13b",
  "transactionStatus" : "DECLINED",
  "status" : "E01599",
  "message" : "Transaction declined, processing timeout",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "71afd7d9-9a36-4b4b-8576-61f4dbfe0bc6",
  "links" : [ ]
}
HTTP Response - STATUS: E0190
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 183

{
  "status" : "E0190",
  "message" : "Failed to get currency rates",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "b1236889-4c8d-4b0d-bc0a-e89be6da1bd9",
  "links" : [ ]
}
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:14:04 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "5c57a621-3342-4fb5-b16f-3a855124aa85"
}
HTTP Response - STATUS: E9008
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 282

{
  "requestUuid" : "fbdda585-6ad6-4905-86cb-945a7b32beab",
  "transactionStatus" : "DECLINED",
  "status" : "E9008",
  "message" : "Error mpi - 3ds initialize failed",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "de1a1a74-a688-4a53-938c-f0af700cffad",
  "links" : [ ]
}
Table 179. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

503 SERVICE UNAVAILABLE
HTTP Response - STATUS: E9001
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:03 GMT
Connection: close
Content-Length: 161

{
  "status" : "E9001",
  "message" : "Error acquirer connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "4574e22f-d368-46d0-91d5-42208ddb9e44"
}
HTTP Response - STATUS: E9002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 267

{
  "requestUuid" : "add00017-600e-450a-b982-0d6ed28f1ce1",
  "transactionStatus" : "DECLINED",
  "status" : "E9002",
  "message" : "Error mpi connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "b3d94184-0ed8-4ab4-9fca-af86e5a433fd",
  "links" : [ ]
}
HTTP Response - STATUS: E9010
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 275

{
  "requestUuid" : "ce1eb091-ef70-4c67-b399-0879e686308c",
  "transactionStatus" : "REJECTED",
  "status" : "E9010",
  "message" : "Error data center connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "9b554863-f243-4b11-9dbe-782ca1762675",
  "links" : [ ]
}
Table 180. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

6.5. MO/TO payment

POST /client/payments/moto/auth Content Type: application/json, Authorization: Basic Auth
MO/TO is a type of transaction where the customer makes a purchase in the merchant's shop by phone or e-mail. All required transactional data are obtained through a call to
the merchant's consultant and sensitive data, e.g. by typing cvc, expiry date, card number on the phone keypad.
The MO/TO transaction has two possible types of authentication: CVC (using the card's cvc) or AVS (using the cardholder's address - postcode and address e.g. house number).
The Fenige Payment API methods optionally allows merchants to store card data and sensitive personal data in order to allow performing subsequent transactions.
If merchant decides to use DataCenter transaction flow then is required to provide the card id of the card previously stored in the Fenige DataCenter, from which card the
relevant required parameters will be downloaded and used for authorization.
Card data and sensitive personal data according to the Fenige API specification are: cardNumber, expiryDate, firstName, lastName and email.
All card data are stored securely on Fenige DataCenter servers in accordance with applicable security requirements.

From January 2021, there is an internal functionality to restrict access for the PSP to specific method. The Fenige employee can disable access to a given endpoint, then the HTTP status 403 FORBIDDEN will be returned. The PSP will be informed about each access restriction action.

MO/TO payment with outside 3DS flow
ecommerce moto with outside3ds trx flow
MO/TO payment with DataCenter and outside 3DS flow
ecommerce moto data center trx with outside3ds flow
MO/TO payment flow
ecommerce moto trx flow
MO/TO payment with DataCenter flow
ecommerce moto data center trx flow

6.5.1. Request

MO/TO CVC
HTTP Request
POST /client/payments/moto/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 491
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "9c37fcca-00bc-4a4c-a311-0e76eefe3c2c",
  "requestUuid" : "9edceaf0-608f-495c-bbd3-07d33d32db12",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "email" : "test@fenige.pl",
  "motoType" : "CVC",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 181. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 182. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

Last name of card holder

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be null when MO/TO CVC

Cardholder’s card cvc2. Required only when moto verification type (motoType) is set to CVC value

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

motoType

String

@Must not be null

Allows to switch between CVC and AVS (Address Verification) methods of authentication

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

MO/TO CVC - forced Terminal
HTTP Request
POST /client/payments/moto/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 550
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "a3eaa4c1-ca5b-406d-b411-82d7780bbd53",
  "terminalUuid" : "d9a807ca-ab63-4ebb-92ce-da4418e0428d",
  "requestUuid" : "e433a97a-d247-4f18-b83c-dd4d139079a9",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "email" : "test@fenige.pl",
  "motoType" : "CVC",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 183. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 184. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

terminalUuid

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

Terminals’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

Last name of card holder

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be null when MO/TO CVC

Cardholder’s card cvc2. Required only when moto verification type (motoType) is set to CVC value

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

motoType

String

@Must not be null

Allows to switch between CVC and AVS (Address Verification) methods of authentication

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

MO/TO AVS
HTTP Request
POST /client/payments/moto/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 531
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "9c37fcca-00bc-4a4c-a311-0e76eefe3c2c",
  "requestUuid" : "7352c0c5-7b7f-4053-8660-5b801ccbf80c",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "email" : "test@fenige.pl",
  "motoType" : "AVS",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "clientPostalCode" : "24-110",
  "clientAddress" : "5",
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 185. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 186. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

Last name of card holder

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

motoType

String

@Must not be null

Allows to switch between CVC and AVS (Address Verification) methods of authentication

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

clientPostalCode

String

@Length must be between 1 and 10 inclusive, @Must not be blank, @Must not be null when AVS

Client postal code required in AVS service to authorize cardholder in bank issuer during MO/TO transaction

clientAddress

String

@Must not be null when AVS

Client address (e.g. house number) required in AVS service to authorize cardholder in bank issuer during MO/TO transaction

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

MO/TO AVS - forced Terminal
HTTP Request
POST /client/payments/moto/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 590
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "a3eaa4c1-ca5b-406d-b411-82d7780bbd53",
  "terminalUuid" : "d9a807ca-ab63-4ebb-92ce-da4418e0428d",
  "requestUuid" : "26314434-eb7b-4fd0-a58d-fce968d045c1",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "email" : "test@fenige.pl",
  "motoType" : "AVS",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "clientPostalCode" : "24-110",
  "clientAddress" : "5",
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 187. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 188. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

terminalUuid

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

Terminals’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

First name of card holder

lastName

String

@Length must be between 2 and 35, @Must match the regular expression [0-9]+$, @Must not be blank, @Must not be null

Last name of card holder

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cardNumber

String

@Card number length must be between 12 and 19, @Must not be blank, @Must not be null

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

motoType

String

@Must not be null

Allows to switch between CVC and AVS (Address Verification) methods of authentication

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

clientPostalCode

String

@Length must be between 1 and 10 inclusive, @Must not be blank, @Must not be null when AVS

Client postal code required in AVS service to authorize cardholder in bank issuer during MO/TO transaction

clientAddress

String

@Must not be null when AVS

Client address (e.g. house number) required in AVS service to authorize cardholder in bank issuer during MO/TO transaction

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Request - DataCenter card
HTTP Request
POST /client/payments/moto/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 369
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "9c37fcca-00bc-4a4c-a311-0e76eefe3c2c",
  "requestUuid" : "aab6d36b-4b0c-4b7c-80c9-c43a77c8eb2b",
  "amount" : 1000,
  "currency" : "USD",
  "cardId" : 1906455,
  "cvc2" : "123",
  "motoType" : "CVC",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 189. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 190. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

cvc2

String

@Length must be 3 characters, @Must not be null when MO/TO CVC

Cardholder’s card cvc2. Required only when moto verification type (motoType) is set to CVC value

cardId

Number

@Must not be null, @Numeric

DataCenter card id. Required to obtain card information data from DataCenter such as (cardNumber, expiryDate, firstName, lastName, email)

motoType

String

@Must not be null

Allows to switch between CVC and AVS (Address Verification) methods of authentication

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

6.5.2. Response

Response status
Status Description

200 OK

Returned when transaction was successfully authorized.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

STATUS: E8001 - Returned when server understood the request but refuses to authorize 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

STATUS: E06003 - Returned when DataCenter card was not found.

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: E01580 - Returned when transaction is rejected, because DataCenter card was expired.

STATUS: E01596 - Returned when transaction is rejected, because terminal has blocked transaction with card issued in restricted country

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: 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

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: E9010 - Returned when is error DataCenter connection.

503 SERVICE UNAVAILABLE

STATUS: E9001 - Returned when is error acquirer connection.

200 OK
HTTP Response - transaction
{
  "requestUuid" : "76d19bae-a6a6-42ac-a452-5369550e7e2f",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "status" : "S0002",
  "message" : "Success transaction",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 191. Response fields
Path Type Description

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

responseCode

String

Response code

links

Array

Links to other resources

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:12:20 GMT
Connection: close
Content-Length: 621

{
  "errors" : {
    "expiryDate" : [ "invalid card expiration date" ],
    "lastName" : [ "must not be null", "must not be blank" ],
    "firstName" : [ "must not be null", "must not be blank" ],
    "amount" : [ "must not be null" ],
    "merchantUuid" : [ "must not be null" ],
    "requestUuid" : [ "must not be null" ],
    "currency" : [ "must not be null" ],
    "cvc2" : [ "must not be null", "must not be blank" ],
    "cardNumber" : [ "must not be blank", "must not be null", "must not be empty" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "9e066c07-6c24-4a2d-8fcc-571f2854cc16"
}
HTTP Response - transaction without specified motoType
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:12:00 GMT
Connection: close
Content-Length: 170

{
  "errors" : {
    "motoType" : [ "must not be null" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "1f242af4-66f7-4c61-9a4f-938649417561"
}
Table 192. Response fields
Path Type Description

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

HTTP Response - STATUS: E8000 - DataCenter 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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:12:19 GMT
Connection: close
Content-Length: 679

{
  "errors" : {
    "expiryDate" : [ "Card id was provided, expiryDate is obtained from data center card: 1906455" ],
    "firstName" : [ "Card id was provided, firstName is obtained from data center card: 1906455" ],
    "lastName" : [ "Card id was provided, lastName is obtained from data center card: 1906455" ],
    "cardId" : [ "Please provide cardId for DATACENTER transaction or fields: cardNumber, expiryDate, firstName, lastName for PLAIN transaction" ],
    "cardNumber" : [ "Card id was provided, cardNumber is obtained from data center card: 1906455" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "4fe993fc-7478-4126-904c-972a0b0e0318"
}
Table 193. Response fields
Path Type Description

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:12:19 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "75202170-339c-4534-8a34-90f78b7c32b0",
  "links" : [ ]
}
Table 194. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:12:20 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "05bd3c6e-339d-4781-b263-ecd0a815ac1b",
  "links" : [ ]
}
Table 195. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0122
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 163

{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "d43b81d3-b406-468b-9eb1-7c7f145b8999",
  "links" : [ ]
}
HTTP Response - STATUS: E0132
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 163

{
  "status" : "E0132",
  "message" : "Terminal not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "14be948d-be15-4b8a-a9ad-a8a8c36cf36f",
  "links" : [ ]
}
HTTP Response - STATUS: E0135
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 176

{
  "status" : "E0135",
  "message" : "Terminals for merchant not exists",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "bfda7781-fbf1-4556-9eaf-ef724981f19c",
  "links" : [ ]
}
HTTP Response - STATUS: E0137
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 180

{
  "status" : "E0137",
  "message" : "Default terminal not exist",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "4c190474-4ebd-4057-bc35-490cb4319671",
  "links" : [ ]
}
Table 196. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

HTTP Response - STATUS: E06003
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 263

{
  "requestUuid" : "3da57bbd-eca6-49e9-9622-b14e2382d9b1",
  "transactionStatus" : "REJECTED",
  "status" : "E06003",
  "message" : "Datacenter card not found",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "21e9d507-3def-4e22-a44d-2593b5a327ca",
  "links" : [ ]
}
Table 197. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E0150
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 268

{
  "requestUuid" : "ea24c2cc-741e-4452-b3cb-d66e25d6d422",
  "transactionStatus" : "REJECTED",
  "status" : "E0150",
  "message" : "Transaction rejected",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "cb8c4aad-5eed-408f-a4b9-8bb04d4d81b7",
  "links" : [ ]
}
HTTP Response - STATUS: E0151
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 292

{
  "requestUuid" : "8f8dd814-bffb-4d81-b5cc-3d496a22c678",
  "transactionStatus" : "REJECTED",
  "status" : "E0151",
  "message" : "Transaction rejected, currency not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "1cba1c9e-fad8-4b9b-97ca-6d3bf6509b22",
  "links" : [ ]
}
HTTP Response - STATUS: E0152
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 295

{
  "requestUuid" : "5cd5be1e-f031-4ae9-a009-7b289a1d7b1a",
  "transactionStatus" : "REJECTED",
  "status" : "E0152",
  "message" : "Transaction rejected, issuer card not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "07d66c5b-f1fa-46b4-a512-ac4ad76d8fab",
  "links" : [ ]
}
HTTP Response - STATUS: E01580
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 299

{
  "requestUuid" : "980ab5f0-b0f0-491f-8b31-bd1c2e6f32db",
  "transactionStatus" : "REJECTED",
  "status" : "E01580",
  "message" : "Transaction rejected. Data center card is expired.",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "094a12ac-0f3b-4362-8b3d-728f8934b045",
  "links" : [ ]
}
HTTP Response - STATUS: E0200
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "requestUuid" : "5581fb89-14c6-4ddb-951f-d3ef2836eb4f",
  "transactionStatus" : "REJECTED",
  "status" : "E0200",
  "message" : "Transaction rejected, card is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "879d328c-5d06-4278-8b6d-ea1319fdd7de",
  "links" : [ ]
}
HTTP Response - STATUS: E0201
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 284

{
  "requestUuid" : "5c895673-9743-4407-8dc2-b067640557d6",
  "transactionStatus" : "REJECTED",
  "status" : "E0201",
  "message" : "Transaction rejected, bin is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "0fdc01c1-6ce1-469f-8cf5-dddfdbc9b6b9",
  "links" : [ ]
}
HTTP Response - STATUS: E0202
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 289

{
  "requestUuid" : "b37804d3-4bb7-4b52-9a32-7b521e4f7b21",
  "transactionStatus" : "REJECTED",
  "status" : "E0202",
  "message" : "Transaction rejected, terminal is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "35c7955c-6e51-4886-a933-aaecc47123f0",
  "links" : [ ]
}
HTTP Response - STATUS: E0204
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 289

{
  "requestUuid" : "adcbe33c-19a5-4516-ab4a-a06d79f726aa",
  "transactionStatus" : "REJECTED",
  "status" : "E0204",
  "message" : "Transaction rejected, user is on aml list",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "c73df32a-8037-4f1e-8aed-5160994a611c",
  "links" : [ ]
}
HTTP Response - STATUS: E0205
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "requestUuid" : "7fc10d32-72df-42df-991e-7fcd4ae7a8fd",
  "transactionStatus" : "REJECTED",
  "status" : "E0205",
  "message" : "Transaction rejected, bank is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "591dcb51-4d85-4289-9ee2-cb402c60ce3c",
  "links" : [ ]
}
HTTP Response - STATUS: E0206
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 317

{
  "requestUuid" : "6158b027-e4bc-4a86-9814-79467cba2190",
  "transactionStatus" : "REJECTED",
  "status" : "E0206",
  "message" : "Transaction rejected, to many reject transactions and card is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "5d28d1bf-742e-4e09-9fa1-5cad9d78b8e9",
  "links" : [ ]
}
HTTP Response - STATUS: E01596
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 338

{
  "requestUuid" : "48406b13-8fdd-41d7-b2ad-ca9df2ef745c",
  "transactionStatus" : "REJECTED",
  "status" : "E01596",
  "message" : "Transaction rejected, terminal blocks transactions with card issued in given card country",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "427ab048-cf59-4897-a356-4f8c45dad24a",
  "links" : [ ]
}
Table 198. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E0142
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 200

{
  "status" : "E0142",
  "message" : "Commission configuration not add for terminal",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "f582af57-f24c-4e40-91cf-57b31720fd53",
  "links" : [ ]
}
HTTP Response - STATUS: E0153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 297

{
  "requestUuid" : "f7e86dc5-27e9-469d-b74c-d807cdb6ce82",
  "transactionStatus" : "PENDING",
  "status" : "E0153",
  "message" : "Transaction declined, problem with MIP connection",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "7e1ad37d-3a34-4088-9745-b37aef53aa2f",
  "links" : [ ]
}
HTTP Response - STATUS: E01599
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 290

{
  "requestUuid" : "a23ca570-bc2b-43e4-b3a8-b4c73a72d13b",
  "transactionStatus" : "DECLINED",
  "status" : "E01599",
  "message" : "Transaction declined, processing timeout",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "71afd7d9-9a36-4b4b-8576-61f4dbfe0bc6",
  "links" : [ ]
}
HTTP Response - STATUS: E0190
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 183

{
  "status" : "E0190",
  "message" : "Failed to get currency rates",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "b1236889-4c8d-4b0d-bc0a-e89be6da1bd9",
  "links" : [ ]
}
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:14:04 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "5c57a621-3342-4fb5-b16f-3a855124aa85"
}
Table 199. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

503 SERVICE UNAVAILABLE
HTTP Response - STATUS: E9001
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:03 GMT
Connection: close
Content-Length: 161

{
  "status" : "E9001",
  "message" : "Error acquirer connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "4574e22f-d368-46d0-91d5-42208ddb9e44"
}
HTTP Response - STATUS: E9002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 267

{
  "requestUuid" : "add00017-600e-450a-b982-0d6ed28f1ce1",
  "transactionStatus" : "DECLINED",
  "status" : "E9002",
  "message" : "Error mpi connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "b3d94184-0ed8-4ab4-9fca-af86e5a433fd",
  "links" : [ ]
}
HTTP Response - STATUS: E9010
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 275

{
  "requestUuid" : "ce1eb091-ef70-4c67-b399-0879e686308c",
  "transactionStatus" : "REJECTED",
  "status" : "E9010",
  "message" : "Error data center connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "9b554863-f243-4b11-9dbe-782ca1762675",
  "links" : [ ]
}
Table 200. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

6.6. Token payment

POST /client/payments/token/auth Content Type: application/json, Authorization: Basic Auth
   The token payment method is a solution that allows merchant customers to make payments using mobile applications. The merchant uses a card number in the form of a token and dynamic cryptographic data to authenticate the cardholder. The merchant receives this data from the token requestor it uses.
   Then Fenige authorizes the transaction in Mastercard or VISA and depending on the result, returns the corresponding status to the merchant.
   An additional option not required is to send an additional authentication in the form of an outside3ds object containing the authentication data for the 3DS version 1.0 or 2.x
execution confirmation.
This endpoint is idempotent so if you execute more than one requests with the same data even at the same time, only first registered transaction will be processed further. In
response, we receive transaction status.

From January 2021, there is an internal functionality to restrict access for the PSP to specific method. The Fenige employee can disable access to a given endpoint, then the HTTP status 403 FORBIDDEN will be returned. The PSP will be informed about each access restriction action.

E-commerce payment with token and outside 3DS flow
ecommerce token with outside3ds flow
E-commerce payment with token and 3ds flow
ecommerce token flow

6.6.1. Request

Request - with forced terminal optional outside 3DS 2.0
HTTP Request
POST /client/payments/token/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 867
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "4f7e56fe-1ba8-4999-8555-af67db8a28cf",
  "terminalUuid" : "b6810ed5-fe8c-4338-980a-fb6b9d394666",
  "requestUuid" : "f5d8206c-6e4c-4eb8-9d65-49557f119375",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 100,
  "currency" : "USD",
  "tokenPan" : "5127482301411937126",
  "expiryDate" : "11/22",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalLocation" : "HOME",
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3",
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  },
  "outside3ds" : {
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
    "cavvAlgorithm" : "01",
    "eci" : "02",
    "authenticationStatus" : "Y",
    "transactionXId" : "d543820d-683e-4589-86d9-6c9e40db4b53"
  }
}
Table 201. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 202. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

firstName

String

Optional field, @Length must be between 2 and 35

First name of card holder

lastName

String

Optional field,@Length must be between 2 and 35

Last name of card holder

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

tokenPan

String

@Must be not null, @Must be not blank, @Length must be between 16 and 19

Token that is used in place of sender’s card number (PAN). Token form payment gateway or native apps from google, apple etc

terminalLocation

String

@Must not be null

Location of terminal - value must be set as HOME or PREMISES

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

paymentData

Object

Payment tokenization data object

paymentData.onlinePaymentCryptogram

String

@Must not be empty, @Size must be between 0 and 28 inclusive

Payment secure cryptogram obtained during merchant card tokenization in mobile app. Base64 encoded payment crypto value.

paymentData.eciIndicator

String

@Length must be between 1 and 2 inclusive, @Must match 01 or 02 or 05 or 06, @Must not be null

Eci value returned only for tokens on the Visa card network. The value should be passed by merchant if present with payment cryptogram. Optional value

outside3ds

Object

There are outside 3ds data authorization that have been send to our API

outside3ds.cavv

String

@Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3ds.transactionXId

String

The transactionXId is the field that defines the 3DS version.The presence of this field in the HTTP request specifies that the transaction will be processed with 3DS 2.x.TransactionXId can be obtained by executing the /authentication method.

outside3ds.cavvAlgorithm

String

@Length must be between 1 and 2 inclusive, @Must match the regular expression ^\d+$

Indicates the algorithm used to generate the AuthenticationCAVV value

0 - HMAC

1 - CVV

2 - CVV with ATN

3 - MasterCard SPA algorithm

outside3ds.eci

String

@Length must be between 1 and 2 inclusive, @Must match 01 or 02 or 05 or 06, @Must not be null

Electronic Commerce Indicator: 5 (Visa) or 2 (SecureCode) - The cardholder was successfully authenticated. 6 (Visa) or 1 (SecureCode) - Authentication was attempted, but the cardholder was not enrolled. Chargeback protection applies.

outside3ds.authenticationStatus

String

@Must match Y or A, @Must not be null

Authentication status:

Y - (Full Authentication) - The customer was successfully authenticated.

A - (Successful Attempted Authentication) - Authentication was not available, but functionality was available to generate a proof of authentication attempt.

terminalUuid

String

Terminals’s unique uuid in system

Request - with forced terminal optional outside 3DS 1.0
HTTP Request
POST /client/payments/token/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 804
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "4f7e56fe-1ba8-4999-8555-af67db8a28cf",
  "terminalUuid" : "b6810ed5-fe8c-4338-980a-fb6b9d394666",
  "requestUuid" : "f5d8206c-6e4c-4eb8-9d65-49557f119375",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 100,
  "currency" : "USD",
  "tokenPan" : "5127482301411937126",
  "expiryDate" : "11/22",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalLocation" : "HOME",
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3",
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  },
  "outside3ds" : {
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
    "cavvAlgorithm" : "01",
    "eci" : "02",
    "authenticationStatus" : "Y"
  }
}
Table 203. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 204. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

firstName

String

Optional field, @Length must be between 2 and 35

First name of card holder

lastName

String

Optional field,@Length must be between 2 and 35

Last name of card holder

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

tokenPan

String

@Must be not null, @Must be not blank, @Length must be between 16 and 19

Token that is used in place of sender’s card number (PAN). Token form payment gateway or native apps from google, apple etc

terminalLocation

String

@Must not be null

Location of terminal - value must be set as HOME or PREMISES

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

paymentData

Object

Payment tokenization data object

paymentData.onlinePaymentCryptogram

String

@Must not be empty, @Size must be between 0 and 28 inclusive

Payment secure cryptogram obtained during merchant card tokenization in mobile app. Base64 encoded payment crypto value.

paymentData.eciIndicator

String

@Length must be between 1 and 2 inclusive, @Must match 01 or 02 or 05 or 06, @Must not be null

Eci value returned only for tokens on the Visa card network. The value should be passed by merchant if present with payment cryptogram. Optional value

outside3ds

Object

There are outside 3ds data authorization that have been send to our API

outside3ds.cavv

String

@Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value.

outside3ds.cavvAlgorithm

String

@Length must be between 1 and 2 inclusive, @Must match the regular expression ^\d+$

Indicates the algorithm used to generate the AuthenticationCAVV value

0 - HMAC

1 - CVV

2 - CVV with ATN

3 - MasterCard SPA algorithm

outside3ds.eci

String

@Length must be between 1 and 2 inclusive, @Must match 01 or 02 or 05 or 06, @Must not be null

Electronic Commerce Indicator: 5 (Visa) or 2 (SecureCode) - The cardholder was successfully authenticated. 6 (Visa) or 1 (SecureCode) - Authentication was attempted, but the cardholder was not enrolled. Chargeback protection applies.

outside3ds.authenticationStatus

String

@Must match Y or A, @Must not be null

Authentication status:

Y - (Full Authentication) - The customer was successfully authenticated.

A - (Successful Attempted Authentication) - Authentication was not available, but functionality was available to generate a proof of authentication attempt.

terminalUuid

String

Terminals’s unique uuid in system

Request
HTTP Request
POST /client/payments/token/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 597
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "022d3842-8bfb-4d53-8b5e-5a5803f6a42f",
  "requestUuid" : "f5d8206c-6e4c-4eb8-9d65-49557f119375",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 100,
  "currency" : "USD",
  "tokenPan" : "5127482301411937126",
  "expiryDate" : "11/22",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalLocation" : "HOME",
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3",
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
Table 205. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 206. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

firstName

String

Optional field, @Length must be between 2 and 35

First name of card holder

lastName

String

Optional field,@Length must be between 2 and 35

Last name of card holder

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

tokenPan

String

@Must be not null, @Must be not blank, @Length must be between 16 and 19

Token that is used in place of sender’s card number (PAN). Token form payment gateway or native apps from google, apple etc

terminalLocation

String

@Must not be null

Location of terminal - value must be set as HOME or PREMISES

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

paymentData

Object

Payment tokenization data object

paymentData.onlinePaymentCryptogram

String

@Must not be empty, @Size must be between 0 and 28 inclusive

Payment secure cryptogram obtained during merchant card tokenization in mobile app. Base64 encoded payment crypto value.

paymentData.eciIndicator

String

@Length must be between 1 and 2 inclusive, @Must match 01 or 02 or 05 or 06, @Must not be null

Eci value returned only for tokens on the Visa card network. The value should be passed by merchant if present with payment cryptogram. Optional value.

Request - forced Terminal
HTTP Request
POST /client/payments/token/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 656
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "4f7e56fe-1ba8-4999-8555-af67db8a28cf",
  "terminalUuid" : "b6810ed5-fe8c-4338-980a-fb6b9d394666",
  "requestUuid" : "f5d8206c-6e4c-4eb8-9d65-49557f119375",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 100,
  "currency" : "USD",
  "tokenPan" : "5127482301411937126",
  "expiryDate" : "11/22",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalLocation" : "HOME",
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3",
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
Table 207. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 208. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

firstName

String

Optional field, @Length must be between 2 and 35

First name of card holder

lastName

String

Optional field,@Length must be between 2 and 35

Last name of card holder

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

tokenPan

String

@Must be not null, @Must be not blank, @Length must be between 16 and 19

Token that is used in place of sender’s card number (PAN). Token form payment gateway or native apps from google, apple etc

terminalLocation

String

@Must not be null

Location of terminal - value must be set as HOME or PREMISES

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

paymentData

Object

Payment tokenization data object

paymentData.onlinePaymentCryptogram

String

@Must not be empty, @Size must be between 0 and 28 inclusive

Payment secure cryptogram obtained during merchant card tokenization in mobile app. Base64 encoded payment crypto value.

paymentData.eciIndicator

String

@Length must be between 1 and 2 inclusive, @Must match 01 or 02 or 05 or 06, @Must not be null

Eci value returned only for tokens on the Visa card network. The value should be passed by merchant if present with payment cryptogram. Optional value.

terminalUuid

String

Terminals’s unique uuid in system

6.6.2. Response

Response status
Status Description

200 OK

Returned when transaction was successfully authorized with Token.

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: 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 declined, 3DS 2.X flow invoked for other card number than specified in the request

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

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.

200 OK (with 3DS)
HTTP Response - transaction with 3DS

Unresolved directive in token-payment.adoc - include::/var/lib/jenkins/workspace/ecommerce_staging/ecommerce_staging/target/generated-snippets/authorizeToken/successAuthorizeWithTerminalUuidWith3ds10/response-body-beneath-result.body.adoc[] .Response fields Unresolved directive in token-payment.adoc - include::/var/lib/jenkins/workspace/ecommerce_staging/ecommerce_staging/target/generated-snippets/authorizeToken/successAuthorizeWithTerminalUuidWith3ds10/response-fields-beneath-result.body.adoc[]

400 BAD REQUEST
HTTP Response - STATUS: E8000

Unresolved directive in token-payment.adoc - include::/var/lib/jenkins/workspace/ecommerce_staging/ecommerce_staging/target/generated-snippets/authorizeToken/badRequestAuthorize/http-response.adoc[] .Response fields Unresolved directive in token-payment.adoc - include::/var/lib/jenkins/workspace/ecommerce_staging/ecommerce_staging/target/generated-snippets/authorizeToken/badRequestAuthorize/response-fields.adoc[]

401 UNAUTHORIZED
HTTP Response - STATUS: E8002

Unresolved directive in token-payment.adoc - include::/var/lib/jenkins/workspace/ecommerce_staging/ecommerce_staging/target/generated-snippets/authorizeToken/unauthorizedAuthorize/http-response.adoc[] .Response fields Unresolved directive in token-payment.adoc - include::/var/lib/jenkins/workspace/ecommerce_staging/ecommerce_staging/target/generated-snippets/authorizeToken/unauthorizedAuthorize/response-fields.adoc[]

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:12:20 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "05bd3c6e-339d-4781-b263-ecd0a815ac1b",
  "links" : [ ]
}
Table 209. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0122
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 163

{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "7da394d5-7917-42e2-8ad0-7e705f038af5",
  "links" : [ ]
}
HTTP Response - STATUS: E0137
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 176

{
  "status" : "E0135",
  "message" : "Terminals for merchant not exists",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "5bbe1ed1-9e94-47da-955a-711f4666beec",
  "links" : [ ]
}
Table 210. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E0150
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 268

{
  "requestUuid" : "e1b72171-5133-44df-92b0-7f018b652068",
  "transactionStatus" : "REJECTED",
  "status" : "E0150",
  "message" : "Transaction rejected",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "1a3c633a-c473-4470-8bd9-4b24b8b45749",
  "links" : [ ]
}
HTTP Response - STATUS: E0151
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 292

{
  "requestUuid" : "056f42eb-cab6-4b05-9eac-511fc371f0e2",
  "transactionStatus" : "REJECTED",
  "status" : "E0151",
  "message" : "Transaction rejected, currency not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "d082ba42-3a95-4806-aa87-cae14dd11b17",
  "links" : [ ]
}
HTTP Response - STATUS: E0152
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 295

{
  "requestUuid" : "521d4afa-f501-425a-9dc4-f83d098099ed",
  "transactionStatus" : "REJECTED",
  "status" : "E0152",
  "message" : "Transaction rejected, issuer card not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "31e40716-8a76-422a-8b2d-c820bf255940",
  "links" : [ ]
}
HTTP Response - STATUS: E0156
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 202

{
  "status" : "E0156",
  "message" : "Transaction rejected, terminal not supported 3ds",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "0c8a868d-8e15-42f4-8078-38c199be58c0",
  "links" : [ ]
}
HTTP Response - STATUS: E0157
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 198

{
  "status" : "E0157",
  "message" : "Transaction rejected, card not supported 3ds",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "5c777ad5-04e5-4a15-8d89-ad909f8e3b61",
  "links" : [ ]
}
HTTP Response - STATUS: E01599
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 290

{
  "requestUuid" : "fc7e74a4-550e-4813-bfef-c78b6b54da5d",
  "transactionStatus" : "DECLINED",
  "status" : "E01599",
  "message" : "Transaction declined, processing timeout",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "6637ff13-0239-414f-b86c-a7e6536ea4a2",
  "links" : [ ]
}
HTTP Response - STATUS: E0200
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "requestUuid" : "300ee259-caa2-4932-9cc2-b64991803b4c",
  "transactionStatus" : "REJECTED",
  "status" : "E0200",
  "message" : "Transaction rejected, card is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "b2c4f7bf-575b-43af-bbd8-3297c5a8b428",
  "links" : [ ]
}
HTTP Response - STATUS: E0201
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 284

{
  "requestUuid" : "7e1ee769-4a31-4389-b913-d82a2ffad29e",
  "transactionStatus" : "REJECTED",
  "status" : "E0201",
  "message" : "Transaction rejected, bin is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "d02265df-9310-4c45-8636-174465c04bad",
  "links" : [ ]
}
HTTP Response - STATUS: E0202
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 289

{
  "requestUuid" : "763001cd-0219-4d35-a10d-56168dda8ba8",
  "transactionStatus" : "REJECTED",
  "status" : "E0202",
  "message" : "Transaction rejected, terminal is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "1a9a5433-4b3b-457c-a0ae-6b42173e327b",
  "links" : [ ]
}
HTTP Response - STATUS: E0203
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 286

{
  "requestUuid" : "11e22c3e-d95d-4799-91b2-11b02a644834",
  "transactionStatus" : "REJECTED",
  "status" : "E0203",
  "message" : "Transaction rejected, token is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "b8b1de43-eaba-4f82-9067-68ba04b68c0f",
  "links" : [ ]
}
HTTP Response - STATUS: E0204
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 289

{
  "requestUuid" : "b6686d32-bdbd-410e-a0f6-918d04d540ba",
  "transactionStatus" : "REJECTED",
  "status" : "E0204",
  "message" : "Transaction rejected, user is on aml list",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "b0464795-070a-4bf1-98b5-272e67bd3ba8",
  "links" : [ ]
}
HTTP Response - STATUS: E0205
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "requestUuid" : "9423889c-8eaf-4582-8803-f15e6d0c6776",
  "transactionStatus" : "REJECTED",
  "status" : "E0205",
  "message" : "Transaction rejected, bank is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "02f267fc-31af-4ee8-ac86-1ca63d2b1e5f",
  "links" : [ ]
}
HTTP Response - STATUS: E0206
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 317

{
  "requestUuid" : "6158b027-e4bc-4a86-9814-79467cba2190",
  "transactionStatus" : "REJECTED",
  "status" : "E0206",
  "message" : "Transaction rejected, to many reject transactions and card is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "5d28d1bf-742e-4e09-9fa1-5cad9d78b8e9",
  "links" : [ ]
}
HTTP Response - STATUS: E01583
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 307

{
  "requestUuid" : "048c178e-dca0-4652-a5dc-96d8d7d422e3",
  "transactionStatus" : "REJECTED",
  "status" : "E01583",
  "message" : "Transaction rejected. Outside 3ds is required for terminal",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "8e7803eb-7b1a-4370-aca5-52e1fb8c2130",
  "links" : [ ]
}
HTTP Response - STATUS: E01596
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 338

{
  "requestUuid" : "48406b13-8fdd-41d7-b2ad-ca9df2ef745c",
  "transactionStatus" : "REJECTED",
  "status" : "E01596",
  "message" : "Transaction rejected, terminal blocks transactions with card issued in given card country",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "427ab048-cf59-4897-a356-4f8c45dad24a",
  "links" : [ ]
}
HTTP Response - STATUS: E01597
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 386

{
  "requestUuid" : "5360881b-9dcc-44b9-94b8-95d336b9a9b2",
  "transactionStatus" : "REJECTED",
  "status" : "E01597",
  "message" : "Transaction rejected, 3DS version of terminal are not compatible with 3DS version defined in request. Please contact the sales department",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "2db61b2a-312a-4adc-8617-ffebd9db6298",
  "links" : [ ]
}
HTTP Response - STATUS: E01598
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 315

{
  "requestUuid" : "01c123c6-4857-461c-94f0-308cc0f0cb95",
  "transactionStatus" : "REJECTED",
  "status" : "E01598",
  "message" : "Transaction rejected, ECI value is not available for card provider",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "540fecdb-4538-4f62-ba82-1806ab9aae62",
  "links" : [ ]
}
Table 211. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

HTTP Response - STATUS: E01600
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 343

{
  "requestUuid" : "e4b9e04b-9924-4bfd-869a-1c887233d2c4",
  "transactionStatus" : "REJECTED",
  "status" : "E01600",
  "message" : "Transaction declined, 3DS 2.X flow invoked for other card number than specified in the request",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "a4ec5eaa-5cfe-4929-acf8-b3a240ca2cf0",
  "links" : [ ]
}
Table 212. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E0153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 297

{
  "requestUuid" : "e1166e16-c557-45db-b145-60714db18f83",
  "transactionStatus" : "PENDING",
  "status" : "E0153",
  "message" : "Transaction declined, problem with MIP connection",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "d31091d9-6904-4e4e-a106-5f4ffd1cc5db",
  "links" : [ ]
}
HTTP Response - STATUS: E0142
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 200

{
  "status" : "E0142",
  "message" : "Commission configuration not add for terminal",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "cea90ca1-c6e5-4ead-aab9-1942895ebd42",
  "links" : [ ]
}
HTTP Response - STATUS: E0190
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 183

{
  "status" : "E0190",
  "message" : "Failed to get currency rates",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "ca395895-c608-4e9a-b9e7-87bd0f734380",
  "links" : [ ]
}
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:14:04 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "5c57a621-3342-4fb5-b16f-3a855124aa85"
}
HTTP Response - STATUS: E9008
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 282

{
  "requestUuid" : "59bebcb3-b371-4ca2-84ec-e9ea1e1b0e09",
  "transactionStatus" : "DECLINED",
  "status" : "E9008",
  "message" : "Error mpi - 3ds initialize failed",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "19d3fc0f-840c-4cf9-89c2-6c05b8e32155",
  "links" : [ ]
}
Table 213. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

503 SERVICE UNAVAILABLE
HTTP Response - STATUS: E9001
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:03 GMT
Connection: close
Content-Length: 161

{
  "status" : "E9001",
  "message" : "Error acquirer connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "4574e22f-d368-46d0-91d5-42208ddb9e44"
}
HTTP Response - STATUS: E9002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 267

{
  "requestUuid" : "513cd6a8-9036-451f-8c79-697d770a0792",
  "transactionStatus" : "DECLINED",
  "status" : "E9002",
  "message" : "Error mpi connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "4994ed7c-9809-446f-b1e3-d3669cebe2ea",
  "links" : [ ]
}
Table 214. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

6.7. CoF payment

A CoF (credential on file transaction) is a transaction where a cardholder authorizes a merchant to store account information such as (PAN and expiration date, and the
cardholder subsequently authorizes that same merchant to bill the cardholder’s stored account.
The method is used to charge the cardholder with no need to collect account data (PAN, exp date) from merchant at every transaction.
Using this method, we can authorize and process entire transaction using stored payment details. CoF supports both 3DS and without 3DS transactions. How the transaction will
be initiated depends on the terminal settings (look at 'is3dsEnable' field).
This endpoint is idempotent so if you execute more than one requests with the same data even at the same time, only first registered transaction will be processed further. In
response, we receive transaction status.
The cof transaction consists of two parts: initial and subsequent, which are discussed in detail below.
Please see detailed CoF transaction flow described on below listings.
The Fenige Payment API methods optionally allows merchants to store card data and sensitive personal data in order to allow performing subsequent transactions.
If merchant decides to use DataCenter transaction flow then is required to provide the card id of the card previously stored in the Fenige DataCenter, from which card the
relevant required parameters will be downloaded and used for authorization.
Card data and sensitive personal data according to the Fenige API specification are: cardNumber, expiryDate, firstName, lastName and email.
All card data are stored securely on Fenige DataCenter servers in accordance with applicable security requirements.

From January 2021, there is an internal functionality to restrict access for the PSP to specific method. The Fenige employee can disable access to a given endpoint, then the HTTP status 403 FORBIDDEN will be returned. The PSP will be informed about each access restriction action.

CoF payment flow
cof trx flow
CoF payment with outside 3DS
cof trx with outside3ds flow
CoF payment with DataCenter flow
cof trx data center flow
CoF payment with DataCenter and outside 3DS flow
cof trx data center outside3ds flow
CoF payment with 3ds flow
cof trx 3ds flow

6.7.1. CoF Initial transaction

POST /client/payments/cof/initial Content Type: application/json, Authorization: Basic Auth
The first stage is a one-time initial transaction, which is a simple e-commerce payment but contains the customer's consent to store card data for subsequent purchases. Card
 data is stored in a secure FENIGE environment. After completing the initial merchant receives the unique cofInitialUuid identifier needed to perform subsequent CoF
 transactions without having to enter card data.

From January 2021, there is an internal functionality to restrict access for the PSP to specific method. The Fenige employee can disable access to a given endpoint, then the HTTP status 403 FORBIDDEN will be returned. The PSP will be informed about each access restriction action.

Request
Simple request
HTTP Request
POST /client/payments/cof/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 469
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "9c37fcca-00bc-4a4c-a311-0e76eefe3c2c",
  "requestUuid" : "f3bc31fd-ffe5-4a78-ad81-3c207d3ba695",
  "firstName" : "user",
  "lastName" : "testUser",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "amount" : 1000,
  "currency" : "USD",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 215. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 216. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

First name of card holder

lastName

String

Last name of card holder

cardNumber

String

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Request with forced Terminal
HTTP Request
POST /client/payments/cof/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 570
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "abbf2a00-051b-4e85-90d0-b71509db17ec",
  "terminalUuid" : "4e87df0d-6556-4ae2-ace4-c82542c53502",
  "requestUuid" : "afab8842-c8b4-4874-8048-d510a48ad4e9",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "cardId" : null,
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "outside3ds" : null,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 217. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 218. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

First name of card holder

lastName

String

Last name of card holder

cardNumber

String

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

terminalUuid

String

Terminals’s unique uuid in system

Request with DataCenter card
HTTP Request
POST /client/payments/cof/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 347
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "232a4cc2-6d7e-450b-a4e6-6dfb374506eb",
  "requestUuid" : "4128deeb-b866-4950-8075-3c6367c2b050",
  "amount" : 1000,
  "currency" : "USD",
  "cardId" : 1906455,
  "cvc2" : "123",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 219. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 220. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

cardId

Number

@Must not be null, @Numeric

DataCenter card id. Required to obtain card information data from DataCenter such as (cardNumber, expiryDate, firstName, lastName, email)

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Response
Status Description

200 OK

Returned when transaction was successfully authorized.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

STATUS: E8001 - Returned when server understood the request but refuses to authorize 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

STATUS: E06003 - Returned when DataCenter card was not found.

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: E01580 - Returned when transaction is rejected, because DataCenter card was expired.

STATUS: E01596 - Returned when transaction is rejected, because terminal has blocked transaction with card issued in restricted country

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: 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: E01600 - Returned when transaction is declined, because 3DS 2.X flow invoked for other card number than specified in the request

500 INTERNAL SERVER ERROR

STATUS: E0142 - Returned when commission configuration is not added for terminal.

STATUS: E0153 - Returned when transaction is declined, by problem with MIP connection.

STATUS: E01599 - Transaction declined, processing timeout.

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.

STATUS: E9010 - Returned when is error DataCenter connection.

200 OK
HTTP Response - transaction without 3DS
{
  "requestUuid" : "609412f4-6ee8-440b-b8e6-261895469bb2",
  "cofInitialUuid" : "a9ac7d0a-5dd1-4b52-9d16-62e773cce6aa",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "status" : "S0002",
  "message" : "Success transaction",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 221. Response fields
Path Type Description

requestUuid

String

Request unique uuid in system

cofInitialUuid

String

CoF transaction unique uuid in system

transactionStatus

String

Transaction status

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

responseCode

String

Response code

links

Array

Links to other resources

200 OK (with 3DS)
HTTP Response - transaction with 3DS
{
  "requestUuid" : "e727784e-6edc-43af-810d-a4e30f05bae9",
  "cofInitialUuid" : "7809d303-1300-4cef-ad05-5f09a5cb68bf",
  "transactionStatus" : "WAITING_ON_3DS_CONFIRMATION",
  "pareq" : "eJxlkltvwjAMhf8K4p3m0qRUlYnE4GHVxMQuT3uLWguK2lDSFsG/n8NlbFqkSD6Oe+p8DnxuPeLyA4vBo4EVdp3d4KgqZ2M5lWpsYD1/x4OBI/qu2jsjIh5JYHdJX/hia11vwBaHp/zVaCVEooDdJDTo86XhtCa0BbBrApxt0HToStUgsIuCYj+43p9NIhJgdwGDr82279suY2xnj3ZS4hFrEQ2trcqorbNUqZgVdYWuBxaqgT3aWg8h6sj9VJUmX8w3//Yyj1e7txmwUAGl7dFILlIeSz4SOlM60ymwSx5sE9oyi6+XUax5xDnd9JqCNvxpfhV0Fo5+p4AQe3TFmcxjut5dAZ7avaPeDXH9iYE9Gl88B7pFT9jiADIsRSxpQKlKtNRqmsiUkN2KgmNF5CTn+mIZBLBgw27jJECXSVP05wV8A1/aqWQ=",
  "acsUrl" : "https://ecom-staging.fenige.pl/fenige-mpi",
  "md" : "ZTkwYjU3N2YtNzU5Ny00ZWM5LWE2MDAtZjQ4YWVmZDgzMjhm",
  "formBase64" : "PGh0bWw+PFNDUklQVCBMQU5HVUFHRT0iSmF2YXNjcmlwdCI+ZnVuY3Rpb24gT25Mb2FkRXZlbnQoKXsgZG9jdW1lbnQuZG93bmxvYWRGb3JtLnN1Ym1pdCgpOyB9PC9TQ1JJUFQ+PGJvZHkgT25Mb2FkPSJPbkxvYWRFdmVudCgpOyI+PGZvcm0gbmFtZT0iZG93bmxvYWRGb3JtIiBhY3Rpb249Imh0dHBzOi8vamF2YS1kZXZlbC5mZW5pZ2UucGw6ODE4MS9mZW5pZ2UtbXBpIiBtZXRob2Q9IlBPU1QiPjxJTlBVVCB0eXBlPSJoaWRkZW4iIG5hbWU9IlBhUmVxIiB2YWx1ZT0iZUp4bGtsdHZ3akFNaGY4SzRwM20wcVJVbFluRTRHSFZ4TVF1VDN1TFdndUsybERTRnNHL244TmxiRnFrU0Q2T2UrcDhEbnh1UGVMeUE0dkJvNEVWZHAzZDRLZ3FaMk01bFdwc1lEMS94NE9CSS9xdTJqc2pJaDVKWUhkSlgvaGlhMTF2d0JhSHAvelZhQ1ZFb29EZEpEVG84NlhodENhMEJiQnJBcHh0MEhUb1N0VWdzSXVDWWorNDNwOU5JaEpnZHdHRHI4MjI3OXN1WTJ4bmozWlM0aEZyRVEydHJjcW9yYk5VcVpnVmRZV3VCeGFxZ1QzYVdnOGg2c2o5VkpVbVg4dzMvL1l5ajFlN3R4bXdVQUdsN2RGSUxsSWVTejRTT2xNNjB5bXdTeDVzRTlveWk2K1hVYXg1eERuZDlKcUNOdnhwZmhWMEZvNStwNEFRZTNURm1jeGp1dDVkQVo3YXZhUGVEWEg5aVlFOUdsODhCN3BGVDlqaUFESXNSU3hwUUtsS3ROUnFtc2lVa04yS2dtTkY1Q1RuK21JWkJMQmd3MjdqSkVDWFNWUDA1d1Y4QTEvYXFXUT0iPjxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9IlRlcm1VcmwiIHZhbHVlPSJodHRwOi8vbG9jYWxob3N0OjgwODEvY2xpZW50L3BheW1lbnRzL3Rlcm1pbmF0ZSI+PGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iTUQiIHZhbHVlPSJaVGt3WWpVM04yWXROelU1TnkwMFpXTTVMV0UyTURBdFpqUTRZV1ZtWkRnek1qaG0iPjwvZm9ybT48L2JvZHk+PC9odG1sPg==",
  "enrolledStatus" : "Y",
  "status" : "S0000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 222. Response fields
Path Type Description

status

String

Status of transaction

message

String

Message describe transaction result

httpStatus

String

Status of request

requestUuid

String

Unique request UUID

cofInitialUuid

String

CoF transaction unique uuid in system

transactionStatus

String

Transaction status

pareq

String

Payer Authentication Request

acsUrl

String

Fully qualified URL of an Access Control Server

md

String

Correlation id in base64 format

formBase64

String

HTML form encoded by Base64 algorithm

enrolledStatus

String

Status of 3DS transaction

links

Array

Links to other resources

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:12:41 GMT
Connection: close
Content-Length: 621

{
  "errors" : {
    "expiryDate" : [ "invalid card expiration date" ],
    "firstName" : [ "must not be blank", "must not be null" ],
    "lastName" : [ "must not be blank", "must not be null" ],
    "amount" : [ "must not be null" ],
    "merchantUuid" : [ "must not be null" ],
    "requestUuid" : [ "must not be null" ],
    "currency" : [ "must not be null" ],
    "cvc2" : [ "must not be blank", "must not be null" ],
    "cardNumber" : [ "must not be empty", "must not be null", "must not be blank" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "13419c36-7efd-452f-9770-010adf4dc343"
}
Table 223. Response fields
Path Type Description

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

HTTP Response - STATUS: E8000 - DataCenter 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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:12:38 GMT
Connection: close
Content-Length: 679

{
  "errors" : {
    "expiryDate" : [ "Card id was provided, expiryDate is obtained from data center card: 1906455" ],
    "firstName" : [ "Card id was provided, firstName is obtained from data center card: 1906455" ],
    "lastName" : [ "Card id was provided, lastName is obtained from data center card: 1906455" ],
    "cardId" : [ "Please provide cardId for DATACENTER transaction or fields: cardNumber, expiryDate, firstName, lastName for PLAIN transaction" ],
    "cardNumber" : [ "Card id was provided, cardNumber is obtained from data center card: 1906455" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "d65a0044-fbca-4068-9c8f-f0ec6a29154f"
}
Table 224. Response fields
Path Type Description

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:12:37 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "df232c4a-f657-43f3-9f40-3ccf9c122f08",
  "links" : [ ]
}
Table 225. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:12:42 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "9087b9f5-abb0-4ff0-9d11-b917045de7f7",
  "links" : [ ]
}
Table 226. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0122
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 163

{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "4c315e27-5025-4e2b-95af-b687632988cd",
  "links" : [ ]
}
HTTP Response - STATUS: E0132
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 163

{
  "status" : "E0132",
  "message" : "Terminal not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "5b9a140d-5eb0-4c5d-ac0b-ef573fb363c7",
  "links" : [ ]
}
Table 227. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

HTTP Response - STATUS: E0135
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 180

{
  "status" : "E0137",
  "message" : "Default terminal not exist",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "30d7675f-9f55-485f-99f1-53ad035da7e9",
  "links" : [ ]
}
Table 228. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

HTTP Response - STATUS: E0137
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 176

{
  "status" : "E0135",
  "message" : "Terminals for merchant not exists",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "486a635a-68cc-4f12-8d72-7285c158a577",
  "links" : [ ]
}
Table 229. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

HTTP Response - STATUS: E06003
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 263

{
  "requestUuid" : "3da57bbd-eca6-49e9-9622-b14e2382d9b1",
  "transactionStatus" : "REJECTED",
  "status" : "E06003",
  "message" : "Datacenter card not found",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "21e9d507-3def-4e22-a44d-2593b5a327ca",
  "links" : [ ]
}
Table 230. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E0150
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 268

{
  "requestUuid" : "d2d20244-d669-442d-b918-3c2d9d1f9d87",
  "transactionStatus" : "REJECTED",
  "status" : "E0150",
  "message" : "Transaction rejected",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "fe36b3ae-dab9-410b-b97e-f5d8d54509e5",
  "links" : [ ]
}
HTTP Response - STATUS: E0151
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 292

{
  "requestUuid" : "a3e2543c-eace-44a9-b215-b6e62464bc05",
  "transactionStatus" : "REJECTED",
  "status" : "E0151",
  "message" : "Transaction rejected, currency not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "7c2f8baf-9b46-40a6-9889-77e623d2df6a",
  "links" : [ ]
}
HTTP Response - STATUS: E0152
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 295

{
  "requestUuid" : "672a3289-2a26-432c-ae19-db4774e87a2f",
  "transactionStatus" : "REJECTED",
  "status" : "E0152",
  "message" : "Transaction rejected, issuer card not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "4b773f75-570a-4793-9cdc-6fbb41731b07",
  "links" : [ ]
}
HTTP Response - STATUS: E01580
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 299

{
  "requestUuid" : "980ab5f0-b0f0-491f-8b31-bd1c2e6f32db",
  "transactionStatus" : "REJECTED",
  "status" : "E01580",
  "message" : "Transaction rejected. Data center card is expired.",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "094a12ac-0f3b-4362-8b3d-728f8934b045",
  "links" : [ ]
}
HTTP Response - STATUS: E0200
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "requestUuid" : "f994063c-c6d3-4904-bc9a-468da477f939",
  "transactionStatus" : "REJECTED",
  "status" : "E0200",
  "message" : "Transaction rejected, card is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "cc29239d-3c34-4011-8b8b-272d31f2e382",
  "links" : [ ]
}
HTTP Response - STATUS: E0201
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 284

{
  "requestUuid" : "8a21609c-40be-4623-be47-06c7d40d796c",
  "transactionStatus" : "REJECTED",
  "status" : "E0201",
  "message" : "Transaction rejected, bin is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "466edf95-5c3d-4a52-ae2b-5190347632a6",
  "links" : [ ]
}
HTTP Response - STATUS: E0202
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 289

{
  "requestUuid" : "eb70f4ac-b55e-4fab-aaf4-96c120025c0d",
  "transactionStatus" : "REJECTED",
  "status" : "E0202",
  "message" : "Transaction rejected, terminal is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "cd5ba7ee-3d7e-4a2e-ad3c-8ea8559c09e4",
  "links" : [ ]
}
HTTP Response - STATUS: E0204
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 289

{
  "requestUuid" : "395a09bd-9daf-44ca-a34d-654e7dafc30f",
  "transactionStatus" : "REJECTED",
  "status" : "E0204",
  "message" : "Transaction rejected, user is on aml list",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "225c77b7-7565-4fbf-a79f-5f645727136b",
  "links" : [ ]
}
HTTP Response - STATUS: E0205
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "requestUuid" : "d28cafa9-bf27-4b7b-b9cc-8d978ffaec32",
  "transactionStatus" : "REJECTED",
  "status" : "E0205",
  "message" : "Transaction rejected, bank is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "53900670-caa0-4657-9a1a-6a339af768a1",
  "links" : [ ]
}
HTTP Response - STATUS: E0206
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 317

{
  "requestUuid" : "6158b027-e4bc-4a86-9814-79467cba2190",
  "transactionStatus" : "REJECTED",
  "status" : "E0206",
  "message" : "Transaction rejected, to many reject transactions and card is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "5d28d1bf-742e-4e09-9fa1-5cad9d78b8e9",
  "links" : [ ]
}
HTTP Response - STATUS: E01596
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 338

{
  "requestUuid" : "48406b13-8fdd-41d7-b2ad-ca9df2ef745c",
  "transactionStatus" : "REJECTED",
  "status" : "E01596",
  "message" : "Transaction rejected, terminal blocks transactions with card issued in given card country",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "427ab048-cf59-4897-a356-4f8c45dad24a",
  "links" : [ ]
}
HTTP Response - STATUS: E01597
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 386

{
  "requestUuid" : "5360881b-9dcc-44b9-94b8-95d336b9a9b2",
  "transactionStatus" : "REJECTED",
  "status" : "E01597",
  "message" : "Transaction rejected, 3DS version of terminal are not compatible with 3DS version defined in request. Please contact the sales department",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "2db61b2a-312a-4adc-8617-ffebd9db6298",
  "links" : [ ]
}
HTTP Response - STATUS: E01598
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 315

{
  "requestUuid" : "01c123c6-4857-461c-94f0-308cc0f0cb95",
  "transactionStatus" : "REJECTED",
  "status" : "E01598",
  "message" : "Transaction rejected, ECI value is not available for card provider",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "540fecdb-4538-4f62-ba82-1806ab9aae62",
  "links" : [ ]
}
Table 231. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

HTTP Response - STATUS: E01600
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 343

{
  "requestUuid" : "e4b9e04b-9924-4bfd-869a-1c887233d2c4",
  "transactionStatus" : "REJECTED",
  "status" : "E01600",
  "message" : "Transaction declined, 3DS 2.X flow invoked for other card number than specified in the request",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "a4ec5eaa-5cfe-4929-acf8-b3a240ca2cf0",
  "links" : [ ]
}
Table 232. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E0142
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 200

{
  "status" : "E0142",
  "message" : "Commission configuration not add for terminal",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "1c0a026a-abbe-47dd-a057-97c3b055c973",
  "links" : [ ]
}
HTTP Response - STATUS: E0153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 297

{
  "requestUuid" : "71590fd6-878e-4b2d-8cfb-fdf00777d3a5",
  "transactionStatus" : "PENDING",
  "status" : "E0153",
  "message" : "Transaction declined, problem with MIP connection",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "cc821c5a-f689-46a5-aba2-6279831537f2",
  "links" : [ ]
}
HTTP Response - STATUS: E01599
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 290

{
  "requestUuid" : "6a04949f-3c2f-4232-9a43-ef0f8f5b9a01",
  "transactionStatus" : "DECLINED",
  "status" : "E01599",
  "message" : "Transaction declined, processing timeout",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "b3641a30-1066-4461-8f9f-8585de47d6f2",
  "links" : [ ]
}
HTTP Response - STATUS: E0190
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 183

{
  "status" : "E0190",
  "message" : "Failed to get currency rates",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "deddc79f-74b4-4a2b-afc7-5e5c26aff916",
  "links" : [ ]
}
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:14:04 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "5c57a621-3342-4fb5-b16f-3a855124aa85"
}
Table 233. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

503 SERVICE UNAVAILABLE
HTTP Response - STATUS: E9001
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:03 GMT
Connection: close
Content-Length: 161

{
  "status" : "E9001",
  "message" : "Error acquirer connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "4574e22f-d368-46d0-91d5-42208ddb9e44"
}
HTTP Response - STATUS: E9010
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 275

{
  "requestUuid" : "ce1eb091-ef70-4c67-b399-0879e686308c",
  "transactionStatus" : "REJECTED",
  "status" : "E9010",
  "message" : "Error data center connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "9b554863-f243-4b11-9dbe-782ca1762675",
  "links" : [ ]
}
Table 234. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

6.7.2. CoF Subsequent transaction

POST /client/payments/cof/subsequent Content Type: application/json, Authorization: Basic Auth
The second phase is the subsequent transaction, which requires a successful initial transaction containing the consent to store card data.
Merchant provides the cofInitialUuid parameter received in the initial transaction, which defines the customer's card data saved in the transaction.
Subsequent transactions are intended for multiple execution.

From January 2021, there is an internal functionality to restrict access for the PSP to specific method. The Fenige employee can disable access to a given endpoint, then the HTTP status 403 FORBIDDEN will be returned. The PSP will be informed about each access restriction action.

Request
Simple request
HTTP Request
POST /client/payments/cof/subsequent HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 278
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "9c37fcca-00bc-4a4c-a311-0e76eefe3c2c",
  "requestUuid" : "5a279ffd-516c-4845-b4ed-42a63fcd3fa4",
  "cofInitialUuid" : "c9ee09a8-e843-43d6-b416-e46ca109005e",
  "amount" : 1000,
  "currency" : "USD",
  "autoClear" : true,
  "transactionRef" : "27F3250GU3"
}
Table 235. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 236. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

cofInitialUuid

String

@Must not be null

CoF initial transaction identifier uuid

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Request with forced Terminal
HTTP Request
POST /client/payments/cof/subsequent HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 337
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "7fa3c45d-6173-4bac-9426-97ab0ac1a863",
  "terminalUuid" : "c9712279-0d0f-40e0-b4f9-4258d5c4ac63",
  "requestUuid" : "210b76ae-ea54-475f-a889-adf90de7c667",
  "cofInitialUuid" : "7fa3c45d-6173-4bac-9426-97ab0ac1a863",
  "amount" : 1000,
  "currency" : "USD",
  "autoClear" : true,
  "transactionRef" : "27F3250GU3"
}
Table 237. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 238. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

cofInitialUuid

String

@Must not be null

CoF initial transaction identifier uuid

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

terminalUuid

String

Terminals’s unique uuid in system

Response
Status Description

200 OK

Returned when transaction was successfully authorized.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

STATUS: E8001 - Returned when server understood the request but refuses to authorize 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: E01590 - Returned when transaction is rejected, because initial CoF card not found in DC.

STATUS: E01591 - Returned when transaction is rejected, because initial CoF transaction not approved.

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: 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

500 INTERNAL SERVER ERROR

STATUS: E0142 - Returned when commission configuration is not added for terminal.

STATUS: E0153 - Returned when transaction is declined, by problem with MIP connection.

STATUS: E01599 - Transaction declined, processing timeout.

STATUS: E0190 - Returned when currency rate is invalid.

STATUS: E9000 - Returned when reason is unknown.

STATUS: E9008 - Returned when mpi received 3ds subsequentize failed.

503 SERVICE UNAVAILABLE

STATUS: E9001 - Returned when is error acquirer connection.

STATUS: E9002 - Returned when is error mpi connection.

STATUS: E9010 - Returned when is error data center connection.

200 OK
HTTP Response - transaction
{
  "requestUuid" : "3aa47f03-020e-4258-a2f5-d334252fdd12",
  "cofInitialUuid" : "6d20331b-730b-4883-abbd-0aa4205f3a7d",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "status" : "S0002",
  "message" : "Success transaction",
  "httpStatus" : "OK",
  "links" : [ ]
}
Table 239. Response fields
Path Type Description

requestUuid

String

Request unique uuid in system

cofInitialUuid

String

CoF transaction unique uuid in system

transactionStatus

String

Transaction status

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

responseCode

String

Response code

links

Array

Links to other resources

400 BAD REQUEST
HTTP Response - STATUS: E8000
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:12:24 GMT
Connection: close
Content-Length: 345

{
  "errors" : {
    "amount" : [ "must not be null" ],
    "merchantUuid" : [ "must not be null" ],
    "requestUuid" : [ "must not be null" ],
    "currency" : [ "must not be null" ],
    "cofInitialUuid" : [ "must not be null" ]
  },
  "status" : "E8000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "90d29f17-44fb-4eef-bcf0-2327b165e470"
}
Table 240. Response fields
Path Type Description

status

String

Response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

401 UNAUTHORIZED
HTTP Response - STATUS: E8002
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: 158
Date: Thu, 22 Jul 2021 22:12:24 GMT

{
  "status" : "E8002",
  "message" : "Unauthorized",
  "httpStatus" : "UNAUTHORIZED",
  "traceId" : "a54f2bf2-204d-4d1e-9d5e-cf01669c1827",
  "links" : [ ]
}
Table 241. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

403 FORBIDDEN
HTTP Response - STATUS: E8001
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: 152
Date: Thu, 22 Jul 2021 22:12:26 GMT

{
  "status" : "E8001",
  "message" : "Forbidden",
  "httpStatus" : "FORBIDDEN",
  "traceId" : "bf420bff-f5c2-4dd5-85c4-73fa022f8474",
  "links" : [ ]
}
Table 242. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

404 NOT FOUND
HTTP Response - STATUS: E0122
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 163

{
  "status" : "E0122",
  "message" : "Merchant not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "bc206dbf-2283-46c9-bb12-bd4a3c4c4ddc",
  "links" : [ ]
}
HTTP Response - STATUS: E0132
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 163

{
  "status" : "E0132",
  "message" : "Terminal not exists.",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "706cc752-837a-472d-9719-e3e6561ff03e",
  "links" : [ ]
}
HTTP Response - STATUS: E0135
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 180

{
  "status" : "E0137",
  "message" : "Default terminal not exist",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "d9aa8dd5-8b78-4f42-87cc-140dcc0ad076",
  "links" : [ ]
}
HTTP Response - STATUS: E0137
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 176

{
  "status" : "E0135",
  "message" : "Terminals for merchant not exists",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "6df556dd-7387-488c-b864-904ed4926957",
  "links" : [ ]
}
Table 243. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E0150
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 268

{
  "requestUuid" : "1a0d1fae-25f1-4d7b-bc38-5e49e6797f52",
  "transactionStatus" : "REJECTED",
  "status" : "E0150",
  "message" : "Transaction rejected",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "3ae6f56a-c7ab-42ec-82a1-9bbc40c31f61",
  "links" : [ ]
}
HTTP Response - STATUS: E0151
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 292

{
  "requestUuid" : "7bf89b7a-8196-4ec1-8543-f42bbffc13cb",
  "transactionStatus" : "REJECTED",
  "status" : "E0151",
  "message" : "Transaction rejected, currency not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "985e902b-3f1e-474b-805d-a732532e4166",
  "links" : [ ]
}
HTTP Response - STATUS: E0152
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 295

{
  "requestUuid" : "e8855318-6522-4f37-bbc3-f297522400ae",
  "transactionStatus" : "REJECTED",
  "status" : "E0152",
  "message" : "Transaction rejected, issuer card not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "9c745047-7c54-4234-985b-971455b21617",
  "links" : [ ]
}
HTTP Response - STATUS: E01590
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 295

{
  "requestUuid" : "baa18ca3-e966-466a-b6ba-954a614cb822",
  "transactionStatus" : "REJECTED",
  "status" : "E01590",
  "message" : "Transaction rejected, cof card not found in db",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "9efe1b7c-b5e3-44dc-8c59-d3e87f65613f",
  "links" : [ ]
}
HTTP Response - STATUS: E01591
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 295

{
  "requestUuid" : "d3ebb30b-873b-4b47-893c-9125063e4562",
  "transactionStatus" : "REJECTED",
  "status" : "E01590",
  "message" : "Transaction rejected, cof card not found in db",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "0a37fb9a-44bb-4183-97bd-762a6805d28f",
  "links" : [ ]
}
HTTP Response - STATUS: E0200
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "requestUuid" : "da641f7b-67e2-4e11-8797-cb4fae865635",
  "transactionStatus" : "REJECTED",
  "status" : "E0200",
  "message" : "Transaction rejected, card is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "03f4f28b-78c0-412e-a8af-87e64991fcef",
  "links" : [ ]
}
HTTP Response - STATUS: E0201
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 284

{
  "requestUuid" : "10ea6c2e-59e7-4eb8-afa2-19bdb86837ff",
  "transactionStatus" : "REJECTED",
  "status" : "E0201",
  "message" : "Transaction rejected, bin is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "94d7adf4-6c02-49e8-bf05-04f11a0ba15a",
  "links" : [ ]
}
HTTP Response - STATUS: E0202
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 289

{
  "requestUuid" : "8ba5bb84-93c8-4ca0-a836-1b64968eabd8",
  "transactionStatus" : "REJECTED",
  "status" : "E0202",
  "message" : "Transaction rejected, terminal is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "ad34cb49-4d62-4922-82f4-4b2c2bd937f2",
  "links" : [ ]
}
HTTP Response - STATUS: E0204
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 289

{
  "requestUuid" : "f73d186e-9870-4688-a784-263a5ab47b8d",
  "transactionStatus" : "REJECTED",
  "status" : "E0204",
  "message" : "Transaction rejected, user is on aml list",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "dfa09dda-2e6a-4b2e-b6c7-0efbafcac0e4",
  "links" : [ ]
}
HTTP Response - STATUS: E0205
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "requestUuid" : "188e2864-411c-4600-8a4d-5f5bebeb0ef9",
  "transactionStatus" : "REJECTED",
  "status" : "E0205",
  "message" : "Transaction rejected, bank is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "67a5787a-c726-4745-a23f-72240d1cb5d6",
  "links" : [ ]
}
Table 244. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

requestUuid

String

Request unique uuid in system

transactionStatus

String

Transaction status

links

Array

Links to other resources

HTTP Response - STATUS: E0206
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 317

{
  "requestUuid" : "6158b027-e4bc-4a86-9814-79467cba2190",
  "transactionStatus" : "REJECTED",
  "status" : "E0206",
  "message" : "Transaction rejected, to many reject transactions and card is blocked",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "5d28d1bf-742e-4e09-9fa1-5cad9d78b8e9",
  "links" : [ ]
}
500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E0142
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 200

{
  "status" : "E0142",
  "message" : "Commission configuration not add for terminal",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "54bae4bd-8095-4a3a-9ae1-1ed36c463e06",
  "links" : [ ]
}
HTTP Response - STATUS: E0153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 297

{
  "requestUuid" : "9fcb1645-e67b-489a-a13e-9bdba27a1159",
  "transactionStatus" : "PENDING",
  "status" : "E0153",
  "message" : "Transaction declined, problem with MIP connection",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "4d61ac13-9efc-4b47-9e92-c80c70a38123",
  "links" : [ ]
}
HTTP Response - STATUS: E01599
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 290

{
  "requestUuid" : "f58be60b-07db-4d97-9a61-ef0068a0f0d6",
  "transactionStatus" : "DECLINED",
  "status" : "E01599",
  "message" : "Transaction declined, processing timeout",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "0ee3d897-b754-44f7-8ba0-2c8838ede86d",
  "links" : [ ]
}
HTTP Response - STATUS: E0190
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 183

{
  "status" : "E0190",
  "message" : "Failed to get currency rates",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "acd54886-b110-45de-a44f-371b73285055",
  "links" : [ ]
}
HTTP Response - STATUS: E9000
HTTP/1.1 500 Internal Server Error
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:14:04 GMT
Connection: close
Content-Length: 150

{
  "status" : "E9000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "5c57a621-3342-4fb5-b16f-3a855124aa85"
}
Table 245. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

503 SERVICE UNAVAILABLE
HTTP Response - STATUS: E9001
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/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 22 Jul 2021 22:15:03 GMT
Connection: close
Content-Length: 161

{
  "status" : "E9001",
  "message" : "Error acquirer connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "4574e22f-d368-46d0-91d5-42208ddb9e44"
}
HTTP Response - STATUS: E9010
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 181

{
  "status" : "E9010",
  "message" : "Error data center connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "cbcab20e-7fe5-4344-9ab2-d413c6183171",
  "links" : [ ]
}
Table 246. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Unique id for this http request register in system

links

Array

Links to other resources

6.8. Recurring payment

    A Recurring Payment is a type of the transaction performed as a result of an agreement between a cardholder and a merchant in which the cardholder authorizes
the merchant to bill the cardholder’s Mastercard account, with no specified end date. Billing may occur periodically, such as monthly, quarterly or annually.
Each payment may be for a variable or a fixed amount.
    The method is used to charge the cardholder with no need to collect account data (PAN, exp date) from merchant at every transaction. Only initial transaction requires providing
card information which are saved in secure Fenige environment according to PCI-DSS Compliance.
    This endpoint is idempotent so if you execute more than one requests with the same data even at the same time, only first registered transaction will be processed further. In
response, we receive transaction status.
The Recurring Payment consists of two parts: initial and subsequent, which are discussed in detail below.
Please see detailed Recurring Payment with 3-DS flow described on below listing.
The Fenige Payment API methods optionally allows merchants to store card data and sensitive personal data in order to allow performing subsequent transactions.
If merchant decides to use DataCenter transaction flow then is required to provide the card id of the card previously stored in the Fenige DataCenter, from which card the
relevant required parameters will be downloaded and used for authorization.
Card data and sensitive personal data according to the Fenige API specification are: cardNumber, expiryDate, firstName, lastName and email.
All card data are stored securely on Fenige DataCenter servers in accordance with applicable security requirements.
Recurring payment with outside 3DS flow
recurring trx outside3ds flow
Recurring payment with DataCenter outside 3DS flow
recurring trx datacenter outside3ds flow
Recurring payment with 3ds flow
recurring trx 3ds flow
Recurring payment with DataCenter flow
recurring trx data center flow

6.8.1. Recurring Initial transaction

POST /client/payments/recurring/initial Content Type: application/json, Authorization: Basic Auth
    The start phase is a one-time initial transaction, which is a simple e-commerce payment with forced 3-DS authentication, but contains the customer's consent to store card data
for recurring subsequent purchases. Card data are stored in a secure FENIGE environment.
    After completing the recurring initial merchant receives the unique recurringInitialUuid identifier needed to perform subsequent Recurring Payments transactions without
    having to enter card data in the future.

From January 2021, there is an internal functionality to restrict access for the PSP to specific method. The Fenige employee can disable access to a given endpoint, then the HTTP status 403 FORBIDDEN will be returned. The PSP will be informed about each access restriction action.

Request
Simple request
HTTP Request
POST /client/payments/recurring/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 469
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "9c37fcca-00bc-4a4c-a311-0e76eefe3c2c",
  "requestUuid" : "1648f0cf-1890-49f1-8514-fbc3424cc5dd",
  "firstName" : "user",
  "lastName" : "testUser",
  "cardNumber" : "5453131785534417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "amount" : 1000,
  "currency" : "USD",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 247. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 248. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

First name of card holder

lastName

String

Last name of card holder

cardNumber

String

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Request with forced Terminal
HTTP Request
POST /client/payments/recurring/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 570
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "43983300-2d24-4e25-8019-a36127bd5002",
  "terminalUuid" : "82c34385-7512-4ffc-a80b-0d44a1f1e5b0",
  "requestUuid" : "ec2f4914-a577-4e6b-9b4c-bb2622f1e505",
  "firstName" : "user",
  "lastName" : "testUser",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "5453131785534417",
  "cardId" : null,
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "email" : "test@fenige.pl",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "outside3ds" : null,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 249. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 250. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

firstName

String

First name of card holder

lastName

String

Last name of card holder

cardNumber

String

Full cardholder’s card number must be between 12-digits and 19-digits

expiryDate

String

Expiration date of card mm/yy

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

email

String

Optional field, @Length(min = 1, max = 128)

Cardholder’s email

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

terminalUuid

String

Terminals’s unique uuid in system

Request with DataCenter card
HTTP Request
POST /client/payments/recurring/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 347
Host: ecom-staging.fenige.pl

{
  "merchantUuid" : "9c37fcca-00bc-4a4c-a311-0e76eefe3c2c",
  "requestUuid" : "b7e3ade3-eca5-4da6-9b9e-cfdd7a56a45e",
  "cvc2" : "123",
  "cardId" : 1906455,
  "amount" : 1000,
  "currency" : "USD",
  "addressIp" : "192.0.0.1",
  "autoClear" : true,
  "terminalUrl" : "https://ecom-staging.fenige.pl/payments",
  "transactionRef" : "27F3250GU3"
}
Table 251. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 252. Authorize request fields
Path Type Constraints Description

merchantUuid

String

@Must not be null

Merchant’s unique uuid in system

requestUuid

String

@Must not be null

Request’s unique uuid in system

cardId

Number

@Must not be null, @Numeric

DataCenter card id. Required to obtain card information data from DataCenter such as (cardNumber, expiryDate, firstName, lastName, email)

cvc2

String

@Length must be 3 characters, @Must not be blank, @Must not be null

Cardholder’s card cvc2

amount

Number

@Must be at least 100, @Must not be null

The total transfer amount (in pennies)

currency

String

@Must not be null

Currency for transaction (in accordance with ISO-4217), example: USD

addressIp

String

Optional field, @Must match the regular expression ^([0-9]{1,3}.){3}[0-9]{1,3}$

The IP address of the order of transaction. Optional field, mandatory from 2021-05-03

autoClear

Boolean

Is auto clear enabled. Enabled if true, is not enabled if false

terminalUrl

String

@Optional

Terminal identifier such as the business website URL or reverse domain name as presented to the consumer during checkout. Optional field, mandatory from 2021-05-03

transactionRef

String

@Optional, @Length must be between 1 and 10, @Must not be blank, @Must match the regular expression ^[a-zA-Z0-9]*$

An additional transaction identifier defined by the merchant. This can be, for example, the document number of a sales receipt or the number of an offer or product

Response
Status Description

200 OK

Returned when transaction was successfully authorized.

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 you are the problem with authorized to your PSP.

403 FORBIDDEN

STATUS: E8001 - Returned when server understood the request but refuses to authorize 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

STATUS: E06003 - Returned when DataCenter card was not found.

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: E01596 - Returned when transaction is rejected, because terminal has blocked transaction with card issued in restricted country

STATUS: E01580 - Returned when transaction is rejected, because DataCenter card was expired.

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: 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: E01600 - Returned when transaction is declined, because 3DS 2.X flow invoked for other card number than specified in the request

500 INTERNAL SERVER ERROR

STATUS: E0142 - Returned when commission configuration is not added for terminal.

STATUS: E0153 - Returned when transaction is declined, by problem with MIP connection.

STATUS: E01599 - Transaction declined, processing timeout.

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.

STATUS: E9010 - Returned when is error DataCenter connection.

200 OK (with 3DS)
HTTP Response - transaction with 3DS
{
  "requestUuid" : "8288d395-815f-4bfa-a615-9f3c49cfed43",
  "recurringInitialUuid" : "cf6cad17-d522-4f63-97e1-ba61dab8a1e4",
  "transactionStatus" : "WAITING_ON_3DS_CONFIRMATION",
  "pareq" : "eJxlkltvwjAMhf8K4p3m0qRUlYnE4GHVxMQuT3uLWguK2lDSFsG/n8NlbFqkSD6Oe+p8DnxuPeLyA4vBo4EVdp3d4KgqZ2M5lWpsYD1/x4OBI/qu2jsjIh5JYHdJX/hia11vwBaHp/zVaCVEooDdJDTo86XhtCa0BbBrApxt0HToStUgsIuCYj+43p9NIhJgdwGDr82279suY2xnj3ZS4hFrEQ2trcqorbNUqZgVdYWuBxaqgT3aWg8h6sj9VJUmX8w3//Yyj1e7txmwUAGl7dFILlIeSz4SOlM60ymwSx5sE9oyi6+XUax5xDnd9JqCNvxpfhV0Fo5+p4AQe3TFmcxjut5dAZ7avaPeDXH9iYE9Gl88B7pFT9jiADIsRSxpQKlKtNRqmsiUkN2KgmNF5CTn+mIZBLBgw27jJECXSVP05wV8A1/aqWQ=",
  "acsUrl" : "https://ecom-staging.fenige.pl/fenige-mpi",
  "md" : "ZTkwYjU3N2YtNzU5Ny00ZWM5LWE2MDAtZjQ4YWVmZDgzMjhm",
  "formBase64" : "PGh0bWw+PFNDUklQVCBMQU5HVUFHRT0iSmF2YXNjcmlwdCI+ZnVuY3Rpb24gT25Mb2FkRXZlbnQoKXsgZG9jdW1lbnQuZG93bmxvYWRGb3JtLnN1Ym1pdCgpOyB9PC9TQ1JJUFQ+PGJvZHkgT25Mb2FkPSJPbkxvYWRFdmVudCgpOyI+PGZvcm0gbmFtZT0iZG93bmxvYWRGb3JtIiBhY3Rpb249Imh0dHBzOi8vamF2YS1kZXZlbC5mZW5pZ2UucGw6ODE4MS9mZW5pZ2UtbXBpIiBtZXRob2Q9IlBPU1QiPjxJTlBVVCB0eXBlPSJoaWRkZW4iIG5hbWU9IlBhUmVxIiB2YWx1ZT0iZUp4bGtsdHZ3akFNaGY4SzRwM20wcVJVbFluRTRHSFZ4TVF1VDN1TFdndUsybERTRnNHL244TmxiRnFrU0Q2T2UrcDhEbnh1UGVMeUE0dkJvNEVWZHAzZDRLZ3FaMk01bFdwc1lEMS94NE9CSS9xdTJqc2pJaDVKWUhkSlgvaGlhMTF2d0JhSHAvelZhQ1ZFb29EZEpEVG84NlhodENhMEJiQnJBcHh0MEhUb1N0VWdzSXVDWWorNDNwOU5JaEpnZHdHRHI4MjI3OXN1WTJ4bmozWlM0aEZyRVEydHJjcW9yYk5VcVpnVmRZV3VCeGFxZ1QzYVdnOGg2c2o5VkpVbVg4dzMvL1l5ajFlN3R4bXdVQUdsN2RGSUxsSWVTejRTT2xNNjB5bXdTeDVzRTlveWk2K1hVYXg1eERuZDlKcUNOdnhwZmhWMEZvNStwNEFRZTNURm1jeGp1dDVkQVo3YXZhUGVEWEg5aVlFOUdsODhCN3BGVDlqaUFESXNSU3hwUUtsS3ROUnFtc2lVa04yS2dtTkY1Q1RuK21JWkJMQmd3MjdqSkVDWFNWUDA1d1Y4QTEvYXFXUT0iPjxpbnB1dCB0eXB