1. Changelog

Version Date Description

1.50

2024-01-20

Add new response status E001602 Transaction rejected, initial uuid already exists for cofInitial and recurringInitial

1.49

2024-01-15

An additional token payment request authorization optional field was added to reflect the token type used (GooglePay, ApplePay, etc.). Read more Token payment paymentData.walletIdentifier]

1.48

2024-01-15

Extension of the reversal method to provide a partial amount - partial reversal before clearing. Removal of the status - E00162 - Payment is already reversed because give the possibility of multiple reversals. Reversal]

Add information about partial reversal in /payments/query method, adding history of partial reversals of transactions. Details]

1.47

2024-01-10

Added validation that forbids provide UNDEFINED currency to /currency-rate method

1.46

2023-09-13

Add external trace id

1.45

2023-09-10

Added fields needed for a transaction, when it will be realized with specific interchange fee for merchant, indicated that terminal is registered in network program in Visa or Mastercard.

1.44

2023-08-29

Add new values for terminalPanEntryMode in the request.

1.43

2023-03-29

Adaptation to the mandatory amendment of AN 6022.

1.42

2022-10-31

Add field terminalPanEntryMode in the request.

1.41

2022-10-26

New report - TC 33 CAS has been added. More information in Reports section.

1.40

2022-05-16

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

1.39

2022-04-13

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

1.38

2022-03-31

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

1.37

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

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

2022-03-01

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

1.34

2021-12-27

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

1.33

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

2021-12-06

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

1.31

2021-10-25

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

1.30

2021-10-18

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

1.29

2021-08-23

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

1.28

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

2021-07-22

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

1.26

2021-06-24

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

1.25

2021-06-24

Added a new payment method Token payment.

1.24

2021-05-04

New file 'Clearing Detail File' report introduced.

1.23

2021-03-10

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

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

2021-01-21

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

1.20

2021-01-19

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

1.19

2021-01-18

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

1.18

2020-11-06

Added new columns to the Interchange report.

1.17

2020-11-05

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

1.16

2020-10-14

Added new VISA response code value 80.

1.15

2020-10-09

Added Mastercard Currency Update report.

1.14

2020-10-08

Added 3DS 2.X API methods.

1.13

2020-10-07

MO/TO DCC payment status E00158 added.

1.12

2020-09-20

Added Installment Payment API methods.

1.11

2020-09-14

Added MO/TO payment.

1.10

2020-09-09

Added Mastercard Settlement Position Details report.

1.9

2020-08-31

Added Mastercard reports txt example.

1.8

2020-07-27

Added VISA reports csv example.

1.7

2020-07-10

Added MasterCard reports csv example.

1.6

2020-07-06

Update diagrams.

1.5

2020-07-01

New method "Card Provider" added.

1.4

2020-06-30

Update VISA reports.

1.3

2020-06-30

Update MasterCard statuses table.

1.2

2020-06-16

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

1.1

2020-06-01

DCC Payment method description changed.

1.0

2020-05-25

First release of API Processor documentation.

1.1. Product Announcements

1.1.1. Adaptation to the mandatory amendment of AN 6022

Date on Staging

2023-03-29

Date on Production

2023-06-06

Source of changes

Mandate AN6022

What was change

  • Authentication

  • Authorization

  • Clearing

  • Reporting

  • API

Scope of changes

We added new fields on API endpoints: 6.4., 6.5., 6.6., 6.7., 6.8., 6.9.:

  • merchant.subdivision

  • merchant.taxId

  • merchant.partnershipAgreement

  • merchant.contactPhoneNumber

  • merchant.supportPhoneNumber

  • merchant.serviceCity

  • merchant.serviceCountry

  • merchant.servicePostalCode

  • merchant.serviceSubdivision

All fields are optional on API but Mastercard require fields:

  • merchant.subdivision

  • merchant.contactPhoneNumber

  • merchant.supportPhoneNumber

We will also start sending DE48 SE22 SF006

Fields When You should use that field Should I do something? How we will use that field Authorization Clearing

merchant.subdivision

Based on Mastercard documentation always.

Change on integration

We will not send if filed is null.

DE122 SE001 SF002

DE43 SF005

merchant.taxId

Field is conditional. Based on Mastercard infotmation, it is required when local law require that field.

no

We will send zeros + N if field is null.

DE122 SE001 SF007

n/a

merchant.partnershipAgreement

Only if Mastercard has relation with merchant.

no

We will not send if filed is null.

DE122 SE001 SF008

n\a

  • merchant.contactPhoneNumber

  • merchant.supportPhoneNumber

Based on Mastercard documentation always.

Send Us a decision what should be default value.

We will send default acquirer number or zeros (depends on Your decision) if fields is null.

  • DE122 SE001 SF004

  • DE122 SE001 SF005

PDS0170

  • merchant.serviceCity

  • merchant.serviceCountry

  • merchant.servicePostalCode

  • merchant.serviceSubdivision

Based on Mastercard documentation required for eCommerce for this cases:

  • e-commerce: electric vehicle charging or fuel purchase then service location should be Location of the charging station or refueling station.

  • e-commerce: In-store pickup then service location should be Merchant store location: The location of the merchant store.

no

We will not send if filed is null.

  • DE122 SE001 SF009

  • DE122 SE001 SF010

  • DE122 SE001 SF011

  • DE122 SE001 SF012

no changes

  • merchant.street

  • merchant.streetNumber

  • merchant.homeNumber

no changes

no changes

We will change DE in which we send that fields.

DE122 SE001 SF001

PDS0216

Timelines
From Procesing Mastercard

2023-03-29

We can consume new fields on Stage

2023-04-05

We can consume new fields on Production but we do not send that data to Masteracrd

2023-04-05

We will not send data to clearing as we do not has proper data on authorization.

Mastercard will implement new changes for Clearing on Production

2023-06-06

Start sending fields for Authorization and Clearing for Test Productions TIDs.

Mastercard will implement new changes for Authorization on Production

Between 2023-06-06 and 2023-06-30

Verification on production and rollout for all clients.

There are no possibility to test earlier on production

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’s special conditions

CODE_03

Invalid merchant

CODE_04

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_09

Request in progress

CODE_10

Approved for partial amount

CODE_11

Approved (V.I.P)

CODE_12

Invalid transaction

CODE_13

Invalid amount

CODE_14

Invalid account number (no such number)

CODE_15

No such issuer

CODE_16

Approved, update track 3

CODE_17

Customer cancellation

CODE_18

Customer dispute

CODE_19

Re-enter transaction

CODE_20

Invalid response

CODE_21

No action taken

CODE_22

Suspected malfunction

CODE_23

Unacceptable transaction fee

CODE_24

File update not supported by receiver

CODE_25

Unable to locate record in file

CODE_26

Duplicate file update record, old record replaced

CODE_27

File update field edit error

CODE_28

File update file locked out

CODE_29

File update not successful, contact acquirer

CODE_30

Format error

CODE_31

Bank not supported by switch

CODE_32

Completed partially

CODE_33

Expired card

CODE_34

Suspected fraud

CODE_35

Card acceptor contact acquirer

CODE_36

Restricted card

CODE_37

Card acceptor call acquirer security

CODE_38

Allowable PIN tries exceeded

CODE_39

No credit account

CODE_40

Requested function not supported

CODE_41

Lost card, pick up (fraud account)

CODE_42

No universal account

CODE_43

Stolen card, pick up (fraud account)

CODE_44

No investment account

CODE_51

Not sufficient funds

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_56

No card record

CODE_57

Transaction not permitted to cardholder

CODE_58

Transaction not permitted to acquirer/terminal

CODE_59

Suspected fraud

CODE_60

Card acceptor contact acquirer

CODE_61

Exceeds withdrawal amount limit

CODE_62

Restricted card (card invalid in this region or country)

CODE_63

Security violation (source is not correct issuer)

CODE_64

Original amount incorrect/Transaction does not fulfill AML requirement

CODE_65

Exceeds withdrawal frequency limit

CODE_66

Card acceptor call acquirer’s security department

CODE_67

Hard capture (requires that card be picked up at ATM)

CODE_68

Response received too late

CODE_70

Contact Card Issuer/PIN data required

CODE_71

PIN Not Changed

CODE_74

Different value than that used for PIN encryption errors

CODE_75

Allowable number of PIN tries exceeded

CODE_76

Invalid/nonexistent “To Account” specified/Unsolicited reversal

CODE_77

Invalid/nonexistent “From Account” specified

CODE_78

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

CODE_79

Life cycle/Already reversed (by Switch)

CODE_80

System not available/No financial impact

CODE_81

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

CODE_82

Policy (Mastercard use only)/Negative CAM, dCVV, iCVV, or CVV results

CODE_83

Fraud/Security (Mastercard use only)

CODE_84

Invalid Authorization Life Cycle

CODE_85

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

CODE_86

PIN Validation not possible

CODE_87

Purchase Amount Only, No Cash Back Allowed

CODE_88

Cryptographic failure

CODE_89

Unacceptable PIN—Transaction Declined—Retry/Ineligible to receive financial position information (GIV)

CODE_90

Cutoff is in process (switch ending a day’s business and starting the next. Transaction can be sent again in a few minutes)

CODE_91

Issuer or switch is inoperative/Issuer or switch inoperative and STIP not applicable or not available for this transaction; Time-out when no stand-in; POS Check Service: Destination unavailable; Credit Voucher and Merchandise Return Authorizations: V.I.P. sent the transaction to the issuer, but the issuer was unavailable.

CODE_92

Financial institution or intermediate network facility cannot be found for routing

CODE_93

Transaction cannot be completed. Violation of law

CODE_94

Duplicate transmission

CODE_95

Reconcile error

CODE_96

System malfunction or certain field error conditions

CODE_A1

Additional customer authentication required

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

Denied PIN unblock—PIN change or unblock request declined by issuer

CODE_P6

Denied PIN change—requested PIN unsafe

CODE_Q1

Card Authentication failed

CODE_R0

Stop payment order

CODE_R1

Revocation of authorization order

CODE_R2

Transaction does not qualify for Visa PIN

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 2.X verification methods

3ds 2.X and 3ds 1.0 flow
3ds 2.X flow
Table 13. 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

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

3.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" : "73dca994-0943-491e-8392-3169cd35a9e6",
  "cardNumber" : "5430149160516930",
  "methodNotificationUrl" : "methodNotificationUrl.exemple.com"
}
Table 14. 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.

3.1.2. Response

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

{
  "requestUuid" : "8e5b2bd0-49fb-41fc-85e4-9b2e127785fb",
  "cardAuthenticationId" : "a0c315a8-bd29-4e9f-9a71-35e788e63d2f",
  "threeDSMethodData" : "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93ZWJob29rLnNpdGUvZDMyZTlkZTgtMGFiOC00ODZjLWJjNzEtMGU2Mzg2MmY4MDNhM2I1YTkzZTUtMjI1Ni00NGQ0LTg2YjItNWFkM2FhMDEyYTJhIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxNjNiZWMzOC1kOTM1LTQ0MGItYWYwYy01OWM3NDI3OTk2MGMifQ",
  "threeDSMethodURL" : "https:/acs.com",
  "protocolVersionStart" : "2.1.0",
  "protocolVersionEnd" : "2.2.0",
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK"
}

Unresolved directive in 3DSAPI/threeDSV2VerificationMethod.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/ThreeDsV2/preAuthentication3DSV2/response-fields-beneath-result.adoc[]

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

{
  "requestUuid" : "5cd0d4d0-44ac-4f90-ae0a-de72c94b999b",
  "cardAuthenticationId" : "f61d2895-8e3c-4179-933c-94c2eb7c6b73",
  "threeDSMethodData" : "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93ZWJob29rLnNpdGUvZDMyZTlkZTgtMGFiOC00ODZjLWJjNzEtMGU2Mzg2MmY4MDNhM2I1YTkzZTUtMjI1Ni00NGQ0LTg2YjItNWFkM2FhMDEyYTJhIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxNjNiZWMzOC1kOTM1LTQ0MGItYWYwYy01OWM3NDI3OTk2MGMifQ",
  "protocolVersionStart" : "2.1.0",
  "protocolVersionEnd" : "2.2.0",
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK"
}

Unresolved directive in 3DSAPI/threeDSV2VerificationMethod.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/ThreeDsV2/preAuthenticationWithoutThreeDSMethodURL3DSV2/response-fields-beneath-result.adoc[]

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

{
  "requestUuid" : "e4bd21ff-e24c-445c-86fb-98a12819deb8",
  "status" : "E03003",
  "message" : "Card number not Enrolled in 3DS v2",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "d0d34b00-d548-42fb-9a92-21abcd64330d"
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: 224

{
  "requestUuid" : "d3a387e8-c824-4a3e-b780-1a4879f6e928",
  "status" : "E03005",
  "message" : "Issuer card is not supported",
  "httpStatus" : "UNPROCESSABLE_ENTITY",
  "traceId" : "4113b80d-81b1-4fa8-8796-f0050c71e1b8"
}
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

3.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,
     (6001, 7000) - status: E03000,
     (7001, 8000) - status: E03009

3.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" : "6b3c2fa1-adb7-45ef-af95-e1a7ead20dcc",
  "cardAuthenticationId" : "249b4a02-04b9-4527-9aac-05b55d35dc71",
  "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 15. 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.

3.2.2. Response

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

{
  "requestUuid" : "0db87a95-32d0-4f82-ac92-2eef05319cfd",
  "transactionStatus" : "Y",
  "transactionXId" : "5f2458d2-db21-4d70-b2cb-80e078a30a6d",
  "cavv" : "B5gQCElHgQAAAAAKmFNEdQAAAAA=",
  "eci" : "06",
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK"
}

Unresolved directive in 3DSAPI/threeDSV2VerificationMethod.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/ThreeDsV2/authentication3DSV2/response-fields-beneath-result.adoc[]

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

{
  "requestUuid" : "a7b7974b-588f-4291-8ad5-0abddfc8e792",
  "transactionStatus" : "C",
  "acsurl" : "acsurl.com",
  "creq" : "c29tZSBjcmVx",
  "challengeHtmlFormBase64" : "PGh0bWw+PFNDUklQVCBMQU5HVUFHRT0iSmF2YXNjcmlwdCI+ZnVuY3Rpb24gT25Mb2FkRXZlbnQoKXsgZG9jdW1lbnQuZG93bmxvYWRGb3JtLnN1Ym1pdCgpOyB9PC9TQ1JJUFQ+PGJvZHkgT25Mb2FkPSJPbkxvYWRFdmVudCgpOyI+PGZvcm0gbmFtZT0iZG93bmxvYWRGb3JtIiBhY3Rpb249Imh0dHBzOi8vYWNzdGVzdC5jb20iIG1ldGhvZD0iUE9TVCI+PElOUFVUIHR5cGU9ImhpZGRlbiIgbmFtZT0iY3JlcSIgdmFsdWU9ImNyZXEiPjxJTlBVVCB0eXBlPSJoaWRkZW4iIG5hbWU9InRocmVlRFNTZXNzaW9uRGF0YSIgdmFsdWU9InNvbWVFbmNvZGVkRGF0ZSI+PC9mb3JtPjwvYm9keT48L2h0bWw+",
  "threeDSSessionData" : "ZGY0NDJhODQtOGJkZS00MmQ3LWExMTUtMzUyNjNlZGY1MGFk",
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK"
}

Unresolved directive in 3DSAPI/threeDSV2VerificationMethod.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/ThreeDsV2/authenticationChallenge3DSV2/response-fields-beneath-result.adoc[]

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

{
  "requestUuid" : "31567049-fec7-4aa9-ba8a-29a1086215fe",
  "status" : "E03000",
  "message" : "Error mpi V2 - failed internal",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "c32185d9-9f9f-4296-981e-bbd92f0c407f"
}
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" : "31567049-fec7-4aa9-ba8a-29a1086215fe",
  "status" : "E03000",
  "message" : "Error mpi V2 - failed internal",
  "httpStatus" : "INTERNAL_SERVER_ERROR",
  "traceId" : "c32185d9-9f9f-4296-981e-bbd92f0c407f"
}
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

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

3.3.1. Request

GET /processor/3ds/details/6c519ed2-e243-491b-988a-9abc2817d4d1 HTTP/1.1
Authorization: Basic bmFtZTpwYXNzd29yZA==
Host: processor-staging.fenige.pl
Table 16. /processor/3ds/details/{cardAuthenticationId}
Parameter Description

cardAuthenticationId

Unique identifier for 3ds verification

3.3.2. Response

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

{
  "cardAuthenticationId" : "4e745872-8707-400e-9a14-94bdf18c991a",
  "provider" : "MASTERCARD",
  "transactionStatus" : "Y",
  "cardAuthenticationStatus" : "AUTHENTICATION_FINISHED",
  "transactionXId" : "a03f3797-315c-4f87-9fff-74a20fa236b0",
  "cavv" : "jEu04WZns7pbARAApU4qgNdJTag",
  "eci" : "01",
  "transactionStatusReason" : "04",
  "status" : "S00000",
  "message" : "SUCCESS",
  "httpStatus" : "OK"
}

Unresolved directive in 3DSAPI/threeDSV2VerificationMethod.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/ThreeDsV2/authenticationDetails3DSV2/response-fields-beneath-result.adoc[]

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

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

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

4.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 and merchantName already exist(together)",
    "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.

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

4.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": "E2000000000001",
      "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, could be the same as old one

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

4.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 and merchantName already exist(together)",
    "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.

4.3. Delete merchant

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

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

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

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

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

5.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 17. 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 18. 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

6. Payment API

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

6.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 19. 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

6.1.2. Response

200 OK Mastercard

Unresolved directive in PaymentAPI/currencyForCardRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyForCard/successCurrencyForCard/response-body-beneath-result.adoc[] Unresolved directive in PaymentAPI/currencyForCardRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyForCard/successCurrencyForCard/response-fields-beneath-result.adoc[]

200 OK Visa

Unresolved directive in PaymentAPI/currencyForCardRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyForCard/successCurrencyForCardVisa/response-body-beneath-result.adoc[] Unresolved directive in PaymentAPI/currencyForCardRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyForCard/successCurrencyForCardVisaCurrencyUndefined/response-body-beneath-result.adoc[] Unresolved directive in PaymentAPI/currencyForCardRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyForCard/successCurrencyForCardVisa/response-fields-beneath-result.adoc[]

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 20. 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" : "dd053a2c-460a-4e94-b07d-7815af6149a1"
}
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" : "2be6fd7c-f0f3-420d-9b25-188145577750"
}
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" : "8e8d2c10-d74d-416d-99ea-943f295d782b"
}
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" : "485368f0-5823-438a-8ff2-6d5f77300a6a"
}
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

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

6.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" : "2024-11-06 01:31:38"
}
Table 21. 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 @Must not be UNDEFINED

Currency code for conversion

to

String

@Must not be null @Must not be UNDEFINED

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")

6.2.2. Response

200 OK (Mastercard)

Unresolved directive in PaymentAPI/currencyRateRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyRate/successCurrencyRateMastercard/response-body-beneath-result.adoc[] Unresolved directive in PaymentAPI/currencyRateRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyRate/successCurrencyRateMastercard/response-fields-beneath-result.adoc[]

200 OK (Maestro)

Unresolved directive in PaymentAPI/currencyRateRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyRate/successCurrencyRateMaestro/response-body-beneath-result.adoc[] Unresolved directive in PaymentAPI/currencyRateRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyRate/successCurrencyRateMaestro/response-fields-beneath-result.adoc[]

200 OK (VISA)

Unresolved directive in PaymentAPI/currencyRateRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyRate/successCurrencyRateVisa/response-body-beneath-result.adoc[] Unresolved directive in PaymentAPI/currencyRateRequest.adoc - include::/var/lib/jenkins/workspace/processor_staging/processor_hub-staging/target/generated-snippets/currencyRate/successCurrencyRateVisa/response-fields-beneath-result.adoc[]

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 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" : "3a209ea4-9862-447f-a90b-347013261416",
  "status" : "E00143",
  "message" : "Currency not found",
  "httpStatus" : "NOT_FOUND",
  "traceId" : "06018842-9d74-4f13-b41c-145cf9a6f2db"
}
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" : "dc009f5d-c93d-40b6-b6ea-4662c4ca1ee5"
}
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" : "9db30cbb-e9d6-491f-94fc-68a4113fd122"
}
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" : "5a3a22ae-4120-4862-b920-6e97e1bf1e27"
}
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

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

6.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" : "8a9a51ca-4a35-45a7-9d12-e01aeb1da830",
  "cardNumber" : "5117964247989169"
}
Table 23. Request headers
Name Description

Authorization

Basic auth credentials for PSP

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

6.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" : "8a9a51ca-4a35-45a7-9d12-e01aeb1da830",
  "provider" : "MASTERCARD"
}
Table 25. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

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 26. 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" : "5f9fd670-7cfe-4faf-95d9-7fdfe175a2e5"
}
Table 27. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

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" : "0b0eb082-f7b6-4c05-89e0-8ff1ff0f3678"
}
Table 28. Response fields
Path Type Description

status

String

Response code from Fenige system

message

String

Message for response code from Fenige system

httpStatus

String

Response http status

traceId

String

Id of trace

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

6.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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "6051",
    "cryptoCurrency" : true,
    "specialConditionIndicatorExistingDebt" : false,
    "terminalPanEntryMode" : "LOW_VALUE_PAYMENT",
    "networkAssignedId" : "NPID01"
  },
  "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 29. 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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

String

@Must match to one of LOW_VALUE_PAYMENT, ACQUIRER_LOW_FRAUD_AND_TRANSACTION_RISK_ANALYSIS, TRUSTED_MERCHANT_EXEMPTION, DELEGATED_AUTHENTICATION, SECURE_CORPORATE_PAYMENT or OUT_OF_SCOPE, can be null

OUT_OF_SCOPE - Country is outside EU

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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "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 30. 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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

String

@Must match to one of LOW_VALUE_PAYMENT, ACQUIRER_LOW_FRAUD_AND_TRANSACTION_RISK_ANALYSIS, TRUSTED_MERCHANT_EXEMPTION, DELEGATED_AUTHENTICATION, SECURE_CORPORATE_PAYMENT or OUT_OF_SCOPE, can be null

OUT_OF_SCOPE - Country is outside EU

LOW_VALUE_PAYMENT - Country is EU and amount is less than 30 euro

ACQUIRER_LOW_FRAUD_AND_TRANSACTION_RISK_ANALYSIS - Country is EU and the amount is equal to or greater than 30 EUR

terminal.networkAssignedId

String

@Can be null @Length for Visa 6, @Length for Mastercard 10.

When mastercard transaction is with network program field must be present, for visa transaction with network program fields is optional

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

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

STATUS: E001601 - Returned when transaction is with network program, but network assignedId 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",
  "banknetReferenceNumber":"66KXFF"
  "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 31. 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

banknetReferenceNumber

String

Unique data element, assigned by Mastercard, which identifies an authorization transaction. Available only for Mastercard transactions.

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 32. 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 33. 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 34. 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 35. 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 36. 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 37. 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 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

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

6.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,
  "networkProgram" : 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",
	"subdivision": "06",
	"taxId": "PL9111158900",
	"partnershipAgreement": "MC0001",
	"contactPhoneNumber": "48587604859",
	"supportPhoneNumber": "48587604844",
	"serviceCity": "Warszawa",
	"serviceCountry": "PL",
	"servicePostalCode": "01-262",
	"serviceSubdivision": "14"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "sender" : {
	"firstName" : "Mark",
	"lastName" : "Smith",
	"email": "senderEmail@fenige.pl"
  }
}
Table 39. Request headers

Name

Description

Authorization

Basic auth credentials for Acquirer

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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "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

autoClear

Boolean

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "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 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "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) 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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

String

@Can be null @Length for Visa 6, @Length for Mastercard 10.

When mastercard transaction is with network program field must be present, for visa transaction with network program fields is optional

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

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

STATUS: E001601 - Returned when transaction is with network program, but network assignedId 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",
    "banknetReferenceNumber":"66KXFF"
    "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 47. 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

banknetReferenceNumber

String

Unique data element, assigned by Mastercard, which identifies an authorization transaction. Available only for Mastercard transactions.

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 48. 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 49. 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 50. 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 51. 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 52. 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 53. 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 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

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

6.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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "cryptoCurrency" : false,
    "specialConditionIndicatorExistingDebt" : false,
    "terminalLocation" : "HOME",
    "terminalPanEntryMode" : "LOW_VALUE_PAYMENT",
    "networkAssignedId" : "NPID01"
  },
  "sender" : {
    "firstName" : "Mark",
    "lastName" : "Smith",
    "email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02",
    "walletIdentifier" : "GOOGLE_PAY"
  }
}
Table 55. 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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

terminal.terminalPanEntryMode

String

@Must match to one of LOW_VALUE_PAYMENT, ACQUIRER_LOW_FRAUD_AND_TRANSACTION_RISK_ANALYSIS, TRUSTED_MERCHANT_EXEMPTION, DELEGATED_AUTHENTICATION, SECURE_CORPORATE_PAYMENT or OUT_OF_SCOPE, can be null

OUT_OF_SCOPE - Country is outside EU

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 or 07, @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

paymentData.walletIdentifier

String

@Optional

An additional authorization field should be introduced to reflect the token type (GooglePay, ApplePay, etc.). Mastercard authorization platform may automatically add this element when it is available, but since the information is already known to acquirer prior authorization request is submitted, it should not be problematic to supply such information to avoid any potential declines. Acceptable values: MASTERPASS, APPLE_PAY, GOOGLE_PAY, SAMSUNG_PAY, REMOTE_COMMERCE_PROGRAMS.

The Remote Commerce Programs are a suite of electronic commerce (e-commerce) solutions, delivered to issuers through the Mastercard Digital Enablement Service (MDES). The suite consists of:

Click to Pay

Mastercard Secure Card on File (COF) (for Merchants and Commerce Platforms)

MDES for Merchants

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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "terminalLocation" : "HOME",
    "networkAssignedId" : "NPID01"
  },
  "sender" : {
    "firstName" : "Mark",
    "lastName" : "Smith",
    "email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
Table 56. 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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 or 07, @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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "terminalLocation" : "HOME",
    "networkAssignedId" : "NPID01"
  },
  "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 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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 or 07, @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,
  "networkProgram" : 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"
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "terminalLocation" : "HOME",
    "networkAssignedId" : "NPID01"
  },
  "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 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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 or 07, @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

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

STATUS: E001601 - Returned when transaction is with network program, but network assignedId 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",
  "banknetReferenceNumber":"66KXFF"
  "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 59. 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

banknetReferenceNumber

String

Unique data element, assigned by Mastercard, which identifies an authorization transaction. Available only for Mastercard transactions.

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 60. 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 61. 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 62. 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 63. 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 64. 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 65. 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 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

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

6.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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "terminalPanEntryMode" : "LOW_VALUE_PAYMENT",
    "networkAssignedId" : "NPID01"
  },
  "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 67. 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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

String

@Must match to one of LOW_VALUE_PAYMENT, ACQUIRER_LOW_FRAUD_AND_TRANSACTION_RISK_ANALYSIS, TRUSTED_MERCHANT_EXEMPTION, DELEGATED_AUTHENTICATION, SECURE_CORPORATE_PAYMENT or OUT_OF_SCOPE, can be null

OUT_OF_SCOPE - Country is outside EU

LOW_VALUE_PAYMENT - Country is EU and amount is less than 30 euro

ACQUIRER_LOW_FRAUD_AND_TRANSACTION_RISK_ANALYSIS - Country is EU and the amount is equal to or greater than 30 EUR

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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "terminalPanEntryMode" : "LOW_VALUE_PAYMENT",
    "networkAssignedId" : "NPID01"
  },
  "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 68. 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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

String

@Must match to one of LOW_VALUE_PAYMENT, ACQUIRER_LOW_FRAUD_AND_TRANSACTION_RISK_ANALYSIS, TRUSTED_MERCHANT_EXEMPTION, DELEGATED_AUTHENTICATION, SECURE_CORPORATE_PAYMENT or OUT_OF_SCOPE, can be null

OUT_OF_SCOPE - Country is outside EU

LOW_VALUE_PAYMENT - Country is EU and amount is less than 30 euro

ACQUIRER_LOW_FRAUD_AND_TRANSACTION_RISK_ANALYSIS - Country is EU and the amount is equal to or greater than 30 EUR

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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "terminalLocation" : "HOME",
    "terminalPanEntryMode" : "LOW_VALUE_PAYMENT",
    "networkAssignedId" : "NPID01"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
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 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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

terminal.terminalPanEntryMode

String

@Must match to one of LOW_VALUE_PAYMENT, ACQUIRER_LOW_FRAUD_AND_TRANSACTION_RISK_ANALYSIS, TRUSTED_MERCHANT_EXEMPTION, DELEGATED_AUTHENTICATION, SECURE_CORPORATE_PAYMENT or OUT_OF_SCOPE, can be null

OUT_OF_SCOPE - Country is outside EU

LOW_VALUE_PAYMENT - Country is EU and amount is less than 30 euro

ACQUIRER_LOW_FRAUD_AND_TRANSACTION_RISK_ANALYSIS - Country is EU and the amount is equal to or greater than 30 EUR

terminal.networkAssignedId

String

@Can be null @Length for Visa 6, @Length for Mastercard 10.

When mastercard transaction is with network program field must be present, for visa transaction with network program fields is optional

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 or 07, @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. STATUS: E001602 - Transaction rejected, initial uuid 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: E001601 - Returned when transaction is with network program, but network assignedId 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",
  "banknetReferenceNumber":"66KXFF"
  "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

banknetReferenceNumber

String

Unique data element, assigned by Mastercard, which identifies an authorization transaction. Available only for Mastercard transactions.

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 70. 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 71. 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 72. 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 73. 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 74. 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 75. 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 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

6.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,
  "networkProgram" : 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",
  	"subdivision": "06",
  	"taxId": "PL9111158900",
  	"partnershipAgreement": "MC0001",
  	"contactPhoneNumber": "48587604859",
  	"supportPhoneNumber": "48587604844",
  	"serviceCity": "Warszawa",
  	"serviceCountry": "PL",
  	"servicePostalCode": "01-262",
  	"serviceSubdivision": "14"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "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 77. 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "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 78. 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
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) 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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

String

@Can be null @Length for Visa 6, @Length for Mastercard 10.

When mastercard transaction is with network program field must be present, for visa transaction with network program fields is optional

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 or 07, @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

CoF Subsequent with external trace id
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",
  "traceId" : "abc123def1234",
  "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",
  	"subdivision": "06",
  	"taxId": "PL9111158900",
  	"partnershipAgreement": "MC0001",
  	"contactPhoneNumber": "48587604859",
  	"supportPhoneNumber": "48587604844",
  	"serviceCity": "Warszawa",
  	"serviceCountry": "PL",
  	"servicePostalCode": "01-262",
  	"serviceSubdivision": "14"
  },
  "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

traceId

String

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

External trace id

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

@Must not be null, 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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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

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.

STATUS: E001601 - Returned when transaction is with network program, but network assignedId 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" : "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",
  "banknetReferenceNumber":"66KXFF"
  "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

banknetReferenceNumber

String

Unique data element, assigned by Mastercard, which identifies an authorization transaction. Available only for Mastercard transactions.

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 81. 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 82. 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 83. 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 84. 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 85. 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 86. 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 87. 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

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

6.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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14"
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "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 88. 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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,
  "networkProgram" : 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"
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "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 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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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,
  "networkProgram" : 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",
    "subdivision": "06",
    "taxId": "PL9111158900",
    "partnershipAgreement": "MC0001",
    "contactPhoneNumber": "48587604859",
    "supportPhoneNumber": "48587604844",
    "serviceCity": "Warszawa",
    "serviceCountry": "PL",
    "servicePostalCode": "01-262",
    "serviceSubdivision": "14",
  },
  "terminal" : {
    "terminalId" : "ABC12345",
    "terminalUrl" : "www.fenige.com",
    "mcc" : "4111",
    "networkAssignedId" : "NPID01"
  },
  "sender" : {
  	"firstName" : "Mark",
  	"lastName" : "Smith",
  	"email" : "senderEmail@fenige.pl"
  },
  "paymentData" : {
    "onlinePaymentCryptogram" : "/0OL1zEABL+gk70RYJ8lMAABAAA=",
    "eciIndicator" : "02"
  }
}
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

@Must not be null, true or false

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

networkProgram

Boolean

@Optional true or false

Field indicates that transaction is with specific interchange fee

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 Alpha-2

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

merchant.subdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s subdivision code

merchant.taxId

String

@Length must be between 1 and 20 inclusive, @Must not be blank, Optional @Can be null

The merchant’s tax identification number

merchant.partnershipAgreement

String

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

The partnership agreement between the merchant and Mastercard

merchant.contactPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s contact phone number

merchant.supportPhoneNumber

String

@Length must be between 1 and 16 inclusive, @Full phone format only numbers, @Must not be blank, Optional @Can be null

The merchant’s support phone number

merchant.serviceCity

String

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

The merchant’s service city

merchant.serviceCountry

String

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

The merchant’s service country

merchant.servicePostalCode

String

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

The merchant’s postal code

merchant.serviceSubdivision

String

@Length must be between 1 and 3 inclusive, @Must not be blank, Optional @Can be null

The merchant’s service subdivision

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

String

@Can be null @Length for Visa 6, @Length for Mastercard 10.

When mastercard transaction is with network program field must be present, for visa transaction with network program fields is optional

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 or 07, @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. STATUS: E001602 - Transaction rejected, initial uuid 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.

STATUS: E001601 - Returned when transaction is with network program, but network assignedId 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",
  "banknetReferenceNumber":"66KXFF"
  "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 91. 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

banknetReferenceNumber

String

Unique data element, assigned by Mastercard, which identifies an authorization transaction. Available only for Mastercard transactions.

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 92. 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 93. 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 94. 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 95. 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 96. Response fields
Path Type Description

requestUuid

String

Request’s unique uuid in system

transactionUuid

String