1. Changelog

Version Date Description

1.0

2020-05-25

First release of API Processor documentation.

1.1

2020-06-01

DCC Payment method description changed.

1.2

2020-06-16

Changes in the CSV file structure in Fee Collection Clearing System and Interchange Report.

1.3

2020-06-30

Update MasterCard statuses table.

1.4

2020-06-30

Update VISA reports.

1.5

2020-07-01

New method "Card Provider" added.

1.6

2020-07-06

Update diagrams.

1.7

2020-07-10

Added MasterCard reports csv example.

1.8

2020-07-27

Added VISA reports csv example.

1.9

2020-08-31

Added Mastercard reports txt example.

1.10

2020-09-09

Added Mastercard Settlement Position Details report.

1.11

2020-09-14

Added MO/TO payment.

1.12

2020-09-20

Added Installment Payment API methods.

1.13

2020-10-07

MO/TO DCC payment status E00158 added.

1.14

2020-10-08

Added 3DS 2.X API methods.

1.15

2020-10-09

Added Mastercard Currency Update report.

1.16

2020-10-14

Added new VISA response code value 80.

1.17

2020-11-05

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

1.18

2020-11-06

Added new columns to the Interchange report.

1.19

2021-01-18

Added merchant configuration to 3DS 1.X initialize method.

1.20

2021-01-19

Added in the Currency for card method the cardholderCurrencyIndicator field that determines if the card supports DCC.

1.21

2021-01-21

Added new field merchantUrl do 3ds 2.x 4.2. Authentication method.

1.22

2021-01-26

Added new fields in the response: provider and cardType to methods: 5.1. Currency for card, 5.4. Payment, 5.13. Details.

1.23

2021-03-10

Remove status E00157 and allow processing of all types of payment transactions using quasi-cash terminal mcc.

1.23

2021-05-04

New file 'Clearing Detail File' report introduced.

1.24

2021-06-24

Added a new payment method Token payment.

1.25

2021-06-24

Added new field cryptoCurrency in the terminal objects for terminals that process cryptocurrency transactions.

1.26

2021-07-22

Added new field specialConditionIndicatorExistingDebt in the terminal objects, this field indicates the cardholder is making a payment on a debt.

1.27

2021-07-30

Added validation on transactionUuid uniqueness (per merchant.merchantId) field in payment (according to the documentation) and new response status - E001598 Transaction rejected, transactionUUID already exists.

1.28

2021-08-23

Added defaultCurrency field to responses returned after a transaction. Added description to Product ID field for Visa.

1.29

2021-10-18

Added description of the use case of the Google pay method.

1.30

2021-10-25

Added validation on ECI and ability to perform transactions with status U on 3ds, new status E001596

1.31

2021-12-06

Updated validation for purchaseAmount in Authentication request in 3DS 2.X verification methods

1.32

2021-12-06

Added transactionInitiator field for Recurring/CoF subsequent transactions to differ MIT/CIT/RECURRING_PAYMENT. Add optional outside3ds requests param for CIT/RECURRING_PAYMENT based CoF/recurring.

1.33

2021-12-27

Added DCC request refund option to allow refund processing in cardholder currency.

1.34

2022-03-01

Added new field in the response: productCategory to method: 5.1. Currency for card.

1.35

2022-03-09

Added new statuses:

E001561 which is thrown when subsequent transaction was executed with other merchantId than the one that was used in initial recurring transaction.

E001591 which is thrown when subsequent transaction was executed with other merchantId than the one that was used in initial CoF transaction.

1.36

2022-03-16

Allow processing multiple refunds for transaction up to clearing amount. Transaction details expanded with refund list history. Remove E00184 status. Added statuses E00189 and E00190.

1.37

2022-03-31

Add new response status S00010 during refund processing clearing to notify that refund was reported for transaction.

1.38

2022-04-13

Added new methods to register merchants in the 3ds 2.X Mastercard system - works on webhooks.

1.39

2022-05-16

Add paymentData object request for CoF/Recurring payments token cards processing

2. Introduction

Fenige Processor 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.

3ds authorize payment request processor
Figure 1. E-commerce flow

2.1. Endpoints

Environment Endpoint (base url)

Staging

https://processor-staging.fenige.pl

2.2. 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 YWNxdWlyZXJuYW1lOnBhc3N3b3Jk

Required

Basic Auth from Acquirer data (acquirer name and password). Consist of keyword Basic and string obtained from Base64 coding method for Acquirer name and password parameter

2.3. 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.4. 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

409 CONFLICT

This response status code indicates a request conflict with current state of the target resource.

422 UNPROCESSABLE ENTITY

This response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.

500 INTERNAL SERVER ERROR

Message occur when an unexpected condition was encountered

Table 1. Response status - Transaction
Code Messages HTTP Code HTTP STATUS

S00000

SUCCESS

200

OK

S00002

Success transaction

200

OK

S00003

Transaction declined, check response code for reason

200

OK

S00004

PENDING

202

ACCEPTED

S00005

Success reverse transaction

200

OK

S00006

Reverse transaction declined, check response code for reason

200

OK

Table 2. Response status - JSON Errors

Code

Messages

HTTP Code

HTTP STATUS

E00111

Invalid format JSON

422

UNPROCESSABLE ENTITY

Table 3. Response status - Currency Errors

Code

Messages

HTTP Code

HTTP STATUS

E00141

Currency rate not found

404

NOT FOUND

E00143

Currency not found

404

NOT FOUND

Table 4. Response status - Transaction Errors
Code Messages HTTP Code HTTP STATUS

E00150

Transaction rejected

422

UNPROCESSABLE ENTITY

E00151

Transaction rejected, currency not supported

422

UNPROCESSABLE ENTITY

E00152

Transaction rejected, issuer not supported

422

UNPROCESSABLE ENTITY

E00153

Transaction declined, problem with MIP connection

500

INTERNAL SERVER ERROR

E00155

Transaction not exist

404

NOT FOUND

E00156

Transaction rejected, initial recurring transaction not approved/exist

422

UNPROCESSABLE ENTITY

E001561

Transaction rejected, invalid initial recurring merchantId

422

UNPROCESSABLE ENTITY

E00158

Transaction rejected, invalid Cardholder Currency Indicator for DCC transaction

422

UNPROCESSABLE ENTITY

E00159

Transaction rejected, initial CoF transaction not approved/exist

422

UNPROCESSABLE ENTITY

E001591

Transaction rejected, invalid initial CoF merchantId

422

UNPROCESSABLE ENTITY

E001596

Transaction rejected, ECI value is not available for card provider

422

UNPROCESSABLE ENTITY

E001597

Transaction declined, processing timeout

500

INTERNAL SERVER ERROR

E001598

Transaction rejected, transactionUUID already exists

409

CONFLICT

E00160

Transaction rejected, cvc2 is required if no 3DS has been made

422

UNPROCESSABLE ENTITY

E001602

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

422

UNPROCESSABLE ENTITY

E001603

Transaction rejected, ECI value is not valid for Card Authentication. Only if 3DS Authentication Status = U and eci is not equal 00 or 07.

422

UNPROCESSABLE ENTITY

Table 5. Response status - Reversal Errors
Code Messages HTTP Code HTTP STATUS

E00161

Can’t reversal payment

422

UNPROCESSABLE ENTITY

E00162

Payment is already reversed

422

UNPROCESSABLE ENTITY

Table 6. Response status - Clearing Errors
Code Messages HTTP Code HTTP STATUS

E00170

Clearing of the payment is processing

422

UNPROCESSABLE ENTITY

E00171

Can’t replay payment

422

UNPROCESSABLE ENTITY

E00172

Can’t replay payment, the time is over

422

UNPROCESSABLE ENTITY

E00173

Payment is automatically cleared

422

UNPROCESSABLE ENTITY

E00174

Payment is already cleared

422

UNPROCESSABLE ENTITY

E00175

Can’t replay payment, clearing amount is to low

422

UNPROCESSABLE ENTITY

E00176

Can’t replay payment, clearing amount is to high

422

UNPROCESSABLE ENTITY

Table 7. Response status - Refund Errors
Code Messages HTTP Code HTTP STATUS

E00180

Refund rejected, no MC/VISA response

500

INTERNAL SERVER ERROR

E00181

Refund rejected by MC/VISA

500

INTERNAL SERVER ERROR

E00182

Refund transaction amount to low

400

BAD REQUEST

E00183

Refund transaction amount to high

400

BAD REQUEST

E00185

Transaction not cleared, can’t refund

422

UNPROCESSABLE ENTITY

E00186

Refund is already processing

422

UNPROCESSABLE ENTITY

E00187

Transaction is chargeback reported

422

UNPROCESSABLE ENTITY

E00188

Unable to refund. The transaction is Installment Payment processing.

422

UNPROCESSABLE ENTITY

E00189

Refund rejected, refundUuid non unique in system

422

UNPROCESSABLE ENTITY

E00190

Refund rejected, the cumulative refund amount exceeding transaction cleared amount

422

UNPROCESSABLE ENTITY

Table 8. Response status - Intallment Payment Errors
Code Messages HTTP Code HTTP STATUS

E001900

Installment Payment initial not found

500

INTERNAL_SERVER_ERROR

E001901

Installment Payment already confirmed

500

INTERNAL_SERVER_ERROR

E001902

Installment Payment already cancelled

INTERNAL_SERVER_ERROR

500

E001903

Installment Payment already pay in full

INTERNAL_SERVER_ERROR

500

E001904

Installment Payment not confirmed in required time

INTERNAL_SERVER_ERROR

500

E001905

Installment Payment Initial was failed

INTERNAL_SERVER_ERROR

500

E001906

Installment Payment could not find valid installment plan for requested uuid

INTERNAL_SERVER_ERROR

500

E001907

Installment Payment Option not allowed for transaction

INTERNAL_SERVER_ERROR

500

E001908

Installment Payment missing plan uuid"

INTERNAL_SERVER_ERROR

500

E001909

Installment Payment missing request number of installments

INTERNAL_SERVER_ERROR

500

E001910

Installment Payment requested number of installments is outside of allowed range

INTERNAL_SERVER_ERROR

500

E001911

Installment Payment reverse not allowed

INTERNAL_SERVER_ERROR

500

E001912

Installment Payment refund not allowed

INTERNAL_SERVER_ERROR

500

E001913

Installment Payment unsupported card provider VISA

INTERNAL_SERVER_ERROR

500

Table 9. Response status - 3DS 2.X
Code Messages HTTP Code HTTP STATUS

E03000

Error mpi V2 - failed internal

500

INTERNAL_SERVER_ERROR

E03001

Three DS Method Data mismatch

422

UNPROCESSABLE_ENTITY

E03002

Error on parsing Three DS Method Data

422

UNPROCESSABLE_ENTITY

E03003

Card number not Enrolled in 3DS v2

422

UNPROCESSABLE_ENTITY

E03004

Invalid card authentication id

422

UNPROCESSABLE_ENTITY

E03005

Issuer card is not supported

422

UNPROCESSABLE_ENTITY

E03006

Invalid card number

422

UNPROCESSABLE_ENTITY

E03007

Card Authentication not found

404

NOT_FOUND

E03009

Protocol version is not supported

422

UNPROCESSABLE_ENTITY

E03010

Invalid Three DS Method Data

422

UNPROCESSABLE_ENTITY

Table 10. Response status - Global Errors
Code Messages HTTP Code HTTP STATUS

E80000

Bad Request

400

BAD REQUEST

Table 11. Response status - Fatal Errors

Code

Messages

HTTP Code

HTTP STATUS

E90000

Domain error

500

INTERNAL SERVER ERROR

E90001

Error acquirer connection

503

SERVICE_UNAVAILABLE

E90002

Error mpi connection

503

SERVICE_UNAVAILABLE

E90004

Unable to read dek file

500

INTERNAL SERVER ERROR

E90005

Decryption error

500

INTERNAL SERVER ERROR

E90006

Encryption error

500

INTERNAL SERVER ERROR

E90007

Error mpi - 3ds initialize failed

500

INTERNAL SERVER ERROR

E90008

Error mpi - 3ds finalize failed

500

INTERNAL SERVER ERROR

2.5. Mastercard/VISA statuses

Table 12. 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

Pick up card, special condition (fraud account)

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 (first 8 digits of account number do not relate to an issuing identifier)

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. Used by switch when function requested is not allowed for product or card type

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/ PIN data required (Europe Region only) (Visa)

CODE_71

PIN Not Changed

CODE_75

Allowable number of PIN-entry 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 or special condition (account is temporarily blocked) (Visa)

CODE_79

Life cycle (Mastercard use only)

CODE_80

No financial impact (used in reversal responses to declined originals)

CODE_81

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

CODE_82

Negative Online CAM, dCVV, iCVV, or CVV results/Offline PIN authentication interrupted/Policy (Mastercard use only)

CODE_83

Fraud/Security (Mastercard use only)

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/Cannot verify PIN

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 or switch 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 or appoved 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

CODE_1A

Additional customer authentication required (Europe Region only)

CODE_6P

Verification Failed (Cardholder Identification does not match issuer records)

3. 3DS 1.0 verification methods

The 3ds method provides the opportunity for additional verification of the card holder. The goal  is to increase security and confidence in online payment. Verification is performed by sending a special security token to the address specified by the user (initialize 3DS method). Verification require by the user to log in bank system. Finalization of the 3DS process require passing received in initialize step parameters.
3ds 2.X and 3ds 1.0 flow
3ds api

3.1. Initialize

POST /processor/3ds/initialize Content Type: application/json, Authorization: Basic Auth
Method initialize verification process by sending required transaction data and generate special form for user to log in.
Success verify enrollment response. MPI return one of statuses:
Y (Card Enrolled) - Cardholder is enrolled, activation is supported, or proof of attempted authentication available.

Error verify enrollment response. MPI return one of statuses:
N (Card Not Enrolled) - Cardholder not participating – cardholder is not enrolled.
U (Card Enrolled Status Unavailable) - Unable to authenticate or card not eligible for attempts.

3.1.1. Request

POST /processor/3ds/initialize HTTP/1.1
Authorization: Basic bmFtZTpwYXNzd29yZA==
Content-Type: application/json
Content-Length: 555
Host: processor-staging.fenige.pl

{
  "requestUuid" : "9f274f9f-bea5-42e9-84e6-222b40eb668f",
  "merchantName" : "TestMerchant",
  "merchantCountryCode" : "616",
  "merchantId" : "100",
  "merchantUrl" : "https:\\/\\/merchant-site.com",
  "cardNumber" : "5453010000095141",
  "cardExpMonth" : "12",
  "cardExpYear" : "18",
  "transactionAmount" : "200",
  "transactionDescription" : "Transaction description",
  "transactionDisplayAmount" : "2,00 PLN",
  "currencyCode" : "840",
  "currencyExponent" : "2",
  "termUrl" : "https:\\/\\/url",
  "md" : "d5cb12d4-3767-4439-b196-46126e8af64c"
}
Table 13. INITIALIZE 3DS REQUEST FIELDS
Path Type Constraints Description

requestUuid

String

@Must not be null

Request’s unique uuid in system

merchantName

String

@Length must be between 0 and 25 inclusive, @Must not be null

Merchant name visible on the 3ds confirmation form from the bank

merchantCountryCode

String

@Must match the regular expression \d+, @Must not be null

Merchant country code location. These codes are specified by ISO-3166

merchantId

String

@Must not be null

Merchant ID registered in DirectoryServer. This is not the same value as the transaction!

merchantUrl

String

@Must not be null

Merchant website

cardNumber

String

@Must be a number and length must be between 12 and 19, @Luhn

Transaction card number used in verification process

cardExpMonth

String

@Length must be between 2 and 2 inclusive, @Must match the regular expression \d+, @Must not be null

Sender card expiry month mm

cardExpYear

String

@Length must be between 2 and 2 inclusive, @Must match the regular expression \d+, @Must not be null

Sender card expiry year yy

transactionAmount

String

@Must match the regular expression \d+, @Must not be null

Transaction amount (in pennies)

transactionDescription

String

@Must not be blank

Transaction description

transactionDisplayAmount

String

@Must not be null

Amount displayed in mpi form

currencyCode

String

@Must match the regular expression \d+, @Must not be null

Numeric currency code of transaction currency. These codes are specified by ISO-4217

currencyExponent

String

@Must match the regular expression \d+, @Must not be null

Number places of the amount precision for transaction currency

termUrl

String

@Must not be null

The url to which the parameters Pares and md will be sent. They will be need in Finalize method

md

String

@Must not be blank

Merchant Data unique uuid needed to complete transaction

3.1.2. Response

Response status
Status Description

200 OK

Returned when form for user to log in was successfully generate.

200 OK - Error validation

Returned list of field name which has validation error.

500 INTERNAL_SERVER_ERROR

STATUS: E90008 - Returned when is error mpi - 3ds initialize failed.

503 SERVICE UNAVAILABLE

STATUS: E90002 - Returned when is error mpi connection.

200 OK
{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "9f274f9f-bea5-42e9-84e6-222b40eb668f",
  "pareq" : "eJxlkltvwjAMhf8K4p3m0qRUlYnE4GHVxMQuT3uLWguK2lDSFsG/n8NlbFqkSD6Oe+p8DnxuPeLyA4vBo4EVdp3d4KgqZ2M5lWpsYD1/x4OBI/qu2jsjIh5JYHdJX/hia11vwBaHp/zVaCVEooDdJDTo86XhtCa0BbBrApxt0HToStUgsIuCYj+43p9NIhJgdwGDr82279suY2xnj3ZS4hFrEQ2trcqorbNUqZgVdYWuBxaqgT3aWg8h6sj9VJUmX8w3//Yyj1e7txmwUAGl7dFILlIeSz4SOlM60ymwSx5sE9oyi6+XUax5xDnd9JqCNvxpfhV0Fo5+p4AQe3TFmcxjut5dAZ7avaPeDXH9iYE9Gl88B7pFT9jiADIsRSxpQKlKtNRqmsiUkN2KgmNF5CTn+mIZBLBgw27jJECXSVP05wV8A1/aqWQ=",
  "acsUrl" : "java-devel.fenige.pl:8181/fenige-mpi",
  "md" : "ZDVjYjEyZDQtMzc2Ny00NDM5LWIxOTYtNDYxMjZlOGFmNjRj",
  "formBase64" : "PGh0bWw+PFNDUklQVCBMQU5HVUFHRT0iSmF2YXNjcmlwdCI+ZnVuY3Rpb24gT25Mb2FkRXZlbnQoKXsgZG9jdW1lbnQuZG93bmxvYWRGb3JtLnN1Ym1pdCgpOyB9PC9TQ1JJUFQ+PGJvZHkgT25Mb2FkPSJPbkxvYWRFdmVudCgpOyI+PGZvcm0gbmFtZT0iZG93bmxvYWRGb3JtIiBhY3Rpb249Imh0dHBzOi8vamF2YS1kZXZlbC5mZW5pZ2UucGw6ODE4MS9mZW5pZ2UtbXBpIiBtZXRob2Q9IlBPU1QiPjxJTlBVVCB0eXBlPSJoaWRkZW4iIG5hbWU9IlBhUmVxIiB2YWx1ZT0iZUp4bGtsdHZ3akFNaGY4SzRwM20wcVJVbFluRTRHSFZ4TVF1VDN1TFdndUsybERTRnNHL244TmxiRnFrU0Q2T2UrcDhEbnh1UGVMeUE0dkJvNEVWZHAzZDRLZ3FaMk01bFdwc1lEMS94NE9CSS9xdTJqc2pJaDVKWUhkSlgvaGlhMTF2d0JhSHAvelZhQ1ZFb29EZEpEVG84NlhodENhMEJiQnJBcHh0MEhUb1N0VWdzSXVDWWorNDNwOU5JaEpnZHdHRHI4MjI3OXN1WTJ4bmozWlM0aEZyRVEydHJjcW9yYk5VcVpnVmRZV3VCeGFxZ1QzYVdnOGg2c2o5VkpVbVg4dzMvL1l5ajFlN3R4bXdVQUdsN2RGSUxsSWVTejRTT2xNNjB5bXdTeDVzRTlveWk2K1hVYXg1eERuZDlKcUNOdnhwZmhWMEZvNStwNEFRZTNURm1jeGp1dDVkQVo3YXZhUGVEWEg5aVlFOUdsODhCN3BGVDlqaUFESXNSU3hwUUtsS3ROUnFtc2lVa04yS2dtTkY1Q1RuK21JWkJMQmd3MjdqSkVDWFNWUDA1d1Y4QTEvYXFXUT0iPjxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9IlRlcm1VcmwiIHZhbHVlPSJodHRwczovL3VybCI+PGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iTUQiIHZhbHVlPSJiV1E9Ij42Zvcm0+PC9ib2R5PjwvaHRtbD4=",
  "eci" : "02",
  "enrolledStatus" : "Y"
}
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

requestUuid

String

Request’s unique uuid in system

pareq

String

The url to which the mpi parameters will be sent

acsUrl

String

The url to which the mpi parameters will be sent

md

String

Merchant data unique udid in base64 format

eci

String

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. More info.

formBase64

String

Html form of the document in base64 format

enrolledStatus

String

Authentication status indicator

200 OK - Error validation
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ERROR_VALIDATION",
    "error": {
        "message": "Some information is missing or incorrect.",
        "errors": [
            {
                "field": "cardExpMonth",
                "message": [
                    "must not be null"
                ]
            },
            {
                "field": "transactionDescription",
                "message": [
                    "may not be empty"
                ]
            },
            {
                "field": "currencyExponent",
                "message": [
                    "must not be null"
                ]
            },
            {
                "field": "transactionAmount",
                "message": [
                    "must not be null"
                ]
            },
            {
                "field": "cardExpYear",
                "message": [
                    "must not be null"
                ]
            },
            {
                "field": "cardNumber",
                "message": [
                    "must not be null"
                ]
            },
            {
                "field": "transactionDisplayAmount",
                "message": [
                    "must not be null"
                ]
            },
            {
                "field": "md",
                "message": [
                    "must not be empty"
                ]
            },
            {
                "field": "currencyCode",
                "message": [
                    "must not be null"
                ]
            },
            {
                "field": "merchantName",
                "message": [
                    "must not be null"
                ]
            },
            {
                "field": "termUrl",
                "message": [
                    "must not be null"
                ]
            }

        ]
    }
}
500 INTERNAL_SERVER_ERROR
HTTP Response - STATUS: E90008
HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "status": "E90008",
    "message": "Error mpi - 3ds initialize failed",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "dcf1ba46-67a8-4570-847f-4ec4fa90a6c5"
}
503 SERVICE UNAVAILABLE
HTTP Response - STATUS: E90002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
    "status": "E90002",
    "message": "Error mpi connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "dcf1ba46-67a8-4570-847f-4ec4fa90a6c5"
}

3.2. Finalize

POST /processor/3ds/finalize Content Type: application/json, Authorization: Basic Auth
The success of the verification depends on the correctness of the uploaded parameters pares and md received in initialize step.
Success 3-D Secure Authentication. MPI return status:
Y (Full Authentication) - The customer was successfully authenticated.

Attempt 3-D Secure Authentication. MPI return status:
A (Successful Attempted Authentication) - Authentication was not available, but functionality was available to generate a proof of authentication attempt.

Error 3-D Secure Authentication results. MPI return one of statuses:
N (Authentication Failed) - The customer failed authentication, and the transaction is denied. The cardholder’s password (or other authentication information) failed validation, thus, the issuer is not able to authenticate the cardholder.
U (Unable to Complete Authentication) - Authentication could not be performed due to technical or other problems.

3.2.1. Request

POST /processor/3ds/finalize HTTP/1.1
Authorization: Basic bmFtZTpwYXNzd29yZA==
Content-Type: application/json
Content-Length: 193
Host: processor-staging.fenige.pl

{
  "requestUuid" : "74f3f32f-49e3-4f90-8b02-f2b232a5d732",
  "pares" : "VGhpcyBpcyBhIHRlc3QgUGFSZXMgdGhhdCByZXR1cm5zIHN1Y2Nlc3M=",
  "md" : "ZDVjYjEyZDQtMzc2Ny00NDM5LWIxOTYtNDYxMjZlOGFmNjRj"
}
Table 14. FINALIZE 3DS REQUEST FIELDS
Path Type Constraints Description

requestUuid

String

@Must not be null

Request’s unique uuid in system

pares

String

@Must not be null

Payer Authentication Response

md

String

@Must not be null

Merchant Data unique uuid in base64 format from Initialize response body needed to complete transaction

3.2.2. Response

Response status
Status Description

200 OK

Returned when customer was successfully authenticated.

200 OK - Error validation

Returned list of field name which has validation error.

500 INTERNAL_SERVER_ERROR

STATUS: E90008 - Returned when is error mpi - 3ds finalize failed.

503 SERVICE UNAVAILABLE

STATUS: E90002 - Returned when is error mpi connection.

200 OK - status Y
{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "74f3f32f-49e3-4f90-8b02-f2b232a5d732",
  "authenticationStatus" : "Y",
  "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
  "eci" : "02",
  "authenticationTime" : "20180703 16:55:28",
  "cavvAlgorithm" : "3"
}
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

requestUuid

String

Request’s unique uuid in system

authenticationStatus

String

Authentication status indicator

cavv

String

Cardholder Authentication Verification Value

eci

String

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. More info.

authenticationTime

String

Date and time of authentication

cavvAlgorithm

String

Indicates the algorithm used to generate the AuthenticationCAVV value

0 - HMAC

1 - CVV

2 - CVV with ATN

3 - MasterCard SPA algorithm

200 OK - status A
{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "74f3f32f-49e3-4f90-8b02-f2b232a5d732",
  "authenticationStatus" : "A",
  "cavv" : "hMKElVc7gh0wCAEAAA/4BgMAAAA=",
  "eci" : "02",
  "authenticationTime" : "20180703 15:46:00",
  "cavvAlgorithm" : "3"
}
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

requestUuid

String

Request’s unique uuid in system

authenticationStatus

String

Authentication status indicator

cavv

String

Cardholder Authentication Verification Value

eci

String

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. More info.

authenticationTime

String

Date and time of authentication

cavvAlgorithm

String

Indicates the algorithm used to generate the AuthenticationCAVV value

0 - HMAC

1 - CVV

2 - CVV with ATN

3 - MasterCard SPA algorithm

200 OK - Error validation
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ERROR_VALIDATION",
    "error": {
        "message": "Some information is missing or incorrect.",
        "errors": [
            {
                "field": "md",
                "message": [
                    "may not be null"
                ]
            },
            {
                "field": "pares",
                "message": [
                    "may not be null"
                ]
            }
        ]
    }
}
500 INTERNAL_SERVER_ERROR
HTTP Response - STATUS: E90008
HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "status": "E90008",
    "message": "Error mpi - 3ds finalize failed",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "dcf1ba46-67a8-4570-847f-4ec4fa90a6c5"
}
503 SERVICE UNAVAILABLE
HTTP Response - STATUS: E90002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
    "status": "E90002",
    "message": "Error mpi connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "dcf1ba46-67a8-4570-847f-4ec4fa90a6c5"
}

4. 3DS 2.X verification methods

3ds 2.X and 3ds 1.0 flow
3ds 2.X flow
Table 15. 3DS Status and liability shift
3DS status ECI(Mastercard) ECI(Visa) Liability Recommended Action

Y

02

05

Card Issuer

Proceed to Card Authorization

A

01

06

Card Issuer

Proceed to Card Authorization

N

00

07

Merchant

No liability shift, do not proceed with the transaction

U

00

07

Merchant

No liability shift, consider whether to proceed with the transaction

R

00

07

Merchant

No liability shift, do not proceed with the transaction

4.1. Pre Authentication

POST /processor/3ds/preAuthentication Content Type: application/json, Authorization: Basic Auth
Method to initiate 3ds authentication.
If the card is in 3ds 2.X, you can proceed to the first stage of authentication. If 'threeDSMethodURL' is returned, make a hidden iframe and post form with field name
'threeDSMethodData' on address from 'threeDSMethodURL'. Insert 'threeDSMethodData' from response to form. You should receive a response on your endpoint 'methodNotificationUrl' with 'threeDSMethodData' too. Measure the response time, the time and response are required at the 'Authentication' method, based on the response time, set the field 'methodCompletionIndicator'.

'threeDSMethodData ' is Base64 encoded string json with fields 'threeDSMethodNotificationURL' and 'threeDSServerTransID'.

If the card is not in 3DS 2.X use version 1.0.

4.1.1. Request

POST /processor/3ds/preAuthentication HTTP/1.1
Authorization: Basic bmFtZTpwYXNzd29yZA==
Content-Type: application/json
Content-Length: 162
Host: processor-staging.fenige.pl

{
  "requestUuid" : "3b092011-ddcb-40fd-ba8b-2ed572f274d7",
  "cardNumber" : "5430149160516930",
  "methodNotificationUrl" : "methodNotificationUrl.exemple.com"
}
Table 16. PRE AUTHENTICATION 3DS REQUEST FIELDS
Path Type Constraints Description

requestUuid

String

@Must not be null

Request’s unique uuid in system

cardNumber

String

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

Card number

methodNotificationUrl

String

@Must not be null

The URL to which the method notification will be posted. This property specifies the URL to which the ACS will post when the method execution has completed.

4.1.2. Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 653

{
  "result" : {
    "requestUuid" : "f767617d-d331-4151-8fce-92c090a073e1",
    "cardAuthenticationId" : "cf354908-6ed5-4c66-b513-1ec7994e2142",
    "threeDSMethodData" : "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93ZWJob29rLnNpdGUvZDMyZTlkZTgtMGFiOC00ODZjLWJjNzEtMGU2Mzg2MmY4MDNhM2I1YTkzZTUtMjI1Ni00NGQ0LTg2YjItNWFkM2FhMDEyYTJhIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxNjNiZWMzOC1kOTM1LTQ0MGItYWYwYy01OWM3NDI3OTk2MGMifQ",
    "threeDSMethodURL" : "https:/acs.com",
    "protocolVersionStart" : "2.1.0",
    "protocolVersionEnd" : "2.2.0",
    "status" : "S00000",
    "message" : "SUCCESS",
    "httpStatus" : "OK"
  },
  "setOrExpired" : true
}
Path Type Description

requestUuid

String

Request’s unique uuid in system

cardAuthenticationId

String

Unique identifier for 3ds verification

threeDSMethodData

String

Encoded data used for request to ACS

threeDSMethodURL

String

ACS endpoint for hidden request. If endpoint is not present then request is not required.

protocolVersionStart

String

Protocol version start range

protocolVersionEnd

String

Protocol version end range

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

200 OK without threeDSMethodURL
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 610

{
  "result" : {
    "requestUuid" : "3c9c5987-2e1d-43e9-bbbb-b4686398ea75",
    "cardAuthenticationId" : "2183fcd4-f98b-46f4-883b-29e6434114f3",
    "threeDSMethodData" : "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93ZWJob29rLnNpdGUvZDMyZTlkZTgtMGFiOC00ODZjLWJjNzEtMGU2Mzg2MmY4MDNhM2I1YTkzZTUtMjI1Ni00NGQ0LTg2YjItNWFkM2FhMDEyYTJhIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxNjNiZWMzOC1kOTM1LTQ0MGItYWYwYy01OWM3NDI3OTk2MGMifQ",
    "protocolVersionStart" : "2.1.0",
    "protocolVersionEnd" : "2.2.0",
    "status" : "S00000",
    "message" : "SUCCESS",
    "httpStatus" : "OK"
  },
  "setOrExpired" : true
}
Path Type Description

requestUuid

String

Request’s unique uuid in system

cardAuthenticationId

String

Unique identifier for 3ds verification

threeDSMethodData

String

Encoded data used for request to ACS

protocolVersionStart

String

Protocol version start range

protocolVersionEnd

String

Protocol version end range

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

422 UNPROCESSABLE_ENTITY Card number not Enrolled in 3DS v2
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: 230

{
  "requestUuid" : "758a5929-6f31-4c76-ab38-f342f598ce62",
  "status" : "E03003",
  "message" : "Card number not Enrolled in 3DS v2",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "3bbd0546-80e4-42f5-8ecb-126e8309915e"
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: 224

{
  "requestUuid" : "b0706752-93fe-42b3-be88-d63e93c256f5",
  "status" : "E03005",
  "message" : "Issuer card is not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "f90f6e2d-d428-4086-9819-a45614c9f3e4"
}
Path Type Description

requestUuid

String

Request’s unique uuid in system

traceId

String

Unique id for this http request register in system

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

4.2. Authentication

POST /processor/3ds/authentication Content Type: application/json, Authorization: Basic Auth
Method initialize authentication process by sending required transaction data. Method can return final data like cavv, transactionXId, eci or challenge flow (shown in the diagram).
After challenge end your app get notification on 'notificationUrl'. This is a POST request with "cres" and "threeDSSessionData".

"threeDSSessionData" is a encoded in base64 "cardAuthenticationId". You must use it in 'Authentication Details' method to get authentication value cavv, transactionXId and eci.

'cres' is Base64 encoded string json with fields: 'threeDSServerTransID', 'acsTransID', 'challengeCompletionInd', 'messageVersion', 'transStatus'.
'threeDSServerTransID' - is same like in 'threeDSMethodData'.
'transStatus' - is same like 'transactionStatus' in response from 'Authentication' method.
In the test environment, you have the option of calling different transactionStatus, depending on the purchaseAmount field. Eg.
     (1, 1000) - Y,
     (1001, 2000) - A,
     (2001, 3000) - C,
     (3001, 4000) - N,
     (4001, 5000) - U,
     (5001, 6000) - I.

4.2.1. Request

POST /processor/3ds/authentication HTTP/1.1
Authorization: Basic bmFtZTpwYXNzd29yZA==
Content-Type: application/json
Content-Length: 1522
Host: processor-staging.fenige.pl

{
  "requestUuid" : "e1b267ca-74d8-4823-8339-de3f0e904c4e",
  "cardAuthenticationId" : "439eb1e8-02e9-4bc3-9d4c-b65f2cde6a80",
  "threeDSMethodData" : "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiSFRUUDQwYjgyNDQ3LTE0ODUtNDUwZi04ZGYxLTdhNGQwYmRiMWMzYiIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiNDE1MDQzY2UtYTNhMC00ODBjLTk0YTYtNzk2NGEzYTcxNWI2In0",
  "methodCompletionIndicator" : "Y",
  "cardNumber" : "5430149160516930",
  "cardExpirationDate" : "12/22",
  "cardholderName" : "John",
  "purchaseAmount" : "123",
  "purchaseCurrency" : "PLN",
  "browserAcceptHeader" : "Accept: application/json",
  "browserLanguage" : "PL",
  "browserScreenHeight" : "1500",
  "browserScreenWidth" : "1500",
  "browserTimeZone" : "60",
  "browserUserAgent" : "Mozilla/5.0",
  "browserScreenColorDepth" : "24",
  "merchantId" : "MerchantId",
  "merchantCountryCode" : "616",
  "merchantName" : "Merchant Name",
  "merchantUrl" : "https:////merchant-site.com",
  "merchantCategoryCode" : "7777",
  "notificationUrl" : "notfication.examlpe.com",
  "cardholderEmail" : null,
  "cardholderHomePhone" : null,
  "cardholderMobilePhone" : null,
  "cardholderWorkPhone" : null,
  "browserIPAddress" : "77.55.135.220",
  "browserJavaEnabledVal" : "ENABLED",
  "browserJavaScriptEnabled" : "ENABLED",
  "recurringExpDate" : null,
  "recurringFrequency" : null,
  "recurringInitialTransactionXId" : null,
  "instalmentPaymentData" : null,
  "authenticationType" : "PAYMENT",
  "requestorChallengeInd" : "NO_CHALLENGE_REQUESTED",
  "protocolVersion" : "2.2.0"
}
Table 17. AUTHENTICATION 3DS REQUEST FIELDS
Path Type Constraints Description

requestUuid

String

@Must not be null

Request’s unique uuid in system

cardAuthenticationId

String

@Must not be empty

Unique identifier for 3ds verification from preAuthentication request

cardNumber

String

@Must be a number and length must be between 12 and 19, @Luhn

Card number

cardExpirationDate

String

@Length must be 5, @Must not be null

Expiration date of card mm/yy

cardholderName

String

@Optional. @Length between 2 and 45 inclusive

This property contains the name of the cardholder. Name of the Cardholder. Must be ASCII characters. This is required to be set unless market or regional mandates restricts sending this information.

purchaseAmount

String

@Must match the regular expression \d{1,48}, @Must not be null

This field contains the purchase amount to be authorized. The transaction amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated PurchaseExponent. This field may not contain a negative number.

purchaseCurrency

String

@Must not be null

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

merchantId

String

@Must not be empty

This field contains a merchantId registered in DirectoryServer. This is not the same value as the transaction!

merchantName

String

@Must not be empty

This field contains a value merchant name which is visible on the 3ds confirmation form from the bank

merchantUrl

String

@Must not be empty

This field contains a value merchant URL - merchant or terminal website

merchantCountryCode

String

@Must match the regular expression \d+, @Must not be empty

This field contains a value Merchant country code location. These codes are specified by ISO-3166

merchantCategoryCode

String

@Must not be empty

This field contains a value merchant category code

notificationUrl

String

@Length must be between 0 and 256 inclusive

This property specifies the URL to which the final challenge response is POSTed

threeDSMethodData

String

@Must not be empty

Response data from a hidden form from the Pre Authentication. If threeDSMethodURL is empty set encodedData

methodCompletionIndicator

String

@Must not be null

Y if response from hidden form from Pre Authentication is under 10s, N if response from hidden form from Pre Authentication is over 10s, U if threeDSMethodURL is empty

protocolVersion

String

@Must not be null

This field indicates the protocol version. Now there are two versions: 2.1.0 and 2.2.0. It is recommended to use 2.2.0 if the card supports it. You will get it from the Pre Authentication method. Some configurations are only available for 2.2.0.

requestorChallengeInd

String

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

Indicates whether a challenge is requested for this transaction. For authenticationType PAYMENT possible values are: NO_PREFERENCE, NO_CHALLENGE_REQUESTED, CHALLENGE_REQUESTED_MANDATE, CHALLENGE_REQUESTED_3DS_REQUESTOR_PREFERENCE

For authenticationType ADD_CARD, VERIFY_CARDHOLDER, INSTALLMENT_PAYMENT, COF_INITIAL, RECURRING_INITIAL possible values are: CHALLENGE_REQUESTED_MANDATE, CHALLENGE_REQUESTED_3DS_REQUESTOR_PREFERENCE

authenticationType

String

@Must not be null

Authentication Type configuration prepared for specific type. Possible values are:

Non payment authentication - Identity verification and account confirmation:

ADD_CARD

VERIFY_CARDHOLDER

Payment authentication - Cardholder authentication during an e-commerce transaction:

PAYMENT

COF_INITIAL

INSTALLMENT_PAYMENT

RECURRING_INITIAL

3DS Requestor Initiated (only for protocolVersion 2.2.0) - Confirmation of account information and Cardholder authentication with no direct Cardholder present. For example, a subscription-based e-commerce merchant confirming that an account is still valid:

MOTO

RECURRING_SUBSEQUENT

browserAcceptHeader

String

Max length: 2048.

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

This field contains the exact content of the HTTP accept header as sent to the merchant from the cardholder’s user agent. This field is required only if the cardholder’s user agent supplied a value. e.g Accept: application/json

browserLanguage

String

Min length: 1, Max length: 8

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

This field contains the cardholder’s browser language as defined in IETF BCP 47.

browserScreenHeight

String

Min length: 1, Max length: 6

Regexp: ^[0-9]{1,6}$

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

This field contains the total height of the cardholder’s screen in pixels.

browserScreenWidth

String

Min length: 1, Max length: 6

Regexp: ^[0-9]{1,6}$

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

This field contains the total width of the cardholder’s screen in pixels.

browserTimeZone

String

Min length: 1, Max length: 5

Regexp: ^[+-]?[0-9]{1,4}$

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

This field contains the difference between UTC time and the cardholder’s browser local time in minutes.

browserUserAgent

String

Max length: 2048

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

This field contains the exact content of the HTTP User-Agent header.

browserJavaEnabledVal

String

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

This field contains a value representing the ability of the cardholder’s browser to execute Java. Enumerated values: NOT_PRESENT, ENABLED, DISABLED.

Required if browserJavascriptEnabled is true

cardholderEmail

String

This field contains the cardholder email address.

cardholderHomePhone

String

Optional. Must match regex \d{1,3}-[1-9]\d{1,14}$

This field contains the home phone number provided by the cardholder. Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

cardholderMobilePhone

String

Optional. Must match regex \d{1,3}-[1-9]\d{1,14}$

This field contains the mobile phone number provided by the cardholder. Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

cardholderWorkPhone

String

Optional. Must match regex \d{1,3}-[1-9]\d{1,14}$

This field contains the work phone number provided by the cardholder. Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

browserIPAddress

String

@Must not be null, Max length: 45

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

This field contains the IP address of the cardholder’s browser as returned by the HTTP headers.

browserJavaScriptEnabled

String

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

This field contains a value representing the ability of the cardholder’s browser to execute JavaScript. Enumerated values: ENABLED, DISABLED.

browserScreenColorDepth

String

Required for authenticationType:

ADD_CARD,

VERIFY_CARDHOLDER,

PAYMENT,

INSTALLMENT_PAYMENT,

COF_INITIAL,

RECURRING_INITIAL

This field contains a value representing the bit depth of the color palette, in bits per pixel, for displaying images. Obtained from Cardholder browser using the screen.colorDepth property. Values accepted:

1 = 1 bit,

4 = 4 bits,

8 = 8 bits,

15 = 15 bits,

16 = 16 bits,

24 = 24 bits,

32 = 32 bits,

48 = 48 bits

recurringExpDate

String

@Must not be null only for authenticationType = RECURRING_INITIAL

This field contains the date after which no further authorizations shall be performed. The format of this field must be: YYYYMMDD

recurringFrequency

String

@Must not be null only for authenticationType = RECURRING_INITIAL

The number of days between recurring payments. This field indicates the minimum number of days between authorizations.

recurringInitialTransactionXId

String

@Must not be null only for authenticationType = RECURRING_SUBSEQUENT

This field indicates the transactionXid from recurring initial authentication.

instalmentPaymentData

String

@Must not be null only for authenticationType = INSTALLMENT_PAYMENT

Max authorizations permitted for installment payments Indicates maximum number of authorizations permitted for installment payments. Required in AReq messages if the Merchant and Cardholder have agree to installment payments ( authenticationType = INSTALLMENT_PAYMENT). Value must be greater than 1.

4.2.2. Response

200 OK without challenge
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 340

{
  "result" : {
    "requestUuid" : "d04ee81d-5321-411c-845d-e0ba4c5db7fe",
    "transactionStatus" : "Y",
    "transactionXId" : "4a41f157-18c6-4fdc-abdb-ea20d480b4a3",
    "cavv" : "B5gQCElHgQAAAAAKmFNEdQAAAAA=",
    "eci" : "06",
    "status" : "S00000",
    "message" : "SUCCESS",
    "httpStatus" : "OK"
  },
  "setOrExpired" : true
}
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionStatus

String

Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:

Y Authentication/account verification successful. N Not authenticated/account not verified; transaction denied. U Authentication/account verification could not be performed; technical or other problem as indicated in ARes or RReq. A Attempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided. C Challenge required; additional authentication is required using the CReq/CRes. R Authentication/account verification rejected; issuer is rejecting authentication/verification and request that authorization not be attempted. D Challenge required; decoupled authentication confirmed. I Informational only; 3DS Requestor challenge preference acknowledged. Note: The CRes message can contain only a value of Y or N. Values of D and I are only applicable for 3DS version 2.2.0.

transactionXId

String

Server transaction Id generated by DS

cavv

String

This property is determined by the Access Control Server (ACS), and is filled after the call to SendAuthRequest (for a frictionless flow), or when the Results Request Message (RReq) is parsed using CheckResponse (for a challenge flow).

This property will be valid if the TransactionStatus is "Y" or "A". The value may be used to provide proof of authentication.

eci

String

This property is determined by the Access Control Server (ACS), and is filled after the call to SendAuthRequest (for a frictionless flow), or when the Results Request Message (RReq) is parsed using CheckResponse (for a challenge flow).

This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the TransactionStatus is "Y" or "A".

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

200 OK with challenge
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 839

{
  "result" : {
    "requestUuid" : "d18be260-522f-41ec-9399-2242184dd3c2",
    "transactionStatus" : "C",
    "acsurl" : "acsurl.com",
    "creq" : "c29tZSBjcmVx",
    "challengeHtmlFormBase64" : "PGh0bWw+PFNDUklQVCBMQU5HVUFHRT0iSmF2YXNjcmlwdCI+ZnVuY3Rpb24gT25Mb2FkRXZlbnQoKXsgZG9jdW1lbnQuZG93bmxvYWRGb3JtLnN1Ym1pdCgpOyB9PC9TQ1JJUFQ+PGJvZHkgT25Mb2FkPSJPbkxvYWRFdmVudCgpOyI+PGZvcm0gbmFtZT0iZG93bmxvYWRGb3JtIiBhY3Rpb249Imh0dHBzOi8vYWNzdGVzdC5jb20iIG1ldGhvZD0iUE9TVCI+PElOUFVUIHR5cGU9ImhpZGRlbiIgbmFtZT0iY3JlcSIgdmFsdWU9ImNyZXEiPjxJTlBVVCB0eXBlPSJoaWRkZW4iIG5hbWU9InRocmVlRFNTZXNzaW9uRGF0YSIgdmFsdWU9InNvbWVFbmNvZGVkRGF0ZSI+PC9mb3JtPjwvYm9keT48L2h0bWw+",
    "threeDSSessionData" : "ZGY0NDJhODQtOGJkZS00MmQ3LWExMTUtMzUyNjNlZGY1MGFk",
    "status" : "S00000",
    "message" : "SUCCESS",
    "httpStatus" : "OK"
  },
  "setOrExpired" : true
}
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionStatus

String

Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:

Y Authentication/account verification successful. N Not authenticated/account not verified; transaction denied. U Authentication/account verification could not be performed; technical or other problem as indicated in ARes or RReq. A Attempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided. C Challenge required; additional authentication is required using the CReq/CRes. R Authentication/account verification rejected; issuer is rejecting authentication/verification and request that authorization not be attempted. D Challenge required; decoupled authentication confirmed. I Informational only; 3DS Requestor challenge preference acknowledged. Note: The CRes message can contain only a value of Y or N. Values of D and I are only applicable for 3DS version 2.2.0.

acsurl

String

ACS Url - if challenge is required, data for building a form such as challengeHtmlFormBase64

creq

String

creq - if challenge is required, data for building a form such as challengeHtmlFormBase64

challengeHtmlFormBase64

String

This field is a BASE64 encrypted html source file containing the challenge 3-D Secure frame

threeDSSessionData

String

This field is a BASE64 encrypted cardAuthenticationId you can add this to challenge form to correlate notification

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

422 UNPROCESSABLE_ENTITY
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 227

{
  "requestUuid" : "06130bf4-d1b8-4584-bed2-f7e54201c883",
  "status" : "E03000",
  "message" : "Error mpi V2 - failed internal",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "09765439-a05a-49dc-9b2d-a56a418ea96d"
}
Path Type Description

requestUuid

String

Request’s unique uuid in system

status

String

Response code from Fenige system

traceId

String

Unique id for this http request register in system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

500 INTERNAL_SERVER_ERROR
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 227

{
  "requestUuid" : "06130bf4-d1b8-4584-bed2-f7e54201c883",
  "status" : "E03000",
  "message" : "Error mpi V2 - failed internal",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "09765439-a05a-49dc-9b2d-a56a418ea96d"
}
Path Type Description

requestUuid

String

Request’s unique uuid in system

status

String

Response code from Fenige system

traceId

String

Unique id for this http request register in system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

4.3. Authentication Details

GET /processor/3ds/details/{uuid} Content Type: application/json, Authorization: Basic Auth
Method return details for authentication.
Success 3-D Secure Authentication. MPI return status:
Y (Full Authentication) - The customer was successfully authenticated.

Attempt 3-D Secure Authentication. MPI return status:
A (Successful Attempted Authentication) - Authentication was not available, but functionality was available to generate a proof of authentication attempt.

Challenge required
C Cardholder challenge required.
D Challenge required; decoupled authentication confirmed.

Information only
I Informational only; 3DS Requestor challenge preference acknowledged.

Error 3-D Secure Authentication results. MPI return one of statuses:
N (Authentication Failed) - The customer failed authentication, and the transaction is denied. The cardholder’s password (or other authentication information) failed validation, thus, the issuer is not able to authenticate the cardholder.
U (Unable to Complete Authentication) - Authentication could not be performed due to technical or other problems.
R Not authenticated because the issuer is rejecting authentication.

4.3.1. Request

GET /processor/3ds/details/ad7a8fc0-db66-412e-8f48-535671e4e5df HTTP/1.1
Authorization: Basic bmFtZTpwYXNzd29yZA==
Host: processor-staging.fenige.pl
Table 18. /processor/3ds/details/{cardAuthenticationId}
Parameter Description

cardAuthenticationId

Unique identifier for 3ds verification

4.3.2. Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 477

{
  "result" : {
    "cardAuthenticationId" : "d0986a07-9fa8-4651-8b85-1d37ee4bfb0e",
    "provider" : "MASTERCARD",
    "transactionStatus" : "Y",
    "cardAuthenticationStatus" : "AUTHENTICATION_FINISHED",
    "transactionXId" : "da2e6956-da19-4826-9dae-f1b74b56ad98",
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag",
    "eci" : "01",
    "transactionStatusReason" : "04",
    "status" : "S00000",
    "message" : "SUCCESS",
    "httpStatus" : "OK"
  },
  "setOrExpired" : true
}
Path Type Description

cardAuthenticationId

String

Unique identifier for 3ds verification

provider

String

Provider

transactionStatusReason

String

Provides information on why the Transaction Status field has the specified value. For MessageCategory 01 (PA), always included when TransactionStatus = N, U, or R. For MessageCategory 02 (NPA), as defined by the DS.

Possible values are:

01 - Card authentication failed, 02 - Unknown device, 03 - Unsupported device, 04 - Exceeds authentication frequency limit, 05 - Expired card, 06 - Invalid card number, 07 - Invalid transaction, 08 - No Card record, 09 - Security failure, 10 - Stolen card, 11 - Suspected fraud, 12 - Transaction not permitted to cardholder, 13 - Cardholder not enrolled in service, 14 - Transaction timed out at the ACS, 15 - Low confidence, 16 - Medium confidence, 17 - High confidence, 18 - Very high confidence, 19 - Exceeds ACS maximum challenges, 20 - Non-Payment transaction non supported, 21 - 3RI transaction not supported, 22 - ACS technical issue, 23 - Decoupled Authentication required by ACS but not requested by 3DS Requestor, 24 - 3DS Requestor Decoupled Max Expiry Time exceeded, 25 - Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt, 26 - Authentication attempted but not performed by the cardholder, 27-79 - Reserved for future EMVCo use (values invalid until defined by EMVCo), 80-99 - Reserved for DS use

cardAuthenticationStatus

String

Card authentication statusPossible values are: INITIALIZED, PREAUTHENTICATION_INITIATED, PREAUTHENTICATION_CONFIRMED, AUTHENTICATION_REJECTED, AUTHENTICATION, AUTHENTICATION_FINISHED

transactionStatus

String

Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:

Y Authentication/account verification successful. N Not authenticated/account not verified; transaction denied. U Authentication/account verification could not be performed; technical or other problem as indicated in ARes or RReq. A Attempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided. C Challenge required; additional authentication is required using the CReq/CRes. R Authentication/account verification rejected; issuer is rejecting authentication/verification and request that authorization not be attempted. D Challenge required; decoupled authentication confirmed. I Informational only; 3DS Requestor challenge preference acknowledged. Note: The CRes message can contain only a value of Y or N. Values of D and I are only applicable for 3DS version 2.2.0.

transactionXId

String

Server transaction Id generated by DS

cavv

String

This property is determined by the Access Control Server. This property will be valid if the TransactionStatus is "Y" or "A". The value may be used to provide proof of authentication.

eci

String

This property is determined by the Access Control Server. This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the TransactionStatus is "Y" or "A".

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

5. 3DS 2.X registration methods

Methods for registration merchants in 3ds 2.X Mastercard system. Endpoints use dedicated credentials created for these methods.
With the webhooks functionality, your endpoint will be notified when the merchant registration status changes. The HTTP success code means that your request is processing in
Fenige system, you need to wait to get response from webhook to be sure the request was successful.

5.1. Add merchant

POST /3ds/processor/registration Content Type: application/json, Authorization: Basic Auth
Method to initiate 3ds registation process. Expect a list of merchants with a unique name and id to be registered.

5.1.1. Request

POST /3ds/processor/registration HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 528
Host: processor-staging.fenige.pl

{
   "requestUuid":"9f134f9f-bca5-41e9-12e6-212b40e1668f",
   "merchants":[
      {
         "merchantId": "E2000000000001",
         "merchantName": "Merchant Name",
         "identityCheckExpress": "N",
         "whiteListName": "name"
      },
      {
         "merchantId": "E2000000000002",
         "merchantName": "Next Merchant Name",
         "identityCheckExpress": "N",
         "whiteListName": "name"
      }
   ]
}
Path Type Constraints Description

requestUuid

String

@Must not be null

Request’s unique uuid in system

merchantId

String

@Must not be null, @Max length: 35

Unique merchant id in system

merchantName

String

@Must not be null, @Max length: 40

Unique merchant name in system

whiteListName

String

@Optional, @Max length: 50

WhiteList Name will allow Acquirer`s to assign a general name to be displayed for companies that may have multiple merchant names. Users must include a Whitelisting name already stored in ISSM Records

identityCheckExpress

String

@Must be Y or N

Identity check express extends the identity check program with a solution whereby the cardholder is authenticated by the merchant providing a more seamless experience to cardholder without chance of step up. An on-behalf service for issuers, the service leverages the FIDO standard to provide more comprehensive proof of authentication during the transaction and includes insights from the risk-based assessment during authorization as additional context

5.1.2. Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 105

{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "716333e9-ed1d-4e59-89e0-34e423d7aab0"
}
Path Type Description

status

String

Response code from Fenige system.

message

String

Message for response code from Fenige system.

httpStatus

String

Response http status.

requestUuid

String

Request’s unique uuid in system.

400 BAD REQUEST
HTTP/1.1 400 Bad Request
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 12 Mar 2020 14:03:26 GMT
Connection: close
Content-Length: 640

{
  "errors" : {
    "merchantId" : [ "must not be null, max length: 35" ],
    "merchantName" : [ "must not be null, max length: 40" ],
    "identityCheckExpress" : [ "must be Y or N" ],
    "acquirerBin" : [ "must not be null, length: 6" ]
    "requestUuid" : [ "must not be null" ]
  },
  "status" : "E80000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "77caa1c3-df03-4e07-bfa6-b4b2d91b53f0"
}
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/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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T07:17:31.968+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "3ds/processor/registration"
}
Path Type Description

timestamp

String

Time stamp.

status

Number

Response code from Fenige system.

error

String

Response http status.

message

String

Message for response code from Fenige system.

path

String

Path.

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E03100
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "013961a7-4181-42e2-930d-9494f96b54e6",
    "status": "E03100",
    "message": "Registration rejected, merchantId or merchantName already exists",
    "httpStatus": "UNPROCESSABLE_ENTITY"
}
HTTP Response - STATUS: E03101
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "013961a7-4181-42e2-930d-9494f96b54e6",
    "status": "E03101",
    "message": "Request uuid is not unique",
    "httpStatus": "UNPROCESSABLE_ENTITY"
}
Path Type Description

requestUuid

String

Request’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.

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

{
    "status": "E90000",
    "message": "Domain error",
    "httpStatus": "INTERNAL_SERVER_ERROR"
}
Path Type Description

status

String

Response code from Fenige system.

message

String

Message for response code from Fenige system.

httpStatus

String

Response http status.

5.2. Edit merchant

PUT /3ds/processor/registration Content Type: application/json, Authorization: Basic Auth
The method is implemented using delete and add operations in the Mastercard system.

5.2.1. Request

PUT /3ds/processor/registration HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 528
Host: processor-staging.fenige.pl

{
   "requestUuid":"9f134f9f-bca5-41e9-12e6-212b40e1668f",
   "oldMerchant":{
      "merchantId": "E2000000000001",
      "merchantName": "Merchant Name",
      "identityCheckExpress": "N",
      "deleteReason": "DATA_ENTRY_ERROR",
      "whiteListName": "name"
   },
   "newMerchant": {
      "merchantId": "E2000000000002",
      "merchantName": "New Merchant Name",
      "identityCheckExpress": "N",
      "whiteListName": "name"
   }
}
Path Type Constraints Description

requestUuid

String

@Must not be null

Request’s unique uuid in system

oldMerchant.merchantId

String

@Must not be null, @Max length: 35

Old unique merchant id in system

oldMerchant.merchantName

String

@Must not be null, @Max length: 40

Old unique merchant name in system

oldMerchant.deleteReason

String

@Must be one of: DATA_ENTRY_ERROR, MERCHANT_NO_LONGER_PARTICIPATING, ACQUIRER_BIN_CHANGE, ACQUIRER_PRIMARY_ICA_CHANGE or OTHER

Reason for deleting the merchant

newMerchant.merchantId

String

@Must not be null, @Max length: 35

New unique merchant id in system

newMerchant.merchantName

String

@Must not be null, @Max length: 40

New unique merchant name in system

whiteListName

String

@Optional, @Max length: 50

WhiteList Name will allow Acquirer`s to assign a general name to be displayed for companies that may have multiple merchant names. Users must include a Whitelisting name already stored in ISSM Records

identityCheckExpress

String

@Must be Y or N

Identity check express extends the identity check program with a solution whereby the cardholder is authenticated by the merchant providing a more seamless experience to cardholder without chance of step up. An on-behalf service for issuers, the service leverages the FIDO standard to provide more comprehensive proof of authentication during the transaction and includes insights from the risk-based assessment during authorization as additional context

5.2.2. Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 105

{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "716333e9-ed1d-4e59-89e0-34e423d7aab0"
}
Path Type Description

status

String

Response code from Fenige system.

message

String

Message for response code from Fenige system.

httpStatus

String

Response http status.

requestUuid

String

Request’s unique uuid in system.

400 BAD REQUEST
HTTP/1.1 400 Bad Request
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 12 Mar 2020 14:03:26 GMT
Connection: close
Content-Length: 640

{
  "errors" : {
    "oldMerchant.merchantId" : [ "must not be null, max length: 35" ],
    "oldMerchant.merchantName" : [ "must not be null, max length: 40" ],
    "newMerchant.merchantId" : [ "must not be null, max length: 35" ],
    "newMErchant.merchantName" : [ "must not be null, max length: 40" ],
    "newMerchant.identityCheckExpress" : [ "must be Y or N" ],
    "acquirerBin" : [ "must not be null, length: 6" ],
    "requestUuid" : [ "must not be null" ]
  },
  "status" : "E80000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "77caa1c3-df03-4e07-bfa6-b4b2d91b53f0"
}
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/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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T07:17:31.968+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "3ds/processor/registration"
}
Path Type Description

timestamp

String

Time stamp.

status

Number

Response code from Fenige system.

error

String

Response http status.

message

String

Message for response code from Fenige system.

path

String

Path.

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E03100
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "013961a7-4181-42e2-930d-9494f96b54e6",
    "status": "E03100",
    "message": "Registration rejected, merchantId or merchantName already exists",
    "httpStatus": "UNPROCESSABLE_ENTITY"
}
HTTP Response - STATUS: E03101
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "013961a7-4181-42e2-930d-9494f96b54e6",
    "status": "E03101",
    "message": "Request uuid is not unique",
    "httpStatus": "UNPROCESSABLE_ENTITY"
}
Path Type Description

requestUuid

String

Request’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.

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

{
    "status": "E90000",
    "message": "Domain error",
    "httpStatus": "INTERNAL_SERVER_ERROR"
}
Path Type Description

status

String

Response code from Fenige system.

message

String

Message for response code from Fenige system.

httpStatus

String

Response http status.

5.3. Delete merchant

DELETE /3ds/processor/registration Content Type: application/json, Authorization: Basic Auth
Method to remove merchant from the Mastercard system.

5.3.1. Request

DELETE /3ds/processor/registration HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 528
Host: processor-staging.fenige.pl

{
    "requestUuid": "9f134f9f-bca5-41e9-12e6-212b40e1668f",
    "merchant": {
        "merchantId": "E2000000000001",
        "merchantName": "Merchant Name",
        "identityCheckExpress": "N",
        "deleteReason": "DATA_ENTRY_ERROR",
        "whiteListName": "name"
    }
}
Path Type Constraints Description

requestUuid

String

@Must not be null

Request’s unique uuid in system

merchantId

String

@Must not be null, @Max length: 35

Unique merchant id in system

merchantName

String

@Must not be null, @Max length: 40

Unique merchant name in system

whiteListName

String

@Optional, @Max length: 50

WhiteList Name will allow Acquirer`s to assign a general name to be displayed for companies that may have multiple merchant names. Users must include a Whitelisting name already stored in ISSM Records

deleteReason

String

@Must be one of: DATA_ENTRY_ERROR, MERCHANT_NO_LONGER_PARTICIPATING, ACQUIRER_BIN_CHANGE, ACQUIRER_PRIMARY_ICA_CHANGE or OTHER

Reason for deleting the merchant

identityCheckExpress

String

@Must be Y or N

Identity check express extends the identity check program with a solution whereby the cardholder is authenticated by the merchant providing a more seamless experience to cardholder without chance of step up. An on-behalf service for issuers, the service leverages the FIDO standard to provide more comprehensive proof of authentication during the transaction and includes insights from the risk-based assessment during authorization as additional context

5.3.2. Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 105

{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "716333e9-ed1d-4e59-89e0-34e423d7aab0"
}
Path Type Description

status

String

Response code from Fenige system.

message

String

Message for response code from Fenige system.

httpStatus

String

Response http status.

requestUuid

String

Request’s unique uuid in system.

400 BAD REQUEST
HTTP/1.1 400 Bad Request
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 12 Mar 2020 14:03:26 GMT
Connection: close
Content-Length: 640

{
  "errors" : {
    "merchantId" : [ "must not be null, max length: 35" ],
    "merchantName" : [ "must not be null, max length: 40" ],
    "identityCheckExpress" : [ "must be Y or N" ],
    "acquirerBin" : [ "must not be null, length: 6" ],
    "requestUuid" : [ "must not be null" ]
  },
  "status" : "E80000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "77caa1c3-df03-4e07-bfa6-b4b2d91b53f0"
}
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/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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T07:17:31.968+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "3ds/processor/registration"
}
Path Type Description

timestamp

String

Time stamp.

status

Number

Response code from Fenige system.

error

String

Response http status.

message

String

Message for response code from Fenige system.

path

String

Path.

422 UNPROCESSABLE ENTITY
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "013961a7-4181-42e2-930d-9494f96b54e6",
    "status": "E03101",
    "message": "Request uuid is not unique",
    "httpStatus": "UNPROCESSABLE_ENTITY"
}
Path Type Description

requestUuid

String

Request’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.

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

{
    "status": "E90000",
    "message": "Domain error",
    "httpStatus": "INTERNAL_SERVER_ERROR"
}
Path Type Description

status

String

Response code from Fenige system.

message

String

Message for response code from Fenige system.

httpStatus

String

Response http status.

6. Webhooks

General information

To use the webhooks functionality, you must notify Fenige Sales Department by email. Then an URL address and a secret token will be configured, thanks to which communication between the Fenige side and the client side will be more secure. After configuring the above-mentioned properties, you will receive Secret Token and then you can handle webhooks from the Fenige system. The URL must be specified by the client, requests from the Fenige system will be directed to this address. The Secret Token will be set by the Fenige employee and sent to the client.

webhook
Figure 2. In the picture above you can see basic idea of this webhook/event
Your server after receiving Webhook Event must return HTTP status 200 OK. Otherwise, the Fenige server will retry the request. There is 3 attempts for requesting your API. Repeated requests will be executing in 5 seconds intervals excluding timeout from client server.
In order to protect client API by polling or other undesirable actions, the Fenige system uses headers. If you want to use Webhook events, you need to do the header handling on your side.
Thanks to the 'X-MERCHANT-SECRET' header you can compare the hash on your backend side to eliminate attempts of unwanted requests. To build 'X-MERCHANT-SECRET' header: + 1. Concatenate secret token established by you and Fenige’s employee with controlUuid from received request body of callback event + 2. Hash with SHA256 function result of above operation
Example of 'X-MERCHANT-SECRET' building
import hashlib

# secret token established by client with fenige employee
secret = 'mNaU9TaK4m9myYYFBJgKu8slNH2fCKutJyzXwI'
# controlUuid received from webhook's request
controlUuid = 'c168a885-acfa-4a91-a1ad-ed7a042b7238'

# concatenate strings in correct order
concatenated = secret + controlUuid

# use SHA256 hashing function
hashed = hashlib.sha256(concatenated.encode('utf-8')).hexdigest()

# then compare 'hashed' variable with content of 'X-MERCHANT-SECRET' header

6.1. 3DS 2.X registration

Method: HTTP POST + Your endpoint will be notified when the registration status changes. This event allows you to eliminate unnecessary network traffic and polling the API for registration status.

6.1.1. 3DS 2.X registration webhook request body

When registration was correctly approved
Content-Type: application/json
X-MERCHANT-SECRET: 3cbd17f561150a1394cabbe2b6031fd83f3f3081abe28c32b7fed16f32aebc4a
X-MERCHANT-TIMESTAMP: 1614800720

{
  "controlUuid": "e28f7423-ae21-44bb-b27e-a2038cb29181",
  "status": "APPROVED",
  "message": "SUCCESS",
  "requestUuids": [
    "d3b767cd-5fde-4901-beb6-f6260fa657ad",
    "18b900ba-8d4e-11eb-8dcd-0242ac130003"
  ]
}
When registration was rejected
Content-Type: application/json
X-MERCHANT-SECRET: 3cbd17f561150a1394cabbe2b6031fd83f3f3081abe28c32b7fed16f32aebc4a
X-MERCHANT-TIMESTAMP: 1614800720

{
  "controlUuid": "e28f7423-ae21-44bb-b27e-a2038cb29181",
  "status": "DECLINED",
  "message": "Problem with merchant registration in mastercard",
  "requestUuids": [
    "d3b767cd-5fde-4901-beb6-f6260fa657ad",
    "18b900ba-8d4e-11eb-8dcd-0242ac130003"
  ]
}
Table 19. Headers description
Path Type Rule Description

X-MERCHANT-SECRET

String

Always present

SHA256 Hash string composed from secret token and requestUuid placed in request body of this webhook

X-MERCHANT-TIMESTAMP

Numeric string

Always present

Timestamp of server response in UNIX format for instance: 1614023731

Table 20. Request fields description
Path Type Rule Description

controlUuid

UUID

Always present

Unique identifier of request body, assigned by Fenige server for security purposes

requestUuids

List<UUID>

Always present

Unique identifier of registration requests

status

String

Always present

Status of registration in Fenige system

message

String

Optional

Additional message

7. Payment API

7.1. Currency for card

POST /processor/currency-for-card Content Type: application/json, Authorization: Basic Auth
Method is used to determine currencies applied for particular card.

7.1.1. Request

POST /processor/currency-for-card HTTP/1.1
Authorization: Basic bmFtZTpwYXNzd29yZA==
Content-Type: application/json
Content-Length: 97
Host: processor-staging.fenige.pl

{
  "requestUuid" : "7d4e8a3f-72d7-4657-83f0-36588abaca2a",
  "cardNumber" : "5575168861324712"
}
Table 21. CURRENCY FOR CARD REQUEST FIELDS
Path Type Constraints Description

requestUuid

String

@Must not be null

Request’s unique uuid in system

cardNumber

String

@Must be a number and length must be between 12 and 19, @Luhn

Transaction card number used in verification process

7.1.2. Response

200 OK Mastercard
{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "7d4e8a3f-72d7-4657-83f0-36588abaca2a",
  "defaultCurrency" : "PLN",
  "currencyCodes" : [ "PLN", "EUR" ],
  "cardholderCurrencyIndicator" : "D",
  "provider" : "MASTERCARD",
  "cardType" : "DMC",
  "bankName" : "BANK MILLENNIUM S.A.",
  "countryCardIssuing" : "POL",
  "countryCodeNumeric" : "616",
  "region" : "EUROPE",
  "gcmsProductId" : "MCG",
  "eeaDomesticRateQualificationIndicator" : "Y",
  "productCategory" : "D"
}
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

requestUuid

String

Request’s unique uuid in system

defaultCurrency

String

Default card currency

currencyCodes

Array

All card currencies with the default currency in the first place

cardholderCurrencyIndicator

String

Cardholder Currency Indicator support valid values:

C = Do not provide POI currency conversion (or DCC) –corporate client optout

D = POI currency conversion (or DCC) is permissible for account range per MastercardRules

T = Do not provide POI currency conversion (or DCC) per MastercardRules– travel cards or multi-currency accounts

U = Not a Mastercard-branded account range

When the field value is "D" the transaction can be processed as DCC otherwise error E00158 ("Transaction rejected, invalid Cardholder Currency Indicator for DCC transaction") returned

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard

DMC - Debit Mastercard

MSI - Maestro

CIR - Cirrus

PVL - Private Label

bankName

String

Bank name only for Mastercard

countryCardIssuing

String

Country card Issuing for Mastercard:

- ISO 3166-1 Alpha-3

countryCodeNumeric

String

Country code numeric for Mastercard::

- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES

- CANADA

- LATINA_AMERICA_AND_THE_CARIBBEAN

- ASIA_PACIFIC

- EUROPE

- SOUTH_ASIA_MIDDLE_EAST_AFRICA

- ANY

gcmsProductId

String

Gcms product id only for Mastercard:

This is the Product ID recognized by GCMS for the issuer account range and card program identifier combination. It may be different from the Licensed Product ID associated with the issuer account range and card program identifier combination.

eeaDomesticRateQualificationIndicator

String

EEA Domestic Rate Qualification Indicator only for Mastercard:

Y = EEA Domestic Rate qualified

N = Not EEA Domestic Rate qualified

productCategory

String

Identifies the product category, only for Mastercard

D = Debit

P = Prepaid

C = Credit

N = None(For non-Mastercad Product Codes)

200 OK Visa
{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "7d4e8a3f-72d7-4657-83f0-36588abaca2a",
  "defaultCurrency" : "PLN",
  "currencyCodes" : [ "PLN", "EUR" ],
  "cardholderCurrencyIndicator" : "D",
  "provider" : "VISA",
  "cardType" : "C",
  "countryCardIssuing" : "US",
  "countryCodeNumeric" : "840",
  "region" : "1",
  "productId" : "F",
  "binType" : "I",
  "domain" : "W",
  "settlementMatch" : " "
}
{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "7d4e8a3f-72d7-4657-83f0-36588abaca2a",
  "defaultCurrency" : "UNDEFINED",
  "currencyCodes" : [ "UNDEFINED" ],
  "cardholderCurrencyIndicator" : "D",
  "provider" : "VISA",
  "cardType" : "C",
  "countryCardIssuing" : "US",
  "countryCodeNumeric" : "840",
  "region" : "1",
  "productId" : "F",
  "binType" : "I",
  "domain" : "W",
  "settlementMatch" : " "
}
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

requestUuid

String

Request’s unique uuid in system

defaultCurrency

String

Default card currency

currencyCodes

Array

All card currencies with the default currency in the first place

cardholderCurrencyIndicator

String

Cardholder Currency Indicator support valid values:

C = Do not provide POI currency conversion (or DCC) –corporate client optout

D = POI currency conversion (or DCC) is permissible for account range per MastercardRules

T = Do not provide POI currency conversion (or DCC) per MastercardRules– travel cards or multi-currency accounts

U = Not a Mastercard-branded account range

When the field value is "D" the transaction can be processed as DCC otherwise error E00158 ("Transaction rejected, invalid Cardholder Currency Indicator for DCC transaction") returned

provider

String

Card’s provider

cardType

String

Card type for Visa:

C - Credit

D - Debit

P - Prepaid

H - Charge

countryCardIssuing

String

Country card Issuing for Visa:

- ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Visa::

- ISO 3166-1 Numeric

region

String

Region for Visa:

1 = US

2 = Canada

3 = Visa Europe

4 = Asia-Pacific

5 = Latin America and Carribean

6 = CEMEA

binType

String

Bin type for Visa:

F = Full Service

I = Issuer Only

M = Merchant Only

N = Nonfinancial

O = On Behalf Of (OBO)

P = Processor

S = SMS Financial entity

V = Visa Internal entity

domain

String

Domain for Visa:

W = (Worldwide)

R = (Regional)

N = (National)

D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values: A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C -Visa Signature, D - Visa Signature Preferred, DI -Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 -Visa Business Enhanced, G4 -Visa Infinite Business, G5 -Visa Business Rewards, I -Visa Infinite, I1 - Visa Infinite Privilege, I2 -Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T & E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 -Private Label Standard, Q4 -Private Label Enhanced, Q5 -Private Label Specialized, Q6 -Private Label Premium, R -Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 -Visa Government Purchasing with Fleet, S4 -Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match for Visa:

B = (B2B)

E = B2E

Space = (Not applicable)

401 UNAUTHORIZED
HTTP Response - STATUS: E80002
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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T12:29:01.246+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/processor/currency-for-card"
}
Table 22. Response fields
Path Type Description

timestamp

String

Time stamp

status

Number

Response code from Fenige system

error

String

Response http status

message

String

Message for response code from Fenige system

path

String

Path

404 NOT FOUND
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 203

{
  "requestUuid" : "7d4e8a3f-72d7-4657-83f0-36588abaca2a",
  "status" : "E00143",
  "message" : "Currency not found",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "54323719-c218-42d0-828b-949808cdaaef"
}
Path Type Description

requestUuid

String

Request’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

traceId

String

Id of error trace

500 INTERNAL SERVER ERROR
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 209

{
  "requestUuid" : "7d4e8a3f-72d7-4657-83f0-36588abaca2a",
  "status" : "E90000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "03cca272-47b0-40cc-80c0-92ca023b0583"
}
Path Type Description

requestUuid

String

Request’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

traceId

String

Id of error trace

503 SERVICE UNAVAILABLE
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Content-Length: 220

{
  "requestUuid" : "7d4e8a3f-72d7-4657-83f0-36588abaca2a",
  "status" : "E90001",
  "message" : "Error acquirer connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "eca4ceef-11c1-4d59-b853-08ae4fa611c4"
}
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Content-Length: 215

{
  "requestUuid" : "7d4e8a3f-72d7-4657-83f0-36588abaca2a",
  "status" : "E90002",
  "message" : "Error mpi connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "b2422e30-a97c-4ef6-8ffa-494ba852db33"
}
Path Type Description

requestUuid

String

Request’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

traceId

String

Id of error trace

7.2. Currency rate

POST /processor/currency-rate Content Type: application/json, Authorization: Basic Auth
Method is used for determine currency rate for revaluation from funding to payment (lowerRate) and payment to funding (higherRate).
Notice that `lowerRate` is used to transaction processing.
Api Send-money allows users to select the direction of revaluation by providing specify type value in send-money request.
1 - User by selecting type = SENDER defines amount of funding in given currency. This amount is collected from sender card in selected currency.
2 - User by selecting type = RECEIVER defines amount of payment in given currency. This amount is transferred to receiver card in selected currency.
In case there's need revaluation from one currency to another, system uses lowerRate for situation 1 and higherRate for situation 2.

7.2.1. Request

POST /processor/currency-rate HTTP/1.1
Authorization: Basic bmFtZTpwYXNzd29yZA==
Content-Type: application/json
Content-Length: 166
Host: processor-staging.fenige.pl

{
  "requestUuid" : "3a209ea4-9862-447f-a90b-347013261416",
  "provider" : "MASTERCARD",
  "from" : "USD",
  "to" : "PLN",
  "effectiveDate" : "2022-05-20 08:28:21"
}
Table 23. CURRENCY RATE REQUEST FIELDS
Path Type Constraints Description

requestUuid

String

@Must not be null

Request’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

effectiveDate

String

Date from which the currency rate is needed. This is optional field. When there is no effectiveDate field, then currency rate is getting from request date. (Format "yyyy-MM-ddHH:mm:ss")

7.2.2. Response

200 OK (Mastercard)
{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "3a209ea4-9862-447f-a90b-347013261416",
  "provider" : "MASTERCARD",
  "from" : "USD",
  "to" : "PLN",
  "buy" : 3.8199,
  "mid" : 3.82115,
  "sell" : 3.8224,
  "effectiveDateBegin" : "2022-05-20 01:31:19",
  "effectiveDateEnd" : "2022-05-21 01:31:19"
}
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

requestUuid

String

Request’s unique uuid in system

provider

String

provider

from

String

from

to

String

to

buy

Number

buy

mid

Number

mid

sell

Number

sell

effectiveDateBegin

String

effectiveDateBegin

effectiveDateEnd

String

effectiveDateEnd

200 OK (Maestro)
{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "3a209ea4-9862-447f-a90b-347013261416",
  "provider" : "MAESTRO",
  "from" : "USD",
  "to" : "PLN",
  "buy" : 3.8199,
  "mid" : 3.82115,
  "sell" : 3.8224,
  "effectiveDateBegin" : "2022-05-20 01:31:19",
  "effectiveDateEnd" : "2022-05-21 01:31:19"
}
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

requestUuid

String

Request’s unique uuid in system

provider

String

provider

from

String

from

to

String

to

buy

Number

buy

mid

Number

mid

sell

Number

sell

effectiveDateBegin

String

effectiveDateBegin

effectiveDateEnd

String

effectiveDateEnd

200 OK (VISA)
{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "3a209ea4-9862-447f-a90b-347013261416",
  "provider" : "VISA",
  "from" : "USD",
  "to" : "PLN",
  "buy" : 3.8199,
  "sell" : 3.8224,
  "effectiveDateBegin" : "2022-05-20 01:31:19",
  "effectiveDateEnd" : "2022-05-21 01:31:19"
}
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

requestUuid

String

Request’s unique uuid in system

provider

String

provider

from

String

from

to

String

to

buy

Number

buy

sell

Number

sell

effectiveDateBegin

String

effectiveDateBegin

effectiveDateEnd

String

effectiveDateEnd

401 UNAUTHORIZED
HTTP Response - STATUS: E80002
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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T12:29:01.246+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/processor/currency-rate"
}
Table 24. Response fields
Path Type Description

timestamp

String

Time stamp

status

Number

Response code from Fenige system

error

String

Response http status

message

String

Message for response code from Fenige system

path

String

Path

404 NOT FOUND
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 203

{
  "requestUuid" : "3a209ea4-9862-447f-a90b-347013261416",
  "status" : "E00143",
  "message" : "Currency not found",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "e7180ad8-7ae8-43a8-9d78-c1c3cbc7374e"
}
Path Type Description

requestUuid

String

Request’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

traceId

String

Id of error trace

500 INTERNAL SERVER ERROR
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 209

{
  "requestUuid" : "3a209ea4-9862-447f-a90b-347013261416",
  "status" : "E90000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "8655566e-1028-4b29-8b81-7f44d81835f7"
}
Path Type Description

requestUuid

String

Request’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

traceId

String

Id of error trace

503 SERVICE UNAVAILABLE
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Content-Length: 220

{
  "requestUuid" : "3a209ea4-9862-447f-a90b-347013261416",
  "status" : "E90001",
  "message" : "Error acquirer connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "557d3640-d0fc-44ef-a6ea-fae17ff83ed5"
}
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Content-Length: 215

{
  "requestUuid" : "3a209ea4-9862-447f-a90b-347013261416",
  "status" : "E90002",
  "message" : "Error mpi connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "c78a2120-2198-44c7-85a7-d4b51daeeb52"
}
Path Type Description

requestUuid

String

Request’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

traceId

String

Id of error trace

7.3. Card provider

POST /processor/card/provider Content Type: application/json, Authorization: Basic Auth
This method is used to check the card provider, for example: VISA or MASTERCARD.

7.3.1. Request

POST /processor/card/provider HTTP/1.1
Authorization: Basic bmFtZTpwYXNzd29yZA==
Content-Type: application/json
Content-Length: 97
Host: processor-staging.fenige.pl

{
  "requestUuid" : "4caf5665-3ee5-4d70-a279-9316d8ac0ebc",
  "cardNumber" : "5117964247989169"
}
Table 25. Request headers
Name Description

Authorization

Basic auth credentials for PSP

Table 26. Request fields
Path Type Constraints Description

requestUuid

String

@Must not be null

@Must not be null

cardNumber

String

@Must not be empty, @Must not be null, @Must pass the Luhn Modulo 10 checksum algorithm

PAN card number

7.3.2. Response

200 OK
HTTP Response - STATUS: S0000
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 160

{
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK",
  "requestUuid" : "4caf5665-3ee5-4d70-a279-9316d8ac0ebc",
  "provider" : "MASTERCARD"
}
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

requestUuid

String

Request’s unique uuid in system

provider

String

Card’s provider

401 UNAUTHORIZED
HTTP Response - STATUS: E80002
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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T12:29:01.246+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/processor/card/provider"
}
Table 28. Response fields
Path Type Description

timestamp

String

Time stamp

status

Number

Response code from Fenige system

error

String

Response http status

message

String

Message for response code from Fenige system

path

String

Path

500 INTERNAL SERVER ERROR
HTTP Response - STATUS: E90000
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 151

{
  "status" : "E90000",
  "message" : "Domain error",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "10aab43a-5202-4175-8126-469c5b4fda2e"
}
Table 29. 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

Id of trace

503 SERVICE UNAVAILABLE
HTTP Response - STATUS: E90002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Content-Length: 157

{
  "status" : "E90002",
  "message" : "Error mpi connection",
  "httpStatus" : "SERVICE_UNAVAILABLE",
  "traceId" : "9d56eece-8e70-4838-bcd5-7ee6aa9914bd"
}
Table 30. 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

Id of trace

7.4. Payment

POST /processor/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.
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.
Payment with DCC (Dynamic Currency Conversion) transaction is a dynamic transaction amount conversion service available at payment terminals, enabling payment in the
currency of the country where the credit card was issued.
The difference between DCC payment and standard payment is on the side of the Acquirer, who must check the card's currencies and present them on request. The client chooses
from the available currencies (or the default currency is automatically selected). Then Acquirer performs a currency conversion on its side to the chosen currency and sends to FENIGE a request with a dcc object in which it places the converted amount in the currency chosen by the Client.
Payment with 3ds flow
3ds authorize payment request processor
Payment DCC with 3ds flow
3ds authorize payment dcc request processor

7.4.1. Request

Payment with 3ds flow
POST /processor/payments/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 528
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
  "requestUuid" : "1f3c4006-6d44-4810-8c26-5c4583ae1e69",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "545313******4417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "autoClear" : true,
  "merchant" : {
    "merchantId" : "ac107c31-6fa9-45ab-acff-f6df8fa48cd9",
    "companyName" : "Company Name",
    "city" : "Lublin",
    "country" : "PL",
    "homeNumber" : "10",
    "street" : "Merchant street",
    "streetNumber" : "11",
    "postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "6051",
    "cryptoCurrency" : true,
    "specialConditionIndicatorExistingDebt" : false
  },
  "sender" : {
    "firstName" : "Mark",
    "lastName" : "Smith",
    "email" : "senderEmail@fenige.pl"
  },
  "outside3dsRequest" : {
    "authenticationStatus" : "Y",
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
    "eci" : "02",
    "authenticationTime" : "20180703 16:55:28",
    "cavvAlgorithm" : "3",
    "transactionxId" : "124"
  }
}
Table 31. Authorize request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

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

cardNumber

String

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

Must be a number and length must be between 12 and 19

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Optional only for Google pay, @Length must be 3 characters

Cardholder’s card cvc2

autoClear

Boolean

true or false

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

terminal.cryptoCurrency

Boolean

true or false

Is the terminal cryptocurrency. Default value is false.

terminal.specialConditionIndicatorExistingDebt

Boolean

true or false

This field indicates the cardholder is making a payment on a debt. Default value is false.

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is optional parameter. Without this parameter, transaction will be processed as a regular transaction without 3DS authorization.

outside3dsRequest.authenticationStatus

String

@must match Y or A or U, @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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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. More info.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

Payment DCC with 3ds flow
POST /processor/payments/auth HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 528
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
  "requestUuid" : "1f3c4006-6d44-4810-8c26-5c4583ae1e69",
  "amount" : 1000,
  "currency" : "PLN",
  "cardNumber" : "545313******4417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "autoClear" : true,
  "dcc":{
	"cardholderAmount" : 224,
	"cardholderCurrency" : "EUR",
	"conversionRateCardholder" : 0.2247541
  },
  "merchant" : {
    "merchantId" : "ac107c31-6fa9-45ab-acff-f6df8fa48cd9",
    "companyName" : "Company Name",
    "city" : "Lublin",
    "country" : "PL",
    "homeNumber" : "10",
    "street" : "Merchant street",
    "streetNumber" : "11",
    "postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
    "firstName" : "Mark",
    "lastName" : "Smith",
    "email" : "senderEmail@fenige.pl"
  },
  "outside3dsRequest" : {
    "authenticationStatus" : "Y",
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
    "eci" : "02",
    "authenticationTime" : "20180703 16:55:28",
    "cavvAlgorithm" : "3",
    "transactionxId" : "124"
  }
}
Table 32. Authorize request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

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) in transaction currency

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

Must be a number and length must be between 12 and 19

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Optional only for Google pay, @Length must be 3 characters

Cardholder’s card cvc2

autoClear

Boolean

True or false

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

dcc

Object

@Must not be null

There are dcc data that have been send to our API

dcc.cardholderAmount

Number

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

The total transfer amount (in pennies) in cardholder dcc currency

dcc.cardholderCurrency

String

@Must not be null

Currency of cardholder card (in accordance with ISO-4217), example: USD

dcc.conversionRateCardholder

BigDecimal

@Must not be null

The rate used to convert the transaction amount to the cardholder billing amount

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is optional parameter. Without this parameter, transaction will be processed as a regular transaction without 3DS authorization.

outside3dsRequest.authenticationStatus

String

@must match Y or A or U, @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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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. More info.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

7.4.2. Response

Response status
Status Description

200 OK

Returned when transaction was successfully authorized.

400 BAD REQUEST

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

401 UNAUTHORIZED

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

409 CONFLICT

STATUS: E001598 - Returned when transactionUUID already exists.

422 UNPROCESSABLE ENTITY

STATUS: E00158 - Cardholder Currency Indicator is invalid for DCC transaction.

STATUS: E001599 - Returned when card expiration date is invalid.

STATUS: E00160 - Returned when transaction rejected, cvc2 is required if no 3DS has been made.

500 INTERNAL SERVER ERROR

STATUS: E00153 - Returned when transaction is declined, by problem with MIP connection.

STATUS: E001597 - Returned when transaction declined, processing timeout.

STATUS: E90000 - Returned when reason is unknown.

503 SERVICE UNAVAILABLE

STATUS: E90001 - Returned when is error acquirer connection.

STATUS: E90002 - Returned when is error mpi connection.

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

{
  "transactionUuid" : "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
  "requestUuid" : "1f3c4006-6d44-4810-8c26-5c4583ae1e69",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "007007614129",
  "stan" : "614129",
  "provider" : "MASTERCARD",
  "cardType" : "DMC",
  "defaultCurrency" : "PLN",
  "bankName": "BANK MILLENNIUM S.A.",
  "countryCardIssuing": "POL",
  "countryCodeNumeric": "616",
  "region": "EUROPE",
  "gcmsProductId": "MCG",
  "eeaDomesticRateQualificationIndicator": "Y",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Table 33. Authorize response fields
Path Type Description

transactionUuid

String

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

Request’s unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

bankName

String

Bank name only for Mastercard

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

gcmsProductId

String

Gcms product id only for Mastercard

This is the Product ID recognized by GCMS for the issuer account range and card program identifier combination. It may be different from the Licensed Product ID associated with the issuer account range and card program identifier combination.

eeaDomesticRateQualificationIndicator

String

EEA Domestic Rate Qualification Indicator only for Mastercard: Valid values:
Y = EEA Domestic Rate qualified
N = Not EEA Domestic Rate qualified

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

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

{
  "transactionUuid" : "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
  "requestUuid" : "1f3c4006-6d44-4810-8c26-5c4583ae1e69",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "007007614129",
  "stan" : "614129",
  "provider" : "VISA",
  "cardType" : "C",
  "defaultCurrency" : "USD",
  "countryCardIssuing": "US",
  "countryCodeNumeric": "840",
  "region": "1",
  "binType": "I",
  "domain": "W",
  "productId": "F",
  "settlementMatch": " ",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Table 34. Authorize response fields
Path Type Description

transactionUuid

String

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

Request’s unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

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: E80000
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, 12 Mar 2020 14:03:26 GMT
Connection: close
Content-Length: 640

{
  "errors" : {
    "expiryDate" : [ "must not be null", "invalid card expiration date", "must not be blank" ],
    "lastName" : [ "must not be blank", "must not be null" ],
    "firstName" : [ "must not be null", "may not be empty" ],
    "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 null", "must not be blank" ]
  },
  "status" : "E80000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "77caa2c3-df04-4e07-bf56-b4b1d92b53f0"
}
Table 35. 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: E80002
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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T07:17:31.968+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/processor/payments/auth"
}
Table 36. Response fields
Path Type Description

timestamp

String

Time stamp

status

Number

Response code from Fenige system

error

String

Response http status

message

String

Message for response code from Fenige system

path

String

Path

409 Conflict
HTTP/1.1 409 Conflict
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "06396fa7-4281-40e2-970d-9894f91b5de6",
    "transactionUuid": "c3413be2-a66f-4437-945c-1b3a5258c857",
    "status": "E001598",
    "message": "Transaction rejected, transactionUUID already exists",
    "httpStatus": "CONFLICT",
    "traceId": "66cd08e1-9153-45be-9428-208f2e73ae99"
}
Table 37. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’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

traceId

String

Unique id for this http request register in system

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E00150
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00150",
    "message": "Transaction rejected",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
HTTP Response - STATUS: E00151
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00151",
    "message": "Transaction rejected, currency not supported",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
HTTP Response - STATUS: E00152
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00152",
    "message": "Transaction rejected, issuer card not supported",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
HTTP Response - STATUS: E00156
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00156",
    "message": "Transaction rejected, initial recurring transaction not cleared/exist",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
HTTP Response - STATUS: E00158
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00158",
    "message": "Transaction rejected, invalid Cardholder Currency Indicator for DCC transaction",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
HTTP Response - STATUS: E00159
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00159",
    "message": "Transaction rejected, initial CoF transaction not cleared/exist",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
HTTP Response - STATUS: E00160
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00160",
    "message": "Transaction rejected, cvc2 is required if no 3DS has been made",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
Table 38. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "status": "E90000",
    "message": "Domain error",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "8c1d724c-f5ca-4543-aa8f-1db865bdf059"
}
HTTP Response - STATUS: E00153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "1f1c4006-6d18-4810-8c26-5c1583ae1e92",
    "transactionUuid": "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
    "transactionStatus": "DECLINED",
    "status": "E00153",
    "message": "Transaction declined, problem with MIP connection",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001597
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001597",
    "message": "Transaction declined, processing timeout",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001900
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001900",
    "message": "Installment Payment initial not found",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001901
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001901",
    "message": "Installment Payment already confirmed",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001902
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001902",
    "message": "Installment Payment already cancelled",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001903
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001903",
    "message": "Installment Payment already pay in full",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001904
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001904",
    "message": "Installment Payment not confirmed in required time",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001905
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001905",
    "message": "Installment Payment Initial was failed",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001906
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001906",
    "message": "Installment Payment could not find valid installment plan for requested uuid",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001907
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001907",
    "message": "Installment Payment Option not allowed for transaction",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001908
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001908",
    "message": "Installment Payment missing plan uuid",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001909
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001909",
    "message": "Installment Payment missing request number of installments",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001910
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001910",
    "message": "Installment Payment requested number of installments is outside of allowed range",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
Table 39. Response fields
Path Type Description

requestUuid

String

Request unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "requestUuid": "849343cf-a0c0-439b-a64d-476a7e5afbc6",
    "transactionUuid": "6d6463cf-d644-47b0-b285-d505784a9757",
    "transactionStatus": "ERROR",
    "status": "E90001",
    "message": "Error acquirer connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "eb3eb56f-2e01-4211-ba34-654b5a5f2c31"
}
HTTP Response - STATUS: E90002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 267

{
    "requestUuid": "849343cf-a0c0-439b-a64d-476a7e5afbc6",
    "transactionUuid": "6d6463cf-d644-47b0-b285-d505784a9757",
    "transactionStatus": "ERROR",
    "status": "E90002",
    "message": "Error mpi connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "6675fab9-05a9-4158-b852-e5b15fe577ca"
}
Table 40. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

7.5. MO/TO payment

POST /processor/payments/moto 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).
A MO/TO DCC (Dynamic Currency Conversion) transaction is a dynamic transaction amount conversion service available at payment terminals, enabling payment in the currency of the
country where the credit card was issued.
The difference between DCC payment and standard payment is on the side of the Acquirer, who must check the card's currencies and present them on request. The client chooses
from the available currencies (or the default currency is automatically selected). Then Acquirer performs a currency conversion on its side to the chosen currency and sends to FENIGE a request with a dcc object in which it places the converted amount in the currency chosen by the Client.
MO/TO
moto payment
MO/TO DCC
moto dcc payment

7.5.1. Request

MO/TO with CVC
POST /processor/payments/moto HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 119
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "23439464-8fa1-4027-baa7-2c81e0d1f1f4",
  "requestUuid": "4d3a45a3-32ed-4352-8298-8b1ddae6028f",
  "currency" : "PLN",
  "amount" : 1000,
  "cardNumber" : "5486009685692819",
  "expiryDate" : "12/22",
  "autoClear" : true,
  "motoType": "CVC",
  "cvc2": "587",
  "merchant" : {
	"merchantId" : "1386a6c7-bce8-4ace-a06e-8b02be5458b5",
	"companyName" : "Company Name",
	"city" : "Lublin",
	"country" : "PL",
	"homeNumber" : "10",
	"street" : "Merchant Street",
	"streetNumber" : "11",
	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
	"firstName" : "Mark",
	"lastName" : "Smith",
	"email": "senderEmail@fenige.pl"
  }
}
Table 41. Request headers

Name

Description

Authorization

Basic auth credentials for Acquirer

Table 42. MO/TO Payment request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

currency

String

@Must not be null

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

amount

Number

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

The total transfer amount (in pennies)

cardNumber

String

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

Must be a number and length must be between 12 and 19

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

autoClear

Boolean

True or false

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

motoType

String

@Must not be null

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

MO/TO with AVS
POST /processor/payments/moto HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 119
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "23439464-8fa1-4027-baa7-2c81e0d1f1f4",
  "requestUuid": "4d3a45a3-32ed-4352-8298-8b1ddae6028f",
  "currency" : "PLN",
  "amount" : 1000,
  "cardNumber" : "5486009685692819",
  "expiryDate" : "12/22",
  "autoClear" : true,
  "motoType": "AVS",
  "clientPostalCode": "11-111",
  "clientAddress": "5",
  "merchant" : {
	"merchantId" : "1386a6c7-bce8-4ace-a06e-8b02be5458b5",
	"companyName" : "Company Name",
	"city" : "Lublin",
	"country" : "PL",
	"homeNumber" : "10",
	"street" : "Merchant Street",
	"streetNumber" : "11",
	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
	"firstName" : "Mark",
	"lastName" : "Smith",
	"email": "senderEmail@fenige.pl"
  }
}
Table 43. Request headers

Name

Description

Authorization

Basic auth credentials for Acquirer

Table 44. MO/TO Payment request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

currency

String

@Must not be null

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

amount

Number

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

The total transfer amount (in pennies)

cardNumber

String

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

Must be a number and length must be between 12 and 19

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

True or false

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

motoType

String

@Must not be null

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

clientPostalCode

String

@Must not be null when MO/TO 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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

MO/TO DCC with CVC
POST /processor/payments/moto HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 119
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "23439464-8fa1-4027-baa7-2c81e0d1f1f4",
  "requestUuid": "4d3a45a3-32ed-4352-8298-8b1ddae6028f",
  "currency" : "PLN",
  "amount" : 1000,
  "cardNumber" : "5486009685692819",
  "expiryDate" : "12/22",
  "autoClear" : true,
  "motoType": "CVC",
  "cvc2": "587",
  "dcc":{
	"cardholderAmount" : 224,
	"cardholderCurrency" : "EUR",
	"conversionRateCardholder" : 0.2247541
  },
  "merchant" : {
	"merchantId" : "1386a6c7-bce8-4ace-a06e-8b02be5458b5",
	"companyName" : "Company Name",
	"city" : "Lublin",
	"country" : "PL",
	"homeNumber" : "10",
	"street" : "Merchant Street",
	"streetNumber" : "11",
	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
	"firstName" : "Mark",
	"lastName" : "Smith",
	"email": "senderEmail@fenige.pl"
  }
}
Table 45. Request headers

Name

Description

Authorization

Basic auth credentials for Acquirer

Table 46. MO/TO DCC Payment request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

currency

String

@Must not be null

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

amount

Number

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

The total transfer amount (in pennies)

cardNumber

String

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

Must be a number and length must be between 12 and 19

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

autoClear

Boolean

True or false

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

motoType

String

@Must not be null

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

dcc

Object

@Must not be null

The total transfer amount (in pennies) in transaction currency

dcc.cardholderAmount

Number

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

The total transfer amount (in pennies) in cardholder dcc currency

dcc.cardholderCurrency

String

@Must not be null

Currency of cardholder card (in accordance with ISO-4217), example: USD

dcc.conversionRateCardholder

BigDecimal

@Must not be null

The rate used to convert the transaction amount to the cardholder billing amount

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

MO/TO DCC with AVS
POST /processor/payments/moto HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 119
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "23439464-8fa1-4027-baa7-2c81e0d1f1f4",
  "requestUuid": "4d3a45a3-32ed-4352-8298-8b1ddae6028f",
  "currency" : "PLN",
  "amount" : 1000,
  "cardNumber" : "5486009685692819",
  "expiryDate" : "12/22",
  "autoClear" : true,
  "motoType": "AVS",
  "clientPostalCode": "11-111",
  "clientAddress": "5",
  "dcc":{
	"cardholderAmount" : 224,
	"cardholderCurrency" : "EUR",
	"conversionRateCardholder" : 0.2247541
  },
  "merchant" : {
	"merchantId" : "1386a6c7-bce8-4ace-a06e-8b02be5458b5",
	"companyName" : "Company Name",
	"city" : "Lublin",
	"country" : "PL",
	"homeNumber" : "10",
	"street" : "Merchant Street",
	"streetNumber" : "11",
	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
	"firstName" : "Mark",
	"lastName" : "Smith",
	"email": "senderEmail@fenige.pl"
  }
}
Table 47. Request headers

Name

Description

Authorization

Basic auth credentials for Acquirer

Table 48. MO/TO DCC Payment request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

currency

String

@Must not be null

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

amount

Number

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

The total transfer amount (in pennies) in transaction currency

cardNumber

String

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

Must be a number and length must be between 12 and 19

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

True or false

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

motoType

String

@Must not be null

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

clientPostalCode

String

@Must not be null when MO/TO 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

dcc

Object

@Must not be null

There are dcc data that have been send to our API

dcc.cardholderAmount

Number

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

The total transfer amount (in pennies) in cardholder dcc currency

dcc.cardholderCurrency

String

@Must not be null

Currency of cardholder card (in accordance with ISO-4217), example: USD

dcc.conversionRateCardholder

BigDecimal

@Must not be null

The rate used to convert the transaction amount to the cardholder billing amount

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

7.5.2. Response

Response status
Status Description

200 OK

STATUS: S00002 - Returned when transaction was successfully authorized.

400 BAD REQUEST

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

401 UNAUTHORIZED

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

403 FORBIDDEN

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

404 NOT FOUND

STATUS: E00155 - Returned when not found transaction or transaction not exist.

409 CONFLICT

STATUS: E001598 - Returned when transactionUUID already exists.

422 UNPROCESSABLE ENTITY

STATUS: E00158 - Returned when Cardholder Currency Indicator is invalid for DCC transaction.

STATUS: E001599 - Returned when card expiration date is invalid.

500 INTERNAL SERVER ERROR

STATUS: E00153 - Returned when transaction is declined, by problem with MIP connection.

STATUS: E001597 - Returned when transaction declined, processing timeout.

STATUS: E90000 - Returned when reason is unknown.

503 SERVICE UNAVAILABLE

STATUS: E90001 - Returned when is error acquirer connection.

STATUS: E90002 - Returned when is error mpi connection.

200 OK Mastercard
HTTP Response - STATUS: S00002
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 164

{
    "requestUuid": "4d3a45a3-32ed-4352-8298-8b1ddae6028f",
    "transactionUuid": "23439464-8fa1-4027-baa7-2c81e0d1f1f4",
    "transactionStatus": "APPROVED",
    "responseCode": "CODE_00",
    "rrn": "015308100167",
    "stan": "100167",
    "provider" : "MASTERCARD",
    "cardType" : "DMC",
    "defaultCurrency" : "PLN",
    "bankName": "BANK MILLENNIUM S.A.",
    "countryCardIssuing": "POL",
    "countryCodeNumeric": "616",
    "region": "EUROPE",
    "gcmsProductId": "MCG",
    "eeaDomesticRateQualificationIndicator": "Y",
    "status": "S00002",
    "message": "Success transaction",
    "httpStatus": "OK"
}
Table 49. MO/TO payment response fields
Path Type Description

transactionUuid

String

Transaction’s unique uuid in system

requestUuid

String

Request’s unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

bankName

String

Bank name only for Mastercard

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

gcmsProductId

String

Gcms product id only for Mastercard

This is the Product ID recognized by GCMS for the issuer account range and card program identifier combination. It may be different from the Licensed Product ID associated with the issuer account range and card program identifier combination.

eeaDomesticRateQualificationIndicator

String

EEA Domestic Rate Qualification Indicator only for Mastercard: Valid values:
Y = EEA Domestic Rate qualified
N = Not EEA Domestic Rate qualified

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

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

{
  "requestUuid" : "4d3a45a3-32ed-4352-8298-8b1ddae6028f",
  "transactionUuid" : "23439464-8fa1-4027-baa7-2c81e0d1f1f4",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "015308100167",
  "stan" : "100167",
  "provider" : "VISA",
  "cardType" : "C",
  "defaultCurrency" : "USD",
  "countryCardIssuing": "US",
  "countryCodeNumeric": "840",
  "region": "1",
  "binType": "I",
  "domain": "W",
  "productId": "F",
  "settlementMatch": " ",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Table 50. Authorize response fields
Path Type Description

transactionUuid

String

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

Request’s unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

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: E80000
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, 12 Mar 2020 14:03:26 GMT
Connection: close
Content-Length: 640

{
    "errors": {
        "expiryDate": [
            "must not be blank",
            "must not be null",
            "invalid card expiration date"
        ],
        "transactionUuid": [
            "must not be null"
        ],
        "amount": [
            "must not be null"
        ],
        "dcc": [
            "must not be null"
        ],
        "sender": [
            "must not be null"
        ],
        "requestUuid": [
            "must not be null"
        ],
        "merchant": [
            "must not be null"
        ],
        "currency": [
            "must not be null"
        ],
        "cvc2": [
            "must not be blank",
            "must not be null"
        ],
        "cardNumber": [
            "must not be null",
            "must not be blank"
        ]
    },
    "status": "E80000",
    "httpStatus": "BAD_REQUEST",
    "traceId": "5e0febea-cf8a-4532-bb66-de806093ce1b"
}
HTTP Response - STATUS: E80000
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, 12 Mar 2020 14:03:26 GMT
Connection: close
Content-Length: 640

{
    "errors": {
        "expiryDate": [
            "must not be blank",
            "must not be null",
            "invalid card expiration date"
        ],
        "transactionUuid": [
            "must not be null"
        ],
        "amount": [
            "must not be null"
        ],
        "sender": [
            "must not be null"
        ],
        "requestUuid": [
            "must not be null"
        ],
        "merchant": [
            "must not be null"
        ],
        "currency": [
            "must not be null"
        ],
        "cvc2": [
            "must not be blank",
            "must not be null"
        ],
        "cardNumber": [
            "must not be null",
            "must not be blank"
        ]
    },
    "status": "E80000",
    "httpStatus": "BAD_REQUEST",
    "traceId": "5e0febea-cf8a-4532-bb66-de806093ce1b"
}
Table 51. 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: E80002
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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T07:17:31.968+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/processor/payments/moto"
}
Table 52. Response fields
Path Type Description

timestamp

String

Time stamp

status

Number

Response code from Fenige system

error

String

Response http status

message

String

Message for response code from Fenige system

path

String

Path

409 Conflict
HTTP/1.1 409 Conflict
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "06396fa7-4281-40e2-970d-9894f91b5de6",
    "transactionUuid": "c3413be2-a66f-4437-945c-1b3a5258c857",
    "status": "E001598",
    "message": "Transaction rejected, transactionUUID already exists",
    "httpStatus": "CONFLICT",
    "traceId": "66cd08e1-9153-45be-9428-208f2e73ae99"
}
Table 53. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’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

traceId

String

Unique id for this http request register in system

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E00158
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00158",
    "message": "Returned when Cardholder Currency Indicator is invalid for DCC transaction.",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
Table 54. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "status": "E90000",
    "message": "Domain error",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "8c1d724c-f5ca-4543-aa8f-1db865bdf059"
}
HTTP Response - STATUS: E00153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "1f1c4006-6d18-4810-8c26-5c1583ae1e92",
    "transactionUuid": "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
    "transactionStatus": "DECLINED",
    "status": "E00153",
    "message": "Transaction declined, problem with MIP connection",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001597
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001597",
    "message": "Transaction declined, processing timeout",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
Table 55. Response fields
Path Type Description

requestUuid

String

Request unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "requestUuid": "4d3a45a3-32ed-4352-8298-8b1ddae6028f",
    "transactionUuid": "23439464-8fa1-4027-baa7-2c81e0d1f1f4",
    "transactionStatus": "ERROR",
    "status": "E90001",
    "message": "Error acquirer connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "2ffd3ef9-c2f8-4d19-8459-eecf743b088d"
}
HTTP Response - STATUS: E90002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 267

{
    "requestUuid": "4d3a45a3-32ed-4352-8298-8b1ddae6028f",
    "transactionUuid": "23439464-8fa1-4027-baa7-2c81e0d1f1f4",
    "transactionStatus": "ERROR",
    "status": "E90002",
    "message": "Error mpi connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "a948f9be-1540-48af-8e18-17dcd24f6e89"
}
Table 56. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

7.6. Token payment

POST /processor/payments/token 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 (Apple
pay/) 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.

Google pay - payment with Google pay is a standard ecommerce payment for which you can use the 5.4. Payment method except that there is no CVC field

Payment with DCC (Dynamic Currency Conversion) transaction is a dynamic transaction amount conversion service available at payment terminals, enabling payment in the
currency of the country where the credit card was issued.
The difference between DCC payment and standard payment is on the side of the Acquirer, who must check the card's currencies and present them on request. The client chooses
from the available currencies (or the default currency is automatically selected). Then Acquirer performs a currency conversion on its side to the chosen currency and sends to FENIGE a request with a dcc object in which it places the converted amount in the currency chosen by the Client.
Token payment
authorize token payment request processor
Token payment with 3ds flow
3ds authorize token payment request processor
Token payment DCC with 3ds flow
3ds authorize token payment dcc request processor

7.6.1. Request

Token payment
POST /processor/payments/token HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 528
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
  "requestUuid" : "1f3c4006-6d44-4810-8c26-5c4583ae1e69",
  "amount" : 1000,
  "currency" : "USD",
  "tokenPan" : "5127482301411937126",
  "expiryDate" : "11/22",
  "autoClear" : true,
  "merchant" : {
    "merchantId" : "ac107c31-6fa9-45ab-acff-f6df8fa48cd9",
    "companyName" : "Company Name",
    "city" : "Lublin",
    "country" : "PL",
    "homeNumber" : "10",
    "street" : "Merchant street",
    "streetNumber" : "11",
    "postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "cryptoCurrency" : false,
    "specialConditionIndicatorExistingDebt" : false,
    "terminalLocation" : "HOME"
  },
  "sender" : {
    "firstName" : "Mark",
    "lastName" : "Smith",
    "email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
Table 57. Authorize request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

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

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 apple etc

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

true or false

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

terminal.cryptoCurrency

Boolean

true or false

Is the terminal cryptocurrency. Default value is false.

terminal.specialConditionIndicatorExistingDebt

Boolean

true or false

This field indicates the cardholder is making a payment on a debt. Default value is false.

terminal.terminalLocation

String

@Must not be null

Location of terminal - value must be set as HOME or PREMISES

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

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

Token payment DCC
POST /processor/payments/token HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 528
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
  "requestUuid" : "1f3c4006-6d44-4810-8c26-5c4583ae1e69",
  "amount" : 1000,
  "currency" : "PLN",
  "tokenPan" : "5127482301411937126",
  "expiryDate" : "11/22",
  "autoClear" : true,
  "dcc":{
	"cardholderAmount" : 224,
	"cardholderCurrency" : "EUR",
	"conversionRateCardholder" : 0.2247541
  },
  "merchant" : {
    "merchantId" : "ac107c31-6fa9-45ab-acff-f6df8fa48cd9",
    "companyName" : "Company Name",
    "city" : "Lublin",
    "country" : "PL",
    "homeNumber" : "10",
    "street" : "Merchant street",
    "streetNumber" : "11",
    "postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "terminalLocation" : "HOME"
  },
  "sender" : {
    "firstName" : "Mark",
    "lastName" : "Smith",
    "email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
Table 58. Authorize request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

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) in transaction currency

currency

String

@Must not be null

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

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 apple etc

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

True or false

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

dcc

Object

@Must not be null

There are dcc data that have been send to our API

dcc.cardholderAmount

Number

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

The total transfer amount (in pennies) in cardholder dcc currency

dcc.cardholderCurrency

String

@Must not be null

Currency of cardholder card (in accordance with ISO-4217), example: USD

dcc.conversionRateCardholder

BigDecimal

@Must not be null

The rate used to convert the transaction amount to the cardholder billing amount

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

terminal.terminalLocation

String

@Must not be null

Location of terminal - value must be set as HOME or PREMISES

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

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

Token payment with 3ds flow
POST /processor/payments/token HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 528
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
  "requestUuid" : "1f3c4006-6d44-4810-8c26-5c4583ae1e69",
  "amount" : 1000,
  "currency" : "USD",
  "tokenPan" : "5127482301411937126",
  "expiryDate" : "11/22",
  "autoClear" : true,
  "merchant" : {
    "merchantId" : "ac107c31-6fa9-45ab-acff-f6df8fa48cd9",
    "companyName" : "Company Name",
    "city" : "Lublin",
    "country" : "PL",
    "homeNumber" : "10",
    "street" : "Merchant street",
    "streetNumber" : "11",
    "postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "terminalLocation" : "HOME"
  },
  "sender" : {
    "firstName" : "Mark",
    "lastName" : "Smith",
    "email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  },
  "outside3dsRequest" : {
    "authenticationStatus" : "Y",
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
    "eci" : "02",
    "authenticationTime" : "20180703 16:55:28",
    "cavvAlgorithm" : "3",
    "transactionxId" : "124"
  }
}
Table 59. Authorize request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

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

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 apple etc

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

true or false

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

terminal.terminalLocation

String

@Must not be null

Location of terminal - value must be set as HOME or PREMISES

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

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

First name of card holder

sender.lastName

String

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

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

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

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is optional parameter. Without this parameter, transaction will be processed as a regular transaction without 3DS authorization.

outside3dsRequest.authenticationStatus

String

@must match Y or A or U, @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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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. More info.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

Token payment DCC with 3ds flow
POST /processor/payments/token HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 528
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
  "requestUuid" : "1f3c4006-6d44-4810-8c26-5c4583ae1e69",
  "amount" : 1000,
  "currency" : "PLN",
  "tokenPan" : "5127482301411937126",
  "expiryDate" : "11/22",
  "autoClear" : true,
  "dcc":{
	"cardholderAmount" : 224,
	"cardholderCurrency" : "EUR",
	"conversionRateCardholder" : 0.2247541
  },
  "merchant" : {
    "merchantId" : "ac107c31-6fa9-45ab-acff-f6df8fa48cd9",
    "companyName" : "Company Name",
    "city" : "Lublin",
    "country" : "PL",
    "homeNumber" : "10",
    "street" : "Merchant street",
    "streetNumber" : "11",
    "postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "terminalLocation" : "HOME"
  },
  "sender" : {
    "firstName" : "Mark",
    "lastName" : "Smith",
    "email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  },
  "outside3dsRequest" : {
    "authenticationStatus" : "Y",
    "cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
    "eci" : "02",
    "authenticationTime" : "20180703 16:55:28",
    "cavvAlgorithm" : "3",
    "transactionxId" : "124"
  }
}
Table 60. Authorize request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

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) in transaction currency

currency

String

@Must not be null

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

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 apple etc

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

True or false

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

dcc

Object

@Must not be null

There are dcc data that have been send to our API

dcc.cardholderAmount

Number

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

The total transfer amount (in pennies) in cardholder dcc currency

dcc.cardholderCurrency

String

@Must not be null

Currency of cardholder card (in accordance with ISO-4217), example: USD

dcc.conversionRateCardholder

BigDecimal

@Must not be null

The rate used to convert the transaction amount to the cardholder billing amount

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

terminal.terminalLocation

String

@Must not be null

Location of terminal - value must be set as HOME or PREMISES

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

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

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is optional parameter. Without this parameter, transaction will be processed as a regular transaction without 3DS authorization.

outside3dsRequest.authenticationStatus

String

@must match Y or A or U, @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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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. More info.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

7.6.2. Response

Response status
Status Description

200 OK

Returned when transaction was successfully authorized.

400 BAD REQUEST

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

401 UNAUTHORIZED

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

409 CONFLICT

STATUS: E001598 - Returned when transactionUUID already exists.

422 UNPROCESSABLE ENTITY

STATUS: E00158 - Returned when Cardholder Currency Indicator is invalid for DCC transaction.

STATUS: E001599 - Returned when card expiration date is invalid.

500 INTERNAL SERVER ERROR

STATUS: E00153 - Returned when transaction is declined, by problem with MIP connection.

STATUS: E001597 - Returned when transaction declined, processing timeout.

STATUS: E90000 - Returned when reason is unknown.

503 SERVICE UNAVAILABLE

STATUS: E90001 - Returned when is error acquirer connection.

STATUS: E90002 - Returned when is error mpi connection.

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

{
  "transactionUuid" : "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
  "requestUuid" : "1f3c4006-6d44-4810-8c26-5c4583ae1e69",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "007007614129",
  "stan" : "614129",
  "provider" : "MASTERCARD",
  "cardType" : "DMC",
  "defaultCurrency" : "PLN",
  "bankName": "BANK MILLENNIUM S.A.",
  "countryCardIssuing": "POL",
  "countryCodeNumeric": "616",
  "region": "EUROPE",
  "gcmsProductId": "MCG",
  "eeaDomesticRateQualificationIndicator": "Y",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Table 61. Authorize response fields
Path Type Description

transactionUuid

String

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

Request’s unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

bankName

String

Bank name only for Mastercard

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

gcmsProductId

String

Gcms product id only for Mastercard

This is the Product ID recognized by GCMS for the issuer account range and card program identifier combination. It may be different from the Licensed Product ID associated with the issuer account range and card program identifier combination.

eeaDomesticRateQualificationIndicator

String

EEA Domestic Rate Qualification Indicator only for Mastercard: Valid values:
Y = EEA Domestic Rate qualified
N = Not EEA Domestic Rate qualified

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

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

{
  "transactionUuid" : "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
  "requestUuid" : "1f3c4006-6d44-4810-8c26-5c4583ae1e69",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "007007614129",
  "stan" : "614129",
  "provider" : "VISA",
  "cardType" : "C",
  "defaultCurrency" : "USD",
  "countryCardIssuing": "US",
  "countryCodeNumeric": "840",
  "region": "1",
  "binType": "I",
  "domain": "W",
  "productId": "F",
  "settlementMatch": " ",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Table 62. Authorize response fields
Path Type Description

transactionUuid

String

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

Request’s unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

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: E80000
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, 12 Mar 2020 14:03:26 GMT
Connection: close
Content-Length: 640

{
  "errors" : {
    "expiryDate" : [ "must not be null", "invalid card expiration date", "must not be blank" ],
    "lastName" : [ "must not be blank", "must not be null" ],
    "firstName" : [ "must not be null", "may not be empty" ],
    "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" ],
    "tokenPan" : [ "must not be null", "must not be blank" ]
  },
  "status" : "E80000",
  "httpStatus" : "BAD_REQUEST",
  "traceId" : "77caa2c3-df04-4e07-bf56-b4b1d92b53f0"
}
Table 63. 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: E80002
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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T07:17:31.968+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/processor/payments/auth"
}
Table 64. Response fields
Path Type Description

timestamp

String

Time stamp

status

Number

Response code from Fenige system

error

String

Response http status

message

String

Message for response code from Fenige system

path

String

Path

409 Conflict
HTTP/1.1 409 Conflict
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "06396fa7-4281-40e2-970d-9894f91b5de6",
    "transactionUuid": "c3413be2-a66f-4437-945c-1b3a5258c857",
    "status": "E001598",
    "message": "Transaction rejected, transactionUUID already exists",
    "httpStatus": "CONFLICT",
    "traceId": "66cd08e1-9153-45be-9428-208f2e73ae99"
}
Table 65. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’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

traceId

String

Unique id for this http request register in system

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E00158
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00158",
    "message": "Returned when Cardholder Currency Indicator is invalid for DCC transaction.",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
Table 66. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "status": "E90000",
    "message": "Domain error",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "8c1d724c-f5ca-4543-aa8f-1db865bdf059"
}
HTTP Response - STATUS: E00153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "1f1c4006-6d18-4810-8c26-5c1583ae1e92",
    "transactionUuid": "9c6d8759-6e51-4b3d-a739-6d684d8cb6e4",
    "transactionStatus": "DECLINED",
    "status": "E00153",
    "message": "Transaction declined, problem with MIP connection",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001597
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001597",
    "message": "Transaction declined, processing timeout",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
Table 67. Response fields
Path Type Description

requestUuid

String

Request unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "requestUuid": "849343cf-a0c0-439b-a64d-476a7e5afbc6",
    "transactionUuid": "6d6463cf-d644-47b0-b285-d505784a9757",
    "transactionStatus": "ERROR",
    "status": "E90001",
    "message": "Error acquirer connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "eb3eb56f-2e01-4211-ba34-654b5a5f2c31"
}
HTTP Response - STATUS: E90002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 267

{
    "requestUuid": "849343cf-a0c0-439b-a64d-476a7e5afbc6",
    "transactionUuid": "6d6463cf-d644-47b0-b285-d505784a9757",
    "transactionStatus": "ERROR",
    "status": "E90002",
    "message": "Error mpi connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "6675fab9-05a9-4158-b852-e5b15fe577ca"
}
Table 68. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

7.7. CoF payment

The CoF initial transaction can be performed with or without 3DS. On the Acquirer side there is the logic of processing CoF transactions - periodical subsequent calling and
remembering the card number and expiry date which is necessary to proceed subsequent transaction which no longer requires CVC or 3ds.
Payment with DCC (Dynamic Currency Conversion) transaction is a dynamic transaction amount conversion service available at payment terminals, enabling payment in the
currency of the country where the credit card was issued.
The difference between DCC payment and standard payment is on the side of the Acquirer, who must check the card's currencies and present them on request. The client chooses
from the available currencies (or the default currency is automatically selected). Then Acquirer performs a currency conversion on its side to the chosen currency and sends to FENIGE a request with a dcc object in which it places the converted amount in the currency chosen by the Client.

Since 16 May, Fenige has enabled the initialisation and processing of recurring transactions back to back with tokenised cards. An additional confirmation of authentication is provided by cryptographic data from mobile applications, which can be optionally provided in the paymentData object similar to the 7.6 Token Payment method.

CoF payment
cof payment request
CoF DCC payment
cof dcc payment request

7.7.1. CoF Initial

Request
CoF Initial
POST /processor/payments/cof/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
  "requestUuid" : "722f93a7-51d1-4082-b5b0-ef23dcd18484",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "545313******4417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "autoClear" : true,
  "merchant" : {
  	"merchantId" : "4db50ee6-bcb4-43dd-8316-f5b38089bf0b",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "outside3dsRequest" : {
  	"authenticationStatus" : "Y",
  	"cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
  	"eci" : "02",
  	"authenticationTime" : "20180703 16:55:28",
  	"cavvAlgorithm" : "3",
  	"transactionxId" : "124"
  }
}
Table 69. CoF Initial request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

amount

Number

@Must not be null

The total transfer amount (in pennies). If the amount is equal to zero there is sent account status inquiry to validate aspects of a cardholder account.

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

Must be a number and length must be between 12 and 19

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Optional, @Length must be 3 characters

Cardholder’s card cvc2

autoClear

Boolean

true or false

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is optional parameter. Without this parameter, transaction will be processed as a regular transaction without 3DS authorization.

outside3dsRequest.authenticationStatus

String

@must match Y or A or U, @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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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. More info.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

CoF DCC Initial
POST /processor/payments/cof/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
  "requestUuid" : "722f93a7-51d1-4082-b5b0-ef23dcd18484",
  "amount" : 1000,
  "currency" : "PLN",
  "cardNumber" : "545313******4417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "autoClear" : true,
  "dcc":{
	"cardholderAmount" : 224,
	"cardholderCurrency" : "EUR",
	"conversionRateCardholder" : 0.2247541
  },
  "merchant" : {
  	"merchantId" : "4db50ee6-bcb4-43dd-8316-f5b38089bf0b",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "outside3dsRequest" : {
  	"authenticationStatus" : "Y",
  	"cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
  	"eci" : "02",
  	"authenticationTime" : "20180703 16:55:28",
  	"cavvAlgorithm" : "3",
  	"transactionxId" : "124"
  }
}
Table 70. CoF Initial request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

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) in transaction currency

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

Must be a number and length must be between 12 and 19"

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Optional, @Length must be 3 characters

Cardholder’s card cvc2

autoClear

Boolean

True or false

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

dcc

Object

@Must not be null

There are dcc data that have been send to our API

dcc.cardholderAmount

Number

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

The total transfer amount (in pennies) in cardholder dcc currency

dcc.cardholderCurrency

String

@Must not be null

Currency of cardholder card (in accordance with ISO-4217), example: USD

dcc.conversionRateCardholder

BigDecimal

@Must not be null

The rate used to convert the transaction amount to the cardholder billing amount

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is optional parameter. Without this parameter, transaction will be processed as a regular transaction without 3DS authorization.

outside3dsRequest.authenticationStatus

String

@must match Y or A or U, @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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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. More info.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

CoF Token Initial
POST /processor/payments/cof/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
  "requestUuid" : "722f93a7-51d1-4082-b5b0-ef23dcd18484",
  "amount" : 1000,
  "currency" : "PLN",
  "cardNumber" : "554422******4138", // token PAN
  "expiryDate" : "11/22",
  "autoClear" : true,
  "merchant" : {
  	"merchantId" : "4db50ee6-bcb4-43dd-8316-f5b38089bf0b",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
Table 71. CoF Initial request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

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) in transaction currency

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

Must be a number and length must be between 12 and 19"

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

cvc2

String

@Optional, @Length must be 3 characters

Cardholder’s card cvc2

autoClear

Boolean

True or false

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

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.

Response status
Status Description

200 OK

Returned when transaction was successfully authorized.

400 BAD REQUEST

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

401 UNAUTHORIZED

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

409 CONFLICT

STATUS: E001598 - Returned when transactionUUID already exists.

422 UNPROCESSABLE ENTITY

STATUS: E00158 - Returned when Cardholder Currency Indicator is invalid for DCC transaction.

STATUS: E001599 - Returned when card expiration date is invalid.

500 INTERNAL SERVER ERROR

STATUS: E00153 - Returned when transaction is declined, by problem with MIP connection.

STATUS: E001597 - Returned when transaction declined, processing timeout.

STATUS: E90000 - Returned when reason is unknown.

503 SERVICE UNAVAILABLE

STATUS: E90001 - Returned when is error acquirer connection.

STATUS: E90002 - Returned when is error mpi connection.

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

{
  "transactionUuid" : "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
  "requestUuid" : "722f93a7-51d1-4082-b5b0-ef23dcd18484",
  "cofInitialUuid" : "dcb92bf3-9e11-456a-ad01-a6a42605a753",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "007007614137",
  "stan" : "614137",
  "provider" : "MASTERCARD",
  "cardType" : "DMC",
  "defaultCurrency" : "PLN",
  "bankName": "BANK MILLENNIUM S.A.",
  "countryCardIssuing": "POL",
  "countryCodeNumeric": "616",
  "region": "EUROPE",
  "gcmsProductId": "MCG",
  "eeaDomesticRateQualificationIndicator": "Y",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Path Type Description

transactionUuid

String

Transaction’s unique uuid in system

requestUuid

String

Request’s unique uuid in system

cofInitialUuid

String

Cof Initial unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

bankName

String

Bank name only for Mastercard

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

gcmsProductId

String

Gcms product id only for Mastercard

This is the Product ID recognized by GCMS for the issuer account range and card program identifier combination. It may be different from the Licensed Product ID associated with the issuer account range and card program identifier combination.

eeaDomesticRateQualificationIndicator

String

EEA Domestic Rate Qualification Indicator only for Mastercard: Valid values:
Y = EEA Domestic Rate qualified
N = Not EEA Domestic Rate qualified

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

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

{
  "transactionUuid" : "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
  "requestUuid" : "722f93a7-51d1-4082-b5b0-ef23dcd18484",
  "cofInitialUuid" : "dcb92bf3-9e11-456a-ad01-a6a42605a753",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "007007614137",
  "stan" : "614137",
  "provider" : "VISA",
  "cardType" : "C",
  "defaultCurrency" : "USD",
  "countryCardIssuing": "US",
  "countryCodeNumeric": "840",
  "region": "1",
  "binType": "I",
  "domain": "W",
  "productId": "F",
  "settlementMatch": " ",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Table 72. Cof response fields
Path Type Description

transactionUuid

String

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

Request’s unique uuid in system

cofInitialUuid

String

Cof Initial unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

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: E80000
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, 12 Mar 2020 14:03:44 GMT
Connection: close
Content-Length: 265

{
  "errors": {
        "expiryDate": [
            "invalid card expiration date",
            "must not be blank",
            "must not be null"
        ],
        "transactionUuid": [
            "must not be null"
        ],
        "amount": [
            "must not be null"
        ],
        "sender": [
            "must not be null"
        ],
        "requestUuid": [
            "must not be null"
        ],
        "merchant": [
            "must not be null"
        ],
        "currency": [
            "must not be null"
        ],
        "cvc2": [
            "must not be blank",
            "must not be null"
        ],
        "cardNumber": [
            "must not be blank",
            "must not be null"
        ]
    },
  "status": "E80000",
  "httpStatus": "BAD_REQUEST",
  "traceId": "f77a09b4-86bb-4298-89ec-72c9cf754b95"
}
Table 73. Response fields Path
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/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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T07:17:31.968+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/processor/payments/cof/initial"
}
Table 74. Response fields
Path Type Description

timestamp

String

Time stamp

status

Number

Response code from Fenige system

error

String

Response http status

message

String

Message for response code from Fenige system

path

String

Path

409 Conflict
HTTP/1.1 409 Conflict
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "06396fa7-4281-40e2-970d-9894f91b5de6",
    "transactionUuid": "c3413be2-a66f-4437-945c-1b3a5258c857",
    "status": "E001598",
    "message": "Transaction rejected, transactionUUID already exists",
    "httpStatus": "CONFLICT",
    "traceId": "66cd08e1-9153-45be-9428-208f2e73ae99"
}
Table 75. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’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

traceId

String

Unique id for this http request register in system

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E00158
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00158",
    "message": "Returned when Cardholder Currency Indicator is invalid for DCC transaction.",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
Table 76. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "status": "E90000",
    "message": "Domain error",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "6b0249eb-9207-47fa-b50f-6eca28ea7e41"
}
HTTP Response - STATUS: E00153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E00153",
    "message": "Transaction declined, problem with MIP connection",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001597
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001597",
    "message": "Transaction declined, processing timeout",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
Table 77. Response fields
Path Type Description

requestUuid

String

Request unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "ERROR",
    "status": "E90001",
    "message": "Error acquirer connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "eb3eb56f-2e01-4211-ba34-654b5a5f2c31"
}
HTTP Response - STATUS: E90002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 267

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "ERROR",
    "status": "E90002",
    "message": "Error mpi connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "6675fab9-05a9-4158-b852-e5b15fe577ca"
}
Table 78. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

7.7.2. CoF Subsequent

Request
CoF Subsequent
POST /processor/payments/cof/subsequent HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "441ccd41-1b53-4a00-898c-ffb5874ad7d9",
  "requestUuid" : "d01f6e00-b848-4c7e-b822-f41292f40515",
  "cofInitialUuid" : "dcb92bf3-9e11-456a-ad01-a6a42605a753",
  "transactionInitiator" : "CIT",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "545313******4417",
  "expiryDate" : "11/22",
  "autoClear" : true,
  "merchant" : {
  	"merchantId" : "c1eaecc1-6a2b-45d0-bf23-71a22dd2f2f0",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "outside3dsRequest" : {
  	"authenticationStatus" : "Y",
  	"cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
  	"eci" : "02",
  	"authenticationTime" : "20180703 16:55:28",
  	"cavvAlgorithm" : "3",
  	"transactionxId" : "124"
  }
}
Table 79. Cof Subsequent request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

cofInitialUuid

String

@Must not be null

CoF Initial unique uuid in system

transactionInitiator

String

@Must not be null

Depends on CoF processing source selection may be MIT - merchant initiated or CIT - cardholder initiated.

For CIT - cardholder initiated type request can be processed using optional 3ds authentication, using authentication data provided in outside3dsRequest

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

Must be a number and length must be between 12 and 19

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

True or False

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

Must be the same as used in CoF initial

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is optional parameter for CIT subsequent transactions. only in case if 3DS authenticationStatus is Y or A, then transaction will be realized.

outside3dsRequest.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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

CoF DCC Subsequent
POST /processor/payments/cof/subsequent HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "441ccd41-1b53-4a00-898c-ffb5874ad7d9",
  "requestUuid" : "d01f6e00-b848-4c7e-b822-f41292f40515",
  "cofInitialUuid" : "dcb92bf3-9e11-456a-ad01-a6a42605a753",
  "transactionInitiator" : "MIT",
  "amount" : 1000,
  "currency" : "PLN",
  "cardNumber" : "545313******4417",
  "expiryDate" : "11/22",
  "autoClear" : true,
  "dcc":{
	"cardholderAmount" : 224,
	"cardholderCurrency" : "EUR",
	"conversionRateCardholder" : 0.2247541
  },
  "merchant" : {
  	"merchantId" : "c1eaecc1-6a2b-45d0-bf23-71a22dd2f2f0",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "outside3dsRequest" : {
  	"authenticationStatus" : "Y",
  	"cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
  	"eci" : "02",
  	"authenticationTime" : "20180703 16:55:28",
  	"cavvAlgorithm" : "3",
  	"transactionxId" : "124"
  }
}
Table 80. Cof Subsequent request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

cofInitialUuid

String

@Must not be null

CoF Initial unique uuid in system

transactionInitiator

String

@Must not be null

Depends on CoF processing source selection may be MIT - merchant initiated or CIT - cardholder initiated.

For CIT - cardholder initiated type request can be processed using optional 3ds authentication, using authentication data provided in outside3dsRequest

amount

Number

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

The total transfer amount (in pennies) in transaction currency

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

Must be a number and length must be between 12 and 19"

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

True or False

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

dcc

Object

@Must not be null

There are dcc data that have been send to our API

dcc.cardholderAmount

Number

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

The total transfer amount (in pennies) in cardholder dcc currency

dcc.cardholderCurrency

String

@Must not be null

Currency of cardholder card (in accordance with ISO-4217), example: USD

dcc.conversionRateCardholder

BigDecimal

@Must not be null

The rate used to convert the transaction amount to the cardholder billing amount

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is optional parameter for CIT subsequent transactions. only in case if 3DS authenticationStatus is Y or A, then transaction will be realized.

outside3dsRequest.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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

CoF Token Subsequent
POST /processor/payments/cof/subsequent HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "441ccd41-1b53-4a00-898c-ffb5874ad7d9",
  "requestUuid" : "d01f6e00-b848-4c7e-b822-f41292f40515",
  "cofInitialUuid" : "dcb92bf3-9e11-456a-ad01-a6a42605a753",
  "transactionInitiator" : "MIT",
  "amount" : 1000,
  "currency" : "PLN",
  "cardNumber" : "554422******4138",
  "expiryDate" : "11/22",
  "autoClear" : true,
  "merchant" : {
  	"merchantId" : "c1eaecc1-6a2b-45d0-bf23-71a22dd2f2f0",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
Table 81. Cof Subsequent request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

cofInitialUuid

String

@Must not be null

CoF Initial unique uuid in system

transactionInitiator

String

@Must not be null

Depends on CoF processing source selection may be MIT - merchant initiated or CIT - cardholder initiated.

For CIT - cardholder initiated type request can be processed using optional 3ds authentication, using authentication data provided in outside3dsRequest

amount

Number

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

The total transfer amount (in pennies) in transaction currency

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

Must be a number and length must be between 12 and 19"

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

True or False

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

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

Response status
Status Description

200 OK

Returned when transaction was successfully authorized.

400 BAD REQUEST

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

401 UNAUTHORIZED

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

409 CONFLICT

STATUS: E001598 - Returned when transactionUUID already exists.

422 UNPROCESSABLE ENTITY

STATUS: E00158 - Returned when Cardholder Currency Indicator is invalid for DCC transaction.

STATUS: E001599 - Returned when card expiration date is invalid.

STATUS: E001591 - Returned when merchantId from CoF subsequent is not the same as in initial.

500 INTERNAL SERVER ERROR

STATUS: E00153 - Returned when transaction is declined, by problem with MIP connection.

STATUS: E001597 - Returned when transaction declined, processing timeout.

STATUS: E90000 - Returned when reason is unknown.

503 SERVICE UNAVAILABLE

STATUS: E90001 - Returned when is error acquirer connection.

STATUS: E90002 - Returned when is error mpi connection.

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

{
  "transactionUuid" : "a441ccd41-1b53-4a00-898c-ffb5874ad7d9",
  "requestUuid" : "d01f6e00-b848-4c7e-b822-f41292f40515",
  "cofInitialUuid" : "82d5cb00-6435-4428-b8b2-d3c3b3a71936",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "007007614137",
  "stan" : "614137",
  "provider" : "MASTERCARD",
  "cardType" : "DMC",
  "defaultCurrency" : "PLN",
  "bankName": "BANK MILLENNIUM S.A.",
  "countryCardIssuing": "POL",
  "countryCodeNumeric": "616",
  "region": "EUROPE",
  "gcmsProductId": "MCG",
  "eeaDomesticRateQualificationIndicator": "Y",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Path Type Description

transactionUuid

String

Transaction’s unique uuid in system

requestUuid

String

Request’s unique uuid in system

cofInitialUuid

String

Cof Initial unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

bankName

String

Bank name only for Mastercard

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

gcmsProductId

String

Gcms product id only for Mastercard

This is the Product ID recognized by GCMS for the issuer account range and card program identifier combination. It may be different from the Licensed Product ID associated with the issuer account range and card program identifier combination.

eeaDomesticRateQualificationIndicator

String

EEA Domestic Rate Qualification Indicator only for Mastercard: Valid values:
Y = EEA Domestic Rate qualified
N = Not EEA Domestic Rate qualified

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

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

{
  "transactionUuid" : "a441ccd41-1b53-4a00-898c-ffb5874ad7d9",
  "requestUuid" : "d01f6e00-b848-4c7e-b822-f41292f40515",
  "cofInitialUuid" : "82d5cb00-6435-4428-b8b2-d3c3b3a71936",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "007007614137",
  "stan" : "614137",
  "provider" : "VISA",
  "cardType" : "D",
  "defaultCurrency" : "USD",
  "countryCardIssuing": "US",
  "countryCodeNumeric": "840",
  "region": "1",
  "binType": "I",
  "domain": "W",
  "productId": "F",
  "settlementMatch": " ",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Table 82. Cof Subsequent response fields
Path Type Description

transactionUuid

String

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

Request’s unique uuid in system

cofInitialUuid

String

Cof Initial unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

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: E80000
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, 12 Mar 2020 14:03:44 GMT
Connection: close
Content-Length: 265

{
    "errors": {
        "expiryDate": [
            "must not be null",
            "must not be blank",
            "invalid card expiration date"
        ],
        "transactionUuid": [
            "must not be null"
        ],
        "amount": [
            "must not be null"
        ],
        "sender": [
            "must not be null"
        ],
        "requestUuid": [
            "must not be null"
        ],
        "merchant": [
            "must not be null"
        ],
        "currency": [
            "must not be null"
        ],
        "cardNumber": [
            "must not be null",
            "must not be blank"
        ],
        "cofInitialUuid": [
            "must not be null"
        ]
    },
    "status": "E80000",
    "httpStatus": "BAD_REQUEST",
    "traceId": "4291a1fd-03d8-48d5-a773-7fd32c661b12"
}
Table 83. Response fields Path
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/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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T07:17:31.968+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/processor/payments/cof/subsequent"
}
Table 84. Response fields
Path Type Description

timestamp

String

Time stamp

status

Number

Response code from Fenige system

error

String

Response http status

message

String

Message for response code from Fenige system

path

String

Path

409 Conflict
HTTP/1.1 409 Conflict
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "06396fa7-4281-40e2-970d-9894f91b5de6",
    "transactionUuid": "c3413be2-a66f-4437-945c-1b3a5258c857",
    "status": "E001598",
    "message": "Transaction rejected, transactionUUID already exists",
    "httpStatus": "CONFLICT",
    "traceId": "66cd08e1-9153-45be-9428-208f2e73ae99"
}
Table 85. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’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

traceId

String

Unique id for this http request register in system

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E00157
HTTP/1.1 422 Unprocessable entity
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, 6 Dec 2021 11:43:57 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00157",
    "message": "Transaction rejected, transactionInitiator type not allowed for transaction",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
HTTP Response - STATUS: E00158
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00158",
    "message": "Returned when Cardholder Currency Indicator is invalid for DCC transaction.",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
HTTP Response - STATUS: E00159
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00159",
    "message": "Transaction rejected, initial CoF transaction not approved/exist",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
HTTP Response - STATUS: E001591
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "REJECTED",
    "status": "E001591",
    "message": "Transaction rejected, invalid initial CoF merchantId",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
Table 86. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "status": "E90000",
    "message": "Domain error",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "6b0249eb-9207-47fa-b50f-6eca28ea7e41"
}
HTTP Response - STATUS: E00153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "d01f6e00-b848-4c7e-b822-f41292f40515",
    "transactionUuid": "441ccd41-1b53-4a00-898c-ffb5874ad7d9",
    "transactionStatus": "DECLINED",
    "status": "E00153",
    "message": "Transaction declined, problem with MIP connection",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001597
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001597",
    "message": "Transaction declined, processing timeout",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
Table 87. Response fields
Path Type Description

requestUuid

String

Request unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "requestUuid": "d01f6e00-b848-4c7e-b822-f41292f40515",
    "transactionUuid": "441ccd41-1b53-4a00-898c-ffb5874ad7d9",
    "transactionStatus": "ERROR",
    "status": "E90001",
    "message": "Error acquirer connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "b8225c58-ca26-43e3-9d62-735979721abb"
}
HTTP Response - STATUS: E90002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 267

{
    "requestUuid": "d01f6e00-b848-4c7e-b822-f41292f40515",
    "transactionUuid": "441ccd41-1b53-4a00-898c-ffb5874ad7d9",
    "transactionStatus": "ERROR",
    "status": "E90002",
    "message": "Error mpi connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "6675fab9-05a9-4158-b852-e5b15fe577ca"
}
Table 88. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

7.8. Recurring payment

Recurring Initial transaction must always be done with 3DS authorization. On the Acquirer side there is the logic of processing Recurring transactions - periodical
subsequent calling and remembering the card number and expiry date which is necessary to proceed subsequent transaction which no longer requires CVC or 3ds.
Payment with DCC (Dynamic Currency Conversion) transaction is a dynamic transaction amount conversion service available at payment terminals, enabling payment in the
currency of the country where the credit card was issued.
The difference between DCC payment and standard payment is on the side of the Acquirer, who must check the card's currencies and present them on request. The client chooses
from the available currencies (or the default currency is automatically selected). Then Acquirer performs a currency conversion on its side to the chosen currency and sends to FENIGE a request with a dcc object in which it places the converted amount in the currency chosen by the Client.

Since 16 May, Fenige has enabled the initialisation and processing of recurring transactions back to back with tokenised cards. An additional confirmation of authentication is provided by cryptographic data from mobile applications, which can be optionally provided in the paymentData object similar to the 7.6 Token Payment method.

Recurring payment
recurring payment request
Recurring DCC payment
recurring dcc payment request

7.8.1. Recurring Initial

Request
Recurring Initial
POST /processor/payments/recurring/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "03df773b-b9cf-44e6-bb02-392874ec12d0",
  "requestUuid" : "b8d59b30-a8a4-4524-9089-4844ed383605",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "545313******4417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "autoClear" : true,
  "merchant" : {
  	"merchantId" : "7828472b-ca22-47b8-b994-a628415d8b69",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "outside3dsRequest" : {
  	"authenticationStatus" : "Y",
  	"cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
  	"eci" : "02",
  	"authenticationTime" : "20180703 16:55:28",
  	"cavvAlgorithm" : "3",
  	"transactionxId" : "124"
  }
}
Table 89. Recurring Initial request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

amount

Number

@Must not be null

The total transfer amount (in pennies). If the amount is equal to zero there is sent account status inquiry to validate aspects of a cardholder account.

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

Must be a number and length must be between 12 and 19"

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

autoClear

Boolean

true or false

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is a required parameter. only in case if 3DS authenticationStatus is Y or A, then transaction will be realized.

outside3dsRequest.authenticationStatus

String

@must match Y or A or U, @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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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. More info.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

Recurring DCC Initial
POST /processor/payments/recurring/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "03df773b-b9cf-44e6-bb02-392874ec12d0",
  "requestUuid" : "b8d59b30-a8a4-4524-9089-4844ed383605",
  "amount" : 1000,
  "currency" : "PLN",
  "cardNumber" : "545313******4417",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "autoClear" : true,
  "dcc":{
	"cardholderAmount" : 224,
	"cardholderCurrency" : "EUR",
	"conversionRateCardholder" : 0.2247541
  },
  "merchant" : {
  	"merchantId" : "7828472b-ca22-47b8-b994-a628415d8b69",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "outside3dsRequest" : {
  	"authenticationStatus" : "Y",
  	"cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
  	"eci" : "02",
  	"authenticationTime" : "20180703 16:55:28",
  	"cavvAlgorithm" : "3",
  	"transactionxId" : "124"
  }
}
Table 90. Recurring Initial request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

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) in transaction currency

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

Must be a number and length must be between 12 and 19"

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

autoClear

Boolean

True or False

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

dcc

Object

@Must not be null

There are dcc data that have been send to our API

dcc.cardholderAmount

Number

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

The total transfer amount (in pennies) in cardholder dcc currency

dcc.cardholderCurrency

String

@Must not be null

Currency of cardholder card (in accordance with ISO-4217), example: USD

dcc.conversionRateCardholder

BigDecimal

@Must not be null

The rate used to convert the transaction amount to the cardholder billing amount

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is a required parameter. only in case if 3DS authenticationStatus is Y or A, then transaction will be realized.

outside3dsRequest.authenticationStatus

String

@must match Y or A or U, @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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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. More info.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

Recurring Token Initial
POST /processor/payments/recurring/initial HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "03df773b-b9cf-44e6-bb02-392874ec12d0",
  "requestUuid" : "b8d59b30-a8a4-4524-9089-4844ed383605",
  "amount" : 1000,
  "currency" : "PLN",
  "cardNumber" : "554422******4138",
  "expiryDate" : "11/22",
  "cvc2" : "123",
  "autoClear" : true,
  "merchant" : {
  	"merchantId" : "7828472b-ca22-47b8-b994-a628415d8b69",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
Table 91. Recurring Initial request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

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) in transaction currency

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

Must be a number and length must be between 12 and 19"

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

autoClear

Boolean

True or False

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

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.

Response status
Status Description

200 OK

Returned when transaction was successfully authorized.

400 BAD REQUEST

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

401 UNAUTHORIZED

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

409 CONFLICT

STATUS: E001598 - Returned when transactionUUID already exists.

422 UNPROCESSABLE ENTITY

STATUS: E00156 - Transaction rejected, initial recurring transaction not approved/exist

STATUS: E00158 - Returned when Cardholder Currency Indicator is invalid for DCC transaction.

STATUS: E001599 - Returned when card expiration date is invalid.

500 INTERNAL SERVER ERROR

STATUS: E00153 - Returned when transaction is declined, by problem with MIP connection.

STATUS: E001597 - Returned when transaction declined, processing timeout.

STATUS: E90000 - Returned when reason is unknown.

503 SERVICE UNAVAILABLE

STATUS: E90001 - Returned when is error acquirer connection.

STATUS: E90002 - Returned when is error mpi connection.

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

{
  "transactionUuid" : "03df773b-b9cf-44e6-bb02-392874ec12d0",
  "requestUuid" : "b8d59b30-a8a4-4524-9089-4844ed383605",
  "recurringInitialUuid" : "9ec99f88-800b-4107-94d8-44ea9560ac58",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "007007614137",
  "stan" : "614137",
  "provider" : "MASTERCARD",
  "cardType" : "DMC",
  "defaultCurrency" : "PLN",
  "bankName": "BANK MILLENNIUM S.A.",
  "countryCardIssuing": "POL",
  "countryCodeNumeric": "616",
  "region": "EUROPE",
  "gcmsProductId": "MCG",
  "eeaDomesticRateQualificationIndicator": "Y",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Table 92. Recurring Initial response fields
Path Type Description

transactionUuid

String

Transaction’s unique uuid in system

requestUuid

String

Request’s unique uuid in system

recurringInitialUuid

String

Recurring Initial unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

bankName

String

Bank name only for Mastercard

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

gcmsProductId

String

Gcms product id only for Mastercard

This is the Product ID recognized by GCMS for the issuer account range and card program identifier combination. It may be different from the Licensed Product ID associated with the issuer account range and card program identifier combination.

eeaDomesticRateQualificationIndicator

String

EEA Domestic Rate Qualification Indicator only for Mastercard: Valid values:
Y = EEA Domestic Rate qualified
N = Not EEA Domestic Rate qualified

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

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

{
  "transactionUuid" : "03df773b-b9cf-44e6-bb02-392874ec12d0",
  "requestUuid" : "b8d59b30-a8a4-4524-9089-4844ed383605",
  "recurringInitialUuid" : "9ec99f88-800b-4107-94d8-44ea9560ac58",
  "transactionStatus" : "APPROVED",
  "responseCode" : "CODE_00",
  "rrn" : "007007614137",
  "stan" : "614137",
  "provider" : "VISA",
  "cardType" : "C",
  "defaultCurrency" : "USD",
  "countryCardIssuing": "US",
  "countryCodeNumeric": "840",
  "region": "1",
  "binType": "I",
  "domain": "W",
  "productId": "F",
  "settlementMatch": " ",
  "status" : "S00002",
  "message" : "Success transaction",
  "httpStatus" : "OK"
}
Table 93. Authorize response fields
Path Type Description

transactionUuid

String

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

Request’s unique uuid in system

recurringInitialUuid

String

Recurring Initial unique uuid in system

transactionStatus

String

Transaction status

responseCode

String

Response code

rrn

String

Retrieval Reference Number

stan

String

System Trace Audit Number (STAN)

provider

String

Card’s provider

cardType

String

Card type for Mastercard:

MCC - Credit Mastercard
DMC - Debit Mastercard
MSI - Maestro
CIR - Cirrus
PVL - Private Label

Card type for Visa:

C - Credit
D - Debit
P - Prepaid
H - Charge
R – Deferred Debit
Space – Not applicable

defaultCurrency

String

Default card currency

countryCardIssuing

String

Country card Issuing for Mastercard: - ISO 3166-1 Alpha-3

Country card Issuing for Visa: - ISO 3166-1 Alpha-2

countryCodeNumeric

String

Country code numeric for Mastercard:
- ISO 3166-1 Numeric

Country code numeric for Visa:
- ISO 3166-1 Numeric

region

String

Region for Mastercard:

- UNITED_STATES
- CANADA
- LATINA_AMERICA_AND_THE_CARIBBEAN
- ASIA_PACIFIC
- EUROPE
- SOUTH_ASIA_MIDDLE_EAST_AFRICA
- ANY

Region for Visa:

1 = US
2 = Canada
3 = Visa Europe
4 = Asia-Pacific
5 = Latin America and Carribean
6 = CEMEA

binType

String

Bin type only for VISA

F = Full Service
I = Issuer Only
M = Merchant Only
N = Nonfinancial
O = On Behalf Of (OBO)
P = Processor
S = SMS Financial entity
V = Visa Internal entity

domain

String

Domain only for VISA:

W = (Worldwide)
R = (Regional)
N = (National)
D = (Domestic)

productId

String

Product ID only for VISA.

This field contains the Product ID values:
A - Visa Traditional, AX - American Express, B - Visa Traditional Rewards, C - Visa Signature, D - Visa Signature Preferred, DI - Discover, DN - Diners, E - Proprietary ATM, F - Visa Classic, G - Visa Business, G1 - Visa Signature Business, G3 - Visa Business Enhanced, G4 - Visa Infinite Business, G5 - Visa Business Rewards, I - Visa Infinite, I1 - Visa Infinite Privilege, I2 - Ultra High Net Worth, J3 - Visa Healthcare, JC - JCB, K - Visa Corporate T&E, K1 - Visa Government Corporate T&E, L - Electron, M - Mastercard, N - Visa Platinum, N1 - Visa Rewards, N2 - Visa Select, P - Visa Gold, Q - Private Label, Q2 - Private Label Basic, Q3 - Private Label Standard, Q4 - Private Label Enhanced, Q5 - Private Label Specialized, Q6 - Private Label Premium, R - Proprietary, S - Visa Purchasing, S1 - Visa Purchasing with Fleet, S2 - Visa Government Purchasing, S3 - Visa Government Purchasing with Fleet, S4 - Commercial Agriculture, S5 - Commercial Transport, S6 - Commercial Marketplace, U - Visa TravelMoney, V - V PAY, X - Visa B2B Virtual Payments

settlementMatch

String

Settlement match only for VISA:

B = (B2B)
E = B2E
Space = (Not applicable)

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: E80000
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, 12 Mar 2020 14:03:44 GMT
Connection: close
Content-Length: 265

{
    "errors": {
        "expiryDate": [
            "must not be null",
            "must not be blank",
            "invalid card expiration date"
        ],
        "transactionUuid": [
            "must not be null"
        ],
        "amount": [
            "must not be null"
        ],
        "outside3dsRequest": [
            "must not be null"
        ],
        "sender": [
            "must not be null"
        ],
        "requestUuid": [
            "must not be null"
        ],
        "merchant": [
            "must not be null"
        ],
        "currency": [
            "must not be null"
        ],
        "cvc2": [
            "must not be blank",
            "must not be null"
        ],
        "cardNumber": [
            "must not be null",
            "must not be blank"
        ]
    },
    "status": "E80000",
    "httpStatus": "BAD_REQUEST",
    "traceId": "50bf37c3-3562-4364-8b30-f51c31bdec6b"
}
Table 94. Response fields Path
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/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, 12 Mar 2020 14:03:26 GMT

{
    "timestamp": "2020-06-01T07:17:31.968+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/processor/payments/recurring/initial"
}
Table 95. Response fields
Path Type Description

timestamp

String

Time stamp

status

Number

Response code from Fenige system

error

String

Response http status

message

String

Message for response code from Fenige system

path

String

Path

409 Conflict
HTTP/1.1 409 Conflict
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "06396fa7-4281-40e2-970d-9894f91b5de6",
    "transactionUuid": "c3413be2-a66f-4437-945c-1b3a5258c857",
    "status": "E001598",
    "message": "Transaction rejected, transactionUUID already exists",
    "httpStatus": "CONFLICT",
    "traceId": "66cd08e1-9153-45be-9428-208f2e73ae99"
}
Table 96. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’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

traceId

String

Unique id for this http request register in system

422 UNPROCESSABLE ENTITY
HTTP Response - STATUS: E00158
HTTP/1.1 422 Unprocessable entity
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, 12 Mar 2020 14:03:26 GMT

{
    "requestUuid": "aa23f94e-1dc4-468c-876d-dee3588daba9",
    "transactionUuid": "3a4b276a-84e9-4f5d-82e9-e20d8936c2c8",
    "status": "E00158",
    "message": "Returned when Cardholder Currency Indicator is invalid for DCC transaction.",
    "httpStatus": "UNPROCESSABLE_ENTITY",
    "traceId": "7fd9be06-e12c-4abd-943b-52fb1d3735cf"
}
Table 97. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "status": "E90000",
    "message": "Domain error",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "8907eafd-92fb-4c8a-abb3-e4420aed8c98"
}
HTTP Response - STATUS: E00153
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "b8d59b30-a8a4-4524-9089-4844ed383605",
    "transactionUuid": "03df773b-b9cf-44e6-bb02-392874ec12d0",
    "transactionStatus": "DECLINED",
    "status": "E00153",
    "message": "Transaction declined, problem with MIP connection",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
HTTP Response - STATUS: E001597
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 167

{
    "requestUuid": "722f93a7-51d1-4082-b5b0-ef23dcd18484",
    "transactionUuid": "ab19f70c-d4ef-4e9b-bf5f-05d0fee80eb2",
    "transactionStatus": "DECLINED",
    "status": "E001597",
    "message": "Transaction declined, processing timeout",
    "httpStatus": "INTERNAL_SERVER_ERROR",
    "traceId": "eb0c1c67-f692-4d43-aa1e-013ad0490f6a"
}
Table 98. Response fields
Path Type Description

requestUuid

String

Request unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

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

{
    "requestUuid": "b8d59b30-a8a4-4524-9089-4844ed383605",
    "transactionUuid": "03df773b-b9cf-44e6-bb02-392874ec12d0",
    "transactionStatus": "ERROR",
    "status": "E90001",
    "message": "Error acquirer connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "078fb9bc-e6c9-4f69-a48f-3ac7ed3153f0"
}
HTTP Response - STATUS: E90002
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Content-Length: 267

{
    "requestUuid": "b8d59b30-a8a4-4524-9089-4844ed383605",
    "transactionUuid": "03df773b-b9cf-44e6-bb02-392874ec12d0",
    "transactionStatus": "ERROR",
    "status": "E90002",
    "message": "Error mpi connection",
    "httpStatus": "SERVICE_UNAVAILABLE",
    "traceId": "6675fab9-05a9-4158-b852-e5b15fe577ca"
}
Table 99. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String

Transaction’s 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

traceId

String

Unique id for this http request register in system

7.8.2. Recurring Subsequent

Request
Recurring Subsequent
POST /processor/payments/recurring/subsequent HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "416888ac-56ba-4fcd-8029-d0317dad53cb",
  "requestUuid" : "32eebb90-8955-49c6-b667-f58488533b13",
  "recurringInitialUuid" : "9ec99f88-800b-4107-94d8-44ea9560ac58",
  "transactionInitiator" : "RECURRING_PAYMENT",
  "amount" : 1000,
  "currency" : "USD",
  "cardNumber" : "545313******4417",
  "expiryDate" : "11/22",
  "autoClear" : true,
  "merchant" : {
  	"merchantId" : "b0e8304d-e58e-4f18-8876-9e6b5ad848f7",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "outside3dsRequest" : {
  	"authenticationStatus" : "Y",
  	"cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
  	"eci" : "02",
  	"authenticationTime" : "20180703 16:55:28",
  	"cavvAlgorithm" : "3",
  	"transactionxId" : "124"
  }
}
Table 100. Recurring Subsequent request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

recurringInitialUuid

String

Recurring Initial unique uuid in system

transactionInitiator

String

@Must not be null

Depends on recurring processing source selection may be MIT - merchant initiated or RECURRING_PAYMENT - recurring payment.

For RECURRING_PAYMENT - request can be processed using optional 3ds authentication, using authentication data provided in outside3dsRequest

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

Must be a number and length must be between 12 and 19"

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

True or False

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

Must be the same as used in recurring initial

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is optional parameter for CIT subsequent transactions. only in case if 3DS authenticationStatus is Y or A, then transaction will be realized.

outside3dsRequest.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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

Recurring DCC Subsequent
POST /processor/payments/recurring/subsequent HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "416888ac-56ba-4fcd-8029-d0317dad53cb",
  "requestUuid" : "32eebb90-8955-49c6-b667-f58488533b13",
  "recurringInitialUuid" : "9ec99f88-800b-4107-94d8-44ea9560ac58",
  "transactionInitiator" : "RECURRING_PAYMENT",
  "amount" : 1000,
  "currency" : "PLN",
  "cardNumber" : "545313******4417",
  "expiryDate" : "11/22",
  "autoClear" : true,
  "dcc":{
	"cardholderAmount" : 224,
	"cardholderCurrency" : "EUR",
	"conversionRateCardholder" : 0.2247541
  },
  "merchant" : {
  	"merchantId" : "b0e8304d-e58e-4f18-8876-9e6b5ad848f7",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "outside3dsRequest" : {
  	"authenticationStatus" : "Y",
  	"cavv" : "jEu04WZns7pbARAApU4qgNdJTag=",
  	"eci" : "02",
  	"authenticationTime" : "20180703 16:55:28",
  	"cavvAlgorithm" : "3",
  	"transactionxId" : "124"
  }
}
Table 101. Recurring Subsequent request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

recurringInitialUuid

String

Recurring Initial unique uuid in system

transactionInitiator

String

@Must not be null

Depends on recurring processing source selection may be MIT - merchant initiated or RECURRING_PAYMENT - recurring payment.

For RECURRING_PAYMENT - request can be processed using optional 3ds authentication, using authentication data provided in outside3dsRequest

amount

Number

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

The total transfer amount (in pennies) in transaction currency

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

Must be a number and length must be between 12 and 19"

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

True or False

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

dcc

Object

@Must not be null

There are dcc data that have been send to our API

dcc.cardholderAmount

Number

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

The total transfer amount (in pennies) in cardholder dcc currency

dcc.cardholderCurrency

String

@Must not be null

Currency of cardholder card (in accordance with ISO-4217), example: USD

dcc.conversionRateCardholder

BigDecimal

@Must not be null

The rate used to convert the transaction amount to the cardholder billing amount

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

Must be the same as used in recurring initial

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

outside3dsRequest

Object

There are outside 3ds data authorization that have been send to our API. This is optional parameter for CIT subsequent transactions. only in case if 3DS authenticationStatus is Y or A, then transaction will be realized.

outside3dsRequest.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.

outside3dsRequest.cavv

String

@Must match the regular expression ^[j,h]{1}[\w,=]+$, @Size must be between 0 and 28 inclusive

Cardholder Authentication Verification Value

outside3dsRequest.eci

String

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

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.

outside3dsRequest.authenticationTime

String

@Must be not null

Authentication date

outside3dsRequest.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

outside3dsRequest.transactionxId

String

This field is required for 3DS 2.X, optional for 3DS 1.0

Recurring Token Subsequent
POST /processor/payments/recurring/subsequent HTTP/1.1
Content-Type: application/json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Content-Length: 373
Host: processor-staging.fenige.pl

{
  "transactionUuid" : "416888ac-56ba-4fcd-8029-d0317dad53cb",
  "requestUuid" : "32eebb90-8955-49c6-b667-f58488533b13",
  "recurringInitialUuid" : "9ec99f88-800b-4107-94d8-44ea9560ac58",
  "transactionInitiator" : "RECURRING_PAYMENT",
  "amount" : 1000,
  "currency" : "PLN",
  "cardNumber" : "554422******4138",
  "expiryDate" : "11/22",
  "autoClear" : true,
  "merchant" : {
  	"merchantId" : "b0e8304d-e58e-4f18-8876-9e6b5ad848f7",
  	"companyName" : "Company Name",
  	"city" : "Lublin",
  	"country" : "PL",
  	"homeNumber" : "10",
  	"street" : "Merchant street",
  	"streetNumber" : "11",
  	"postalCode" : "24-110"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
Table 102. Recurring Subsequent request fields
Path Type Constraints Description

transactionUuid

String

@Must not be null

Unique transaction uuid which, together with the merchantId, identifies transactions

requestUuid

String

@Must not be null

Request’s unique uuid in system

recurringInitialUuid

String

Recurring Initial unique uuid in system

transactionInitiator

String

@Must not be null

Depends on recurring processing source selection may be MIT - merchant initiated or RECURRING_PAYMENT - recurring payment.

For RECURRING_PAYMENT - request can be processed using optional 3ds authentication, using authentication data provided in outside3dsRequest

amount

Number

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

The total transfer amount (in pennies) in transaction currency

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

Must be a number and length must be between 12 and 19"

expiryDate

String

@Must not be blank, @Must not be null

Expiration date of card mm/yy

autoClear

Boolean

True or False

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

merchant

Object

@Must not be null

There are merchant data that have been send to our API

merchant.merchantId

String

@Must not be null

Merchant’s unique uuid in system

Must be the same as used in recurring initial

merchant.companyName

String

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

The merchant’s name sent in the messages to MC and Visa

merchant.city

String

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

The merchant’s city

merchant.country

String

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

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

merchant.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

merchant.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

merchant.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

merchant.postalCode

String

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

The merchant’s postal code

terminal

Object

@Must not be null

There are terminal data that have been send to our API

terminal.terminalId

String

@Must match alphanumeric format ^[a-zA-Z0-9]+, @Length must be min 4 max 8 inclusive

Card Acceptor Terminal ID uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS systems

terminal.terminalUrl

String

@Length must be max 150

Terminal website URL

terminal.mcc

String

@Must match number format ^\\d+$, @Length must be 4 inclusive

MCC according to current ISO 18245 that have been send to our API

sender

Object

@Optional

There are sender data that have been send to our API

sender.firstName

String

@Optional field, @Length must be between 1 and 12, @Must match the regular expression [0-9]+$

First name of card holder

sender.lastName

String

@Optional field, @Length must be between 1 and 20, @Must match the regular expression [0-9]+$

Last name of card holder

sender.email

String

Optional field, @Length(min = 1, max = 128), @Must match the regular expression ^\s*?(.)@(.?)\.(.+?)\s*$

Cardholder’s email

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

Response status
Status Description

200 OK

Returned when transaction was successfully authorized.

400 BAD REQUEST

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

401 UNAUTHORIZED

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

409 CONFLICT

STATUS: E001598 - Returned when transactionUUID already exists.

422 UNPROCESSABLE ENTITY

STATUS: E00156 - Transaction rejected, initial recurring transaction not approved/exist

STATUS: E001561 - Returned when merchantId from recurring initial is not the same as in subsequent.

STATUS: E00158 - Returned when Cardholder Currency Indicator is invalid for DCC transaction.

STATUS: E001599 - Returned when card expiration date is invalid.

500 INTERNAL SERVER ERROR

STATUS: E00153 - Returned when transaction is declined, by problem with MIP connection.

STATUS: E001597 - Returned when transaction declined, processing timeout.

STATUS: E90000 - Returned when reason is unknown.

503 SERVICE UNAVAILABLE

STATUS: E90001 - Returned when is error acquirer connection.

STATUS: E90002 - Returned when is error mpi connection.

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

{
  "transactionUuid" : "416888ac-56ba-4fcd-8029-d0317dad53cb",
  "requestUuid" : "32eebb90-8955-49c6-b667-f58488533b13",
  "recurringInitialUuid" : "9ec99f88-800b-4107-94d8-44ea9560ac58",