About Card Payments

General information about card payments

FXC's Gateway processes all major cards and currencies worldwide. Card data is protected against unauthorised access by TLS encryption. Additional security functions are integrated fraud prevention and risk management. Our standardized settlement files guarantee a straightforward reconciliation processes in your accounting.

Verified by Visa and MasterCard SecureCode secure your payment claim by password validation if a customer disputes the payment later. American Express SafeKey also uses the 3D-Secure technology, which means that the card holder must confirm their identity with a password.

Transaction processing can be made via FXC Gateway standard form, via customized forms, via server-to-server-connection or via batch transfer. Likewise, FXC Gateway can process transactions from stationary terminals.

Using the card form provides several advantages:

  1. Merchants can bypass the costly PCI-security authorisation
  2. The programming of 3DSecure with forms is much easier and quicker than via Server-to-Server connection

Process of 3D Secure payments

MasterCard SecureCode (UCAF), Verified by Visa (VbV), Diners ProtectBuy, JCB J/Secure and American Express SafeKey are authentication methods which verify the identity of the card holder before making the payment. The name 3D Secure used by technicians describes only the protocol. The correct brand names are Verified by Visa, MasterCard SecureCode, SafeKey, ProtectBuy and J/Secure.

Merchants benefit from authentication with 3D Secure because the card schemes provide a liability shift: If you are using Verified by Visa, MasterCard SecureCode, Diners ProtectBuy, JCB-Card J/Secure or American Express SafeKey, the burdon of proof and thereby generally the liability is shifted from the merchant to the card issuing bank, should the customer dispute the payment. Irrespective of whether the card holder actually uses the authentication you obtain a very high protection against payment defaults / chargebacks in case the customer states they have not authorized the card payment. Your Acquirer will be able to discuss the details of 3D Secure and the cover that it provides.

From a technical perspective 3D Secure is not a payment method but an authentication process which precedes the payment: Once the credit card data has been entered, FXC Gateway checks the identity of the card holder and does not process the payment until after the authentication.

For further steps it is crucial if the credit card connection is made via form interface or via Server-to-Server-connection. In the first case the FXC Gateway form assumes the further authentication process, with Server-to-Server-connection the merchant has to manage the authentication through a separate interface.

Process of a transaction with 3D Secure via form interface

The customer selects the Credit card payment method in the Internet shop and enters the card number and expiry date. FXC Gateway receives the card number and checks, via a connection to Visa, MasterCard, Diners, JCB or American Express, whether this credit card is registered for Verified, SecureCode, Diners ProtectBuy, JCB-Card J/Secure or SafeKey. If the credit card is not registered a credit card payment is carried out with TLS. With that the transaction gets a flag which identifies payments with 3D Secure. This marking tells the Acquiring Bank that you use the authentication and a secured payment claim is obtained based on the Liability Shift in case the card holder disputes the payment.

If the customer's credit card has been registered by the issuing bank for Verified by Visa, MasterCard SecureCode, Diners ProtectBuy, JCB-Card J/Secure or American Express SafeKey the authentication process now starts: FXC Gateway opens a new browser window which connects the customer to its bank. In this window the customer enters the password received by its bank.

If the password is correct FXC Gateway obtains confirmation in the form of a signature. Only after confirmation does FXC Gateway start the payment and send the transaction with the signature to the Acquiring Bank.

FXCPay flow

Communication for credit card payments with 3D Secure with FXC Gateway forms

Process of a transaction with 3D Secure via Server-to-Server-connection

To carry out authentication, FXC Gateway connects the card holder to his bank, which confirms the identity. A payment process with Verified by Visa or MasterCard SecureCode, Diners ProtectBuy, JCB-Card J/Secure or American Express SafeKey comprises two steps: authentication and payment.

Following scheme illustrates the processes of a Server-to-Server-payment with 3D Secure.

In the next phases there are three different cases in which FXC Gateway responses differ. The individual connection parameters can be found in the credit card payments section of the handbook.

Case 1: Credit card not registered for 3D Secure

FXC Gateway initially contacts Visa or MasterCard, Diners, JCB or American Express Directory Server to determine whether the purchaser's credit card is registered for Verified or SecureCode or SafeKey.

Case 2 with Popup: Credit card registered for a 3D Secure system

IMPORTANT NOTICE: We strongly recommend the use of the iFrame solution since MasterCard has revised the regulations. MasterCard prohibits the use of a popup. For this an excerpt from the regulations (Excerpt from: MasterCard® SecureCode™ Merchant Implementation):

"Inline window implementations, which have proven to virtually eliminate the issues caused by pop-up authentication windows, are required for all new merchant implementations and existing pop-up implementations must convert to inline windows."

If the credit card is registered for Verified or SecureCode, ProtectBuy, J/Secure or SafeKey, FXC Gateway returns the socket-connection HTML source code with a JavaScript function. This JavaScript function creates the connection to the bank with which the customer is authenticated by entering its password into a popup-window. The HTML source code with the JavaScript function Initiate3DSec() which FXC Gateway sends to the shop must be embedded in the response page which the shop displays in the customer's browser.

Notice: Please note that the use of a popup window can lead to problems with popup blockers in the customer's browser. Therefore case 3 describes an alternative in the form of an Inframe variant.

The listing to the right shows a response page in which the HTML code is embedded:



Notice
: You can also use this code if you only want to verify the identity of the card holder without making a credit card payment. Our Support team can set your account in a way that FXC Gateway can carry out just the authentication with Verified or SecureCode, ProtectBuy, J/Secure or SafeKey without payment (Authentication Hosting).

After the customer has been authenticated with its bank, the bank's Access Control Server (ACS) requests the TermURL in the shop. In the case of this Request the ACS transfers the following parameters via GET (QueryString) to the TermURL of the shop: MID, PayID and TransID. The PARes parameter is transferred via POST.

Notice: The PAResponse parameter must be URL encoded but not Blowfish-encrypted since the content can include special characters.

The parameter must be transferred in whole via POST to the following URL:

https://fxcpay.com/direct3d.aspx

Notice: If you forward the PARes and MID of the ACS parameters please use the specified parameter name MerchantID, PAResponse for the direct3d.aspx page.

Case 3 without Popup: Credit card registered for a 3D Secure system.

Alternatively to the popup window the card holder can also carry out authentication with the bank in an iFrame variant; this avoids difficulties with popup blockers in the customer's browser. Provided the card is registered on the Directory Server, FXC Gateway returns the following parameters via the socket connection.

Parameter Format CND Description
ACSURL ans.. C Only in the case of registered credit cards: URL of the Access Control Server of the card issuer with attached request parameters (not URL-encoded!)
PaReq ans.. M Payer Authentication Request, which must be URL-encoded.
MD   M Merchant Data is an empty value, which must be transferred for compatibility reasons
TermURL ans.. M Shop return address

Response parameters of Socket-connection for the Authentication Request

Notice: Please note in this process that data must sometimes be transferred directly from the bank network. Therefore e.g. the ACSURL parameter is not URL-encoded, although FXC Gateway uses other URL-encoded data.

These parameters should be included as HIDDEN fields in an HTML page which posts itself to the ACS-URL.

The listing above to the right shows one such HTML page, in which the return parameters are embedded:


Notice: You can also use this code if you only want to verify the identity of the card holder without immediately making a credit card payment (Authentication Hosting). FXC Support can configure your checkout so that FXC Gateway can carry out Verified by Visa or SecureCode without payment.

After the customer has been authenticated with its bank, the bank's Access Control Server (ACS) requests the TermURL in the shop. In the case of this Request the ACS transfers the following parameters via GET (QueryString) to the TermURL of the shop: MID, PayID and TransID (unencrypted). The PARes parameter is transferred unencrypted via POST.

Notice: The PAResponse parameter must be URL encoded but not Blowfish-encrypted since the content can include special characters.

The parameter must be transferred in whole via POST to the following URL:

https://fxcpay.com/direct3d.aspx


Notice: If you forward the PARes and MID of the ACS parameters please use the specified parameter name MerchantID, PAResponse for the direct3d.aspx page.


FXCPay flow

Communication for credit card payments with 3D via socket connection

The following listing shows a response page in which the HTML code is embedded:
<HTML> <HEAD> <META http-equiv=Content-Type content="text/html; charset=unicode"> <script language="javascript"> <!-- <Response excerpt from request: HTML with JavaScript> //--> </script> </HEAD>"); <BODY onload="javascript:Initiate3DSec();"> <table> <tr> <td align="center"> <font face="Verdana" size="-1"> <b>Please identify yourself with 3D Secure! </b> </font> </td> </tr> </table>"); </BODY> </HTML>
The following listing shows one such HTML page, in which the return parameters are embedded:
<HTML> <HEAD> <META http-equiv=Content-Type content="text/html; charset=unicode"> <A content="MSHTML 6.00.2800.1106" name=GENERATOR> </HEAD> <BODY onload="sendpareq.submit();"> <FORM action="[ACSURL]" method="POST" name="sendpareq"> <input type="hidden" name="MD" value=""> <input type="hidden" name="PaReq" value="[PaReq]"> <input type="hidden" name="TermUrl" value="[TermUrl]"> </FORM> </BODY> </HTML>

Credit card brands

Credit card brand, correct spelling for CCBrand
MasterCard
VISA

Definitions

Data formats:

Format Description
a alphabetical
as alphabetical with special characters
n numeric
an alphanumeric
ans alphanumeric with special characters
ns numeric with special characters
bool boolean expression (true or false)
3 fixed length with 3 digits/characters
..3 variable length with maximum 3 digits/characters
enum enumeration of allowed values
dttm ISODateTime (YYYY-MM-DDDhh:mm:ss)

Abbreviations:

Abbreviation Description
CND condition
M mandatory
O optional
C conditional

Notice: Please not that the names of parameters can be returned in upper or lower case.

FXC Gateway interface: via form

Chart of process flow via form interface

You can view the process flow of Credit card payment via form interface in the image to the right.
Chart of process flow via form interface

Corporate PayPage

FXC Gateway forms are framed as standard in white and grey. Merchants can customise the layout of the forms with the help of layout parameters. The simplest way to change the layout is to set the parameters for the background colour (BGColor), background image (BGImage) and the font (FFace). You can use XSL-templates to change the layout further:

In the case of credit card payments, you can change the parameter Template to create an individual layout for your PaySSL form which exactly matches the shop layout. To this end your graphic designer can design an HTML-template in the shop-design based on XSLT (Extensible Stylesheet Language Transformation). FXC Support copies this XSLT-template to our FXC Gateway Server. If you enter the name of your XSLT-file in the Template parameter, the FXC Gateway form will appear in your layout.

For general information about XSLT see www.w3.org.

The subsequent conventions apply for the use of the Corporate Paypage with XSLT:

File names

A XSL file designed by you defines your individual layout. The associated XML file contains the texts that are to be displayed on the form. Hence, multilingualism is easy. Always use your MerchantID in the names of the files.

XSL template:

MerchantID_PaySSL.xsl

XML text file:

MerchantID_PaySSL.xml

Sub-folder for images:

Templates/imagesMerchantID

In order not to receive safety notices, please ensure that external image sources are retrieved via SSL.

In order to call the individual layout, use the 'template' parameter with your MerchantID and attach it unencrypted to the call of the FXC payment page, for example:

https://fxcpay.com/payssl.aspx?MerchantID=YourMID&Len=123&Data=AGSD_ASDF&template=YourMerchantID

Field names of the form

When implementing the text field for the credit card number, use the following values for the parameters 'name' and 'id':

Year of expiry:

"KKYear"

Expiry date month:

"KKMonth"

Credit card number:

"KKNr"

Card verification number:

"CCCVC"

Card brand: 

"KKName"

You can view the text field for the input in the image to the right.

A text field for the input of the credit card number is then implemented as follows:
<input type="text" name="KKNr" id= "KKNr" value=""></input>

Hidden Fields

The following hidden fields must be implemented so that the values can be passed on when sending the form:

MerchantID:
"MerchantID"

Request length:
"Len"

Request data:
"Data"

Template:
"Template"

Repeat attempts:
"Counter"

Language:
"Language"

Notify:
"Norify" - (optional in the case of repeat attempts)

Address choice
"AddrChoice" (only for American Express address verification service)

Language selection

The language selection in form PaySSL.aspx is automatically based on the parameterLanguage. Other language areas are filtered out. If you wish to access the field of another language area e.g. with JavaScript, you can do so via the following path: FXC Gateway/language/@name.

XML structure

The 'language' parameter controls which section of the XML text file is read out. German 'de' is always used as standard.

The XML file should have the basic structure as shown in the top image to the right:

'UTF-8' is also possible for the coding.

With<xsl:variablename=““ select="FXC Gateway/language/@name"/> you can directly address an XML language section from the XSL file.

For an overview of which parameters are additionally rendered by the PaySSL, please examine the structure (XSL file is rendered against the following XML string) as shown in the second image to the right.

Since merchants use its own layout for the form, you do not require the layout parameter. However, it is possible after prior consultation with FXC to use the parameters for the transfer, e.g. the SessionID.

For an overview of which parameters are additionally rendered by the PaySSL, please examine the following structure (XSL file is rendered against the following XML string):
<?xml version="1.0" encoding="windows-1252"?> </languages> <language name="de"> </language> <language name="en"> </language> </languages>
The XML file should have the following basic structure:
strXML = "<?xml version="1.0" encoding="windows-1252"?>" & _ "<FXC Gateway pay="ssl">" & _ "<merchantID>"..."</merchantID>" & _ "<len>"..."</len>" & _ "<data>"..."</data>" & _ "<Background>"..."</Background>" & _ "<BGImage>"..."</BGImage>" & _ "<BGColor>"..."</BGColor>" & _ "<FFace>"..."</FFace>" & _ "<FSize>"..."</FSize>" & _ "<FColor>"..."</FColor>" & _ "<center>"..."</center>" & _ "<CCard>"..."</CCard>" & _ "<Year>"..."</Year>" & _ "<URLBack>"..."</URLBack>" & _ "<twidth>"..."</twidth>" & _ "<theight>"..."</theight>" & _ “<brands><brand>”…”</brand></brands>” &_ “<cvc>”…”</cvc>” &_ "<ccexpiryyear>" … "</ccexpiryyear>" & _ "<ccbrand>" … "</ccbrand>" & _ "<template>"..."</template>" & _ "<counter>"… "</counter>" & _ "<errorcode>"..."</errorcode>" & _ "<PCNr>"..."</PCNr>" & _ "<PCNrBrand>"... "</PCNrBrand>" & _ "<PCNrMonth>"… "</PCNrMonth>" & _ "<PCNrYear>"… "</PCNrYear>" & _ “<creditcardholder>” … “</creditcardholder>” "<Autostart>"…"</Autostart>" & _ <language/@name ... (Area for selected language-Node) (content of MerchantId_PaySSL.xml in the respective language)> "</FXC Gateway>"

Error mapping

In the case of the error codes, as shown in the column to the right, FXC returns the form in order to enable the credit card data to be entered again. You only have to evaluate the 'error code' parameter and display the desired text from your XML file.

See image to the right to see at this point what the ‘error code’ template is called.

The second image to the right shows the called-up ‘error code’ template which may look like this. It can alternatively be implemented with ‘if’.

It is also possible to integrate the error messages directly into the (main) template as shown in the final image on the right side.

At this point the 'error code' template is called:
<xsl:apply-templates select="/FXC Gateway/errorcode" />
The called-up ‘error code’ template may look like this. It can alternatively be implemented with 'if'.
<xsl:template match="errorcode"> <tr> <td> <xsl:choose> <xsl:when test=".="0015" "> <xsl:value-of select="/FXC Gateway/language/ ErrorCodeDescription/Description1"/> <!--The input of the credit card number was not correct--> </xsl:when> ... </xsl:choose> </td> </tr> </xsl:template>
It is also possible to integrate the error messages directly into the (main) template:
<xsl:if test="FXC Gateway/errorcode != "" "> <xsl:choose> <xsl:when test="FXC Gateway/errorcode="0015" "> <xsl:value-of select="/FXC Gateway/language/ ErrorCodeDescription/Description1"/> <!--The input of the credit card number was not correct--> </xsl:when> </xsl:choose> </xsl:if>

JavaScript

If JavaScript functions are desired, you must implement them in your template (as shown to the right).

Please do not use any external link to your JavaScript.

If JavaScript functions are desired, you must implement them in your template.
<script id=“clientEventHandlersJS“ language=“JavaScript“> if (document.SSLForm.KKnr.value.length> 19) { alert(„<xsl:value-of select=“/FXC Gateway/language/strJavaScript1“/>“); document.SSLForm.KKnr.focus(); } ... </script>

Programming and testing the form

First design a HTML page with the layout for your payment page and initially save it for testing with the file extension .htm or .html. Open this file in the browser. Next, save this as an xsl file. (See image to the right).

In order to read the texts from the XML file, first of all create your tags in the desired language sections with the texts (see third image to the right).

Subsequently, replace the text in the HTML by a reference to the respective section in the XML file (See fourth image to the right).

In order to test your template, we request that you integrate these lines in your XML file only for the test (before sending it to FXC) and afterwards to call up the XML file in a browser. If no error is displayed you can send your template and the image folder in a Zip file to FXC's Support with a request to check and install it (as shown in the fifth image to the right).

In order to get an overview of the versions, please include the date and version number in the name of your Zip file.

As with the credit card form, it is now also possible to design your own XSLT templates for the SEPA direct debit form. In exactly the same way as with the credit card form, this is controlled via the 'Template' parameter. This can be called via the following URL:

https://fxcpay.com/paySDD.aspx?MerchantID=IhreMID&Len=123&Data=AGSD_ASDF&template=YourMerchantID


The files must use the following naming convention:

XSL template: MerchantID_PaySDD.xsl
XML text file: MerchantID_PaySDD.xml
Sub-folder for images: Templates/imagesMerchantID

Notice: A Corporate Paypage offers you much more extended functions like for example a preconfiguration of card data which are not explained in detail here. For questions about extended functions please consult the FXC Support.

Open this file in the browser. Next, save this as an xsl file.
<?xml version="1.0" encoding="windows-1252"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="html" encoding="UTF-8"/> <xsl:template match="/"> <html> <head> <title>PaySSL Template</title> <script>Your JavaScript</script> </head> <body> <form action="https://fxcpay.com/payinterim.aspx" methode="POST"> Your form with hiddenfields and xsl-tags </form> </body> </html> </xsl:template>
In order to read the texts from the XML file, first of all create your tags in the desired language sections with the texts:
<language name="de"> <strCCNumber>credit card number</strCCNumber> </language>
Subsequently, replace the text in the HTML by a reference to the respective section in the XML file:
<xsl:value-of select="/FXC Gateway/language/strCCNumber"/>
If no error is displayed you can send your template and the image folder in a Zip file to FXC's Support with a request to check and install it.
<?xml version="1.0" encoding="windows-1252"?> <?xml-stylesheet type="text/xsl" href="templatename.xsl"?> <FXC Gateway> <languages>please omit for your layout tests <language name="de"> </language> <language name="en"> </language> <languages>please omit for your layout tests </FXC Gateway>

General parameters of the interface

The interface of the FXC Gateway form is consistently payssl.aspx for all connections. In order to make a credit card payment via FXC Gateway form, go to the following URL:

https://fxcpay.com/payssl.aspx

This section explains the parameters which are the same for each connection. These values are always required, along with the special parameters explained in the following sections for each individual connection, e.g. GICC. The second table explains all response parameters which are also the same for all credit card connections. There are separate handbooks for credit card transactions via PagBrasil, PayU CEE and PayU LatAm connections.

Notice: For security reasons, FXC Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter Format CND Description
MerchantID ans..30 M Merchant ID, assigned by FXC This parameter is to be passed in plain language.
TransID ans..64 M TransactionID which should be unique for each payment
Please note for some connections the different formats that are given within the specific parameters.
Amount n..12 M Amount in the smallest currency unit (e.g. EUR Cent)
Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).
Amount3D n..12 OC Only for 3DSecure: Amount for authentication with Verified, SecureCode and SafeKey if Amount deviates. E.g. Customer confirms flight costs of 120 Euros with 'Verified' but the travel agent captures only the booking fee of 20 Euros: Amount3D=12000; Amount=2000. Amount in the smallest currency unit (e.g. EUR Cent)
Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).
Currency a3 M Currency, three digits DIN / ISO 4217
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
URLSuccess ans..256 M Complete URL which calls up FXC Gateway if payment has been successful. The URL may be called up only via port 443 This URL may not contain parameters: In order to exchange values between FXC Gateway and shop, please use the parameter UserData.
URLFailure ans..256 M Complete URL which calls up FXC Gateway if payment has been unsuccessful. The URL may be called up only via port 443 This URL may not contain parameters: In order to exchange values between FXC Gateway and shop, please use the parameter UserData.
Response a7 O Status response sent by FXC Gateway to URLSuccess and URLFailure, should be encrypted. For this purpose, transmit Response=encrypt parameter.
URLNotify ans..256 M Complete URL which FXC Gateway calls up in order to notify the shop about the payment result. The URL may be called up only via port 443 It may not contain parameters: Use the UserData parameter instead.
UserData ans..256 O If specified at request, FXC Gateway forwards the parameter with the payment result to the shop
Capture ans..6 O Determines the type and time of capture. AUTO: capturing immediately after authorisation (default value). MANUAL: capturing made by the merchant. : Delay in hours until the capture (whole number; 1 to 696).
ReqID ans..32 O To avoid double payments, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction is submitted again with the same ReqID, FXC Gateway will not carry out the payment, but will just return the status of the original transaction.
Plain ans..50 O A value to be set by the merchant to return some information unencrypted, e.g. the MID
Custom ans..1024 O The merchant can submit several values separated by | which are returned unencrypted and separated by &.
Custom=session=123|id=456 will change in the answer to Session=123&id=456
expirationTime ans..19 O timestamp for the end time of the transaction processing, specified in UTC.
Format: YYYY-MM-ddTHH:mm:ss
CustomField[n] ans..50 O Field that can be used individually by the merchant. Presently 14 fields from CustomField1 to CustomField14 are supported.

General parameters for credit card payments via form

To adapt the layout of the SSL-page to your shop you can use the following unencrypted parameters to configure colours, fonts and images.

Parameter Format CND Description
Template ans..20 O Name of XSLT-file with your own layout for the pay form. If you want to use the redesigned and downwards compatible FXC template, please transfer the template name "ct_compatible". If you want to use the responsive FXC template for mobile devices, please transfer the template name "ct_responsive".
Background ans..256 O Background ambiance of form:
URL for a background image
- HTML-colour value for background colour as HEX value or
- HTML-colour name
BGColor ans..7 O Form background colour:
- HTML-colour value for background colour as HEX value or
- HTML-colour name
BGImage ans..256 O Form background image:
URL for a background image
Please note that this value supersedes "BGColor".
FColor ans..6 O Text colour:
- HTML-colour value as HEX value or
- HTML-colour name
FFace ans..10 O HTML-name for the font
FSize n2 O Number for font size
Language a2
(enum)
O Language code:
No details means the language is German.
CCSelect a16 O Determines preselected card type in the form: VISA, AMEX, JCB, DINERS, MasterCard, Cartes Bancaires, Bancontact, Maestro, Dankort, Hipercard, CBN, Airplus, ComfortCard, Discover, Elo, Auro, CUP
URLBack ans..256 O URL for "Cancel" button
Center n1 O By default the form is centered vertically and horizontally. The value <1> centres the form at the top.
tWidth ans..4 O Width of table for input of the credit card data as percent- (50%) or pixel values (320).
tHeight ans..4 O Height of table for input of the credit card data as percent- (70%) or pixel values (480).

Layout parameters for FXC Gateway forms for credit card payments

The following table describes the result parameters that FXC Gateway transmits to your URLNotify, URLSuccess or URLFailure. If you have specified the Response=encrypt parameter, the following parameters are sent Blowfish encrypted to your system:

Parameter Format CND Description
MID ans..30 M MerchantID, assigned by FXC
PayID an32 M ID assigned by FXC Gateway for the payment, e.g. for referencing in batch files
XID an32 M ID for all single transactions (authorisation, capture, credit note) for one payment assigned by FXC Gateway
TransID ans..64 M Merchant's transaction number
Please note for some connections the different formats that are given within the specific parameters.
Status a..50 M OK or AUTHORIZED (URLSuccess) as well as FAILED (URLFailure)
Description ans..1024 M
Code n8 M Error code according to FXC Gateway Response Codes Excel file.
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
UserData ans..1024 O If specified at request, FXC Gateway forwards the parameter with the payment result to the shop
PCNr n16 O Pseudo Card Number: Random number generated by FXC Gateway which represents a genuine credit card number. The pseudo card number (PCN) starts with 0 and the last 3 digits correspond to those of the real card number. You can use the PCN like a genuine card number for authorisation, capture and credits.
CCBrand a22 OC In combination with PCNr: Name of credit card brand.
Please note the spelling according to table of credit card brands!
CCExpiry n6 OC In combination with PCNr: Expiry date of the credit card in the format YYYYMM (201706).
MaskedPan an..19 OC Masked card number 6X4
CAVV ans..40 OC In the case of 3D Secure with Authentication Hosting (only 3D request without authorisation): Cardholder Authentication Validation Value: Contains the digital signature for authentication with the ACS of the card issuing bank.
ECI n2 OC In the case of 3D Secure with Authentication Hosting (only 3D request without authorisation): ACS E-Commerce indicator: defines the security level of a credit card payment via different communication paths: MOTO, SSL, Verified by Visa etc.
Type ans..20 C For 3D Secure only in the response to URLNotify: Abbreviation of payment type, e.g. SSL
Plain ans..50 O A value to be set by the merchant to return some information unencrypted, e.g. the MID
Custom ans..1024 O The merchant can submit several values separated by | which are returned unencrypted and separated by &.
Custom=session=123|id=456 will change in the answer to
Session=123&id=456
CustomField[n] ans..50 O Field that can be used individually by the merchant. Presently 14 fields from CustomField1 to CustomField14 are supported.

General results parameters for URLNotify, URLSuccess and URLFailure

GICC: Concardis, B+S Card Service, EVO Payments, American Express, Elavon, SIX Payment Service

Besides the general parameters described above

Call of interface: general parameters for the credit card connection, GICC requires the following additional parameters. An authorization with 3D Secure is possible. The following table describes the encrypted payment request parameters:

Parameter Format CND Description
RefNr ns..30 M Merchant's unique reference number
OrderDesc ans..768 M Description of purchased goods, unit prices etc.
CreditCardHolder ans..60 O Name of the card holder
RTF a1 O for repeat payments (subscriptions): I = Initial payment of a new subscription
R = Routine payment (Recurring)
ChDesc an..30 O Text printed on the customer's credit card bill alongside the payee
AccVerify a3 O If AccVerify=Yes the credit card is checked at the acquirer according to he interface descriptions of the acquirer. The merchant has to submit only this parameter, the "Amount" is optional. If "Amount" is used we replace this value according to the interface description of the acquirer. At the payment always Amount=0 is stored.
Permissiable value: yes
CountryCode a2 O Card holder information: Country
Textfeld1 ans..30 O Card holder information: Name
Textfeld2 ans..30 O Card holder information: City
Contact data/Address verification (AVS)
Parameter Format CND Description
AddrStreet ans..50 O Street name (for AVS)
AddrStreetNr ans..15 O Street number for verification by American Express (for AVS)
AddrZip n10 O Postcode (for AVS)
AddrCity a40 O Town/city (for AVS)
AddrCountryCode a2/a3 M Country code according to ISO-3166-1: it can be transmitted with two or three digits optionally - Format a2 / a3 (for AVS)
AddrStreet2 a..32 O Second street name (for AVS)
AddrStreetNr2 ans..5 O Second street number (for AVS)
AddrZip2 n..5 O Second postcode (for AVS)
AddrCity2 a..32 O Second town/city (for AVS)
AddrChoice n1 O If you transmit 2 street numbers and postcodes, the AddrChoice parameter will determine which address is checked. AddrChoice=1 checks the first address, AddrChoice=2 the second address. (for AVS)

Additional parameters for the credit card connection GICC via FXC Gateway form

The following table gives the result parameters which the FXC Gateway transmits especially for the GICC connection to your URLSuccess or URLFailure and URLNotify. If you have specified the Response=encrypt parameter, the following parameters are sent Blowfish encrypted to your system:

Parameter Format CND Description
Match a1 O Total result of address check (American Express via GICC): For possible values see manual Match parameters
TerminalID an8 O ID of the terminal
VUNr n5..12 M Contract partner number
TrxTime an21 M Time stamp of transaction in the format dd.MM.yyyy HH:mm:ssff
AQ an3 M Acquirer shortcode

Additional result parameters for URLNotify, URLSuccess and URLFailure in case of GICC connection

FXC Gateway interface: via Server-to-Server

Chart of process flow via Server-to-Server

For the server-to-server payment processes please refer to the programming basics manual.
Process flow of a payment via server-to-server interface

Call of interface: general parameters

Notice: For credit card payments with 3D Secure, please note the different cases as explained separately in the chapter at the start of the handbook. If the credit card is registered for Verified or SecureCode or SafeKey, the next phase is divided into two steps of authentication and payment. However it always begins in the same way via the direct.aspx interface. The first response however is the receipt of Javascript code or other parameters in order to carry out a second call up of the direct3d.aspx interface. Only after that, do you receive the listed parameter as a response.

To carry out a TLS credit card payment via a Server-to-Server connection, call the following URL:

https://fxcpay.com/direct.aspx

Notice: For security reasons, FXC Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter Format CND Description
MerchantID ans..30 M Merchant ID, assigned by FXC This parameter is to be passed in plain language.
TransID ans..64 M TransactionID which should be unique for each payment
Please note for some connections the different formats that are given within the specific parameters.
Amount n..12 M Amount in the smallest currency unit (e.g. EUR Cent)
Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).
Amount3D n..12 C Only for 3DSecure: Amount for authentication with Verified, SecureCode and SafeKey if Amount deviates. E.g. Customer confirms flight costs of 120 Euros with 'Verified' but the travel agent captures only the booking fee of 20 Euros: Amount3D=12000; Amount=2000. Amount in the smallest currency unit (e.g. EUR Cent)
Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).
Currency a3 M Currency, three digits DIN / ISO 4217
CCNr n..19 M Credit card number at least 12-digit, numerical without spaces. You can optionally transmit also a pseudo card number (PCN)
CCCVC n..4 O Optional, not with ATOS: Card verification number: The last 3 digits on the signature strip of the credit card. 4 numbers in the case of American Express.
CCExpiry n6 M Expiry date of the credit card in the format YYYYMM, e.g. 201707.
CCBrand a..22 M Credit card brand.
Please note the spelling according to table of credit card brands!
Capture ans..6 O Determines the type and time of capture. AUTO: capturing immediately after authorisation (default value). MANUAL: capturing made by the merchant.: Delay in hours until the capture (whole number; 1 to 696).
OrderDesc ans..768 M Description of purchased goods, unit prices etc.
TermURL ans..256 C Only for 3DSecure: URL of the shop which has been selected by the Access Control Server (ACS) of the bank to transmit the result of the authentication. The bank transmits the parameters PayID, TransID and MerchantID via GET and the PAResponse parameter via POST to the TermURL.
UserAgent ans..128 C Only for 3DSecure: Browser type of the purchaser who requests the page. For example: IE Mozilla/4. 0 (compatible; MSIE 6.0; Windows NT 5.0; NET CLR 1.0.3705)
HTTPAccept ans..128 C Only for 3DSecure: MIME types that the customer's client accept. E.g. image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd. ms-powerpoint, application/vnd. ms-excel, application/msword, */*
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
ReqID ans..32 O To avoid double payments, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction is submitted again with the same ReqID, FXC Gateway will not carry out the payment, but will just return the status of the original transaction.

General parameters for credit card payments via socket connection

Parameter Format CND Description
MID ans..30 M MerchantID, assigned by FXC
PayID an32 M ID assigned by FXC Gateway for the payment, e.g. for referencing in batch files
XID an32 M ID for all single transactions (authorisation, capture, credit note) for one payment assigned by FXC Gateway
TransID ans..64 M Merchant's transaction number
Please note for some connections the different formats that are given within the specific parameters.
Status ans..50 M OK or AUTHORIZED as well as FAILED
Description ans..1024 M Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!
Code n8 M Error code according to FXC Gateway Response Codes Excel file.
MAC ans..64   Hash Message Authentication Code (HMAC) with SHA-256 algorithm
PCNr n16 O Pseudo Card Number: Random number generated by FXC Gateway which represents a genuine credit card number. The pseudo card number (PCN) starts with 0 and the last 3 digits correspond to those of the real card number. You can use the PCN like a genuine card number for authorisation, capture and credits.
CCExpiry n6 OC Optional in combination with PCNr: Expiry date of the credit card in the format YYYYMM (201706).
CCBrand a..22 OC Optional in combination with PCNr: Name of credit card brand.
Please noite the spelling according to table of credit card brands!
MaskedPan an..19 OC Masked card number 6X4
AboID ans..32 O For subscriptions: Unique ID assigned by FXC Gateway for the subscription.
CAVV ans..40 O In the case of authentication hosting: Cardholder Authentication Validation Value: Contains the digital signature for authentication with the ACS of the card issuing bank.
ECI n2 O In the case of authentication hosting: ACS E-Commerce indicator: defines the security level of a credit card payment via different communication paths: MOTO, SSL, Verified by Visa etc.
ACSXID ans..40 O Only in the case of 2 / 3, with Authentication Hosting: ID for transaction identification. The ACSXID is transferred with the authorisation to the Acquiring Bank.

General response parameters for credit card payments via socket connection

GICC: Concardis, B+S Card Service, EVO Payments, American Express, Elavon, SIX Payment Service

Besides the general parameters described above

Call of interface: general parameters for the credit card connection, GICC requires the following additional parameters. An authorization with 3D Secure is possible. The following table describes the encrypted payment request parameters:

Parameter Format CND Description
RefNr ns..30 M Merchant's unique reference number
OrderDesc ans..768 M Description of purchased goods, unit prices etc.
CreditCardHolder ans..60 O Name of the card holder
RTF a1 O for repeat payments (subscriptions): I = Initial payment of a new subscription
R = Routine payment (Recurring)
ChDesc an..30 O Text printed on the customer’s credit card bill alongside the payee
AccVerify a3 O If AccVerify=Yes the credit card is checked at the acquirer according to he interface descriptions of the acquirer. The merchant has to submit only this parameter, the "Amount" is optional. If "Amount" is used we replace this value according to the interface description of the acquirer. At the payment always Amount=0 is stored.
Permissiable value: yes
CountryCode a2 O Card holder information: Country
Textfeld1 ans..30 O Card holder information: Name
Textfeld2 ans..30 O Card holder information: City
Contact data/Address verification (AVS)
Parameter Format CND Description
AddrStreet ans..50 O Street name (for AVS)
AddrStreetNr ans..15 O Street number for verification by American Express (for AVS)
AddrZip n10 O Postcode (for AVS)
AddrCity a40 O Town/city (for AVS)
AddrCountryCode a2/a3 M Country code according to ISO-3166-1: it can be transmitted with two or three digits optionally – Format a2 / a3 (for AVS)
AddrStreet2 a..32 O Second street name (for AVS)
AddrStreetNr2 ans..5 O Second street number (for AVS)
AddrZip2 n..5 O Second postcode (for AVS)
AddrCity2 a..32 O Second town/city (for AVS)
AddrChoice n1 O If you transmit 2 street numbers and postcodes, the AddrChoice parameter will determine which address is checked. AddrChoice=1 checks the first address, AddrChoice=2 the second address. (for AVS)

Additional parameters for the credit card connection GICC via FXC Gateway form

The following table gives the result parameters which the FXC Gateway transmits especially for the GICC connection to your URLSuccess or URLFailure and URLNotify. If you have specified the Response=encrypt parameter, the following parameters are sent Blowfish encrypted to your system:

Parameter Format CND Description
Match a1 O Total result of address check (American Express via GICC): For possible values see manual Match parameters
TerminalID an8 O ID of the terminal
VUNr n5..12 M Contract partner number
TrxTime an21 M Time stamp of transaction in the format dd.MM.yyyy HH:mm:ssff
AQ an3 M Acquirer shortcode

Additional result parameters for URLNotify, URLSuccess and URLFailure in case of GICC connection

Capture / Credit / Reversal

Capture

Captures are possible via a Server-to-Server connection. To perform a capture via a Server-to-Server connection please use the following URL:

https://fxcpay.com/capture.aspx

Notice: For security reasons, FXC Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter Format CND Description
MerchantID an..30 M MerchantID, assigned by FXC
PayID an32 M ID assigned by FXC Gateway for the payment to be captured
TransID an..64 M TransactionID which should be unique for each payment.
Please note for some connections the different formats that are given within the specific parameters.
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
Amount n..12 M Amount in the smallest currency unit (e.g. EUR Cent)
Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).
Currency a3 M Currency code, three digits DIN / ISO 4217
RefNr ns..30 C Merchant's reference number (not with EVO Payments, for CardComplete in the format an..25, for Omnipay in the format ns..15)
FinishAuth a1 C Only with ETM: Transmit valuein order to stop the renewal of guaranteed authorizations and rest amounts after partial captures. Please use this parameter only if you are using the additional function ETM (Extended Transactions Managament). (not with Clearhaus)
Textfeld1 an..30 O Card holder information: Name (not with Clearhaus)
an..30 M
Textfeld2 an..30 O Card holder information: City (not with Clearhaus)
CHDesc an..22 OC Only with Clearhaus: Text printed on the customer’s credit card bill. Only printable ASCII characters from 0x20 to 0x7E

Parameters for captures of credit card payments

The following table describes the FXC Gateway response parameters:

Parameter Format CND Description
MID ans..30 M MerchantID, assigned by FXC
PayID an32 M ID assigned by FXC Gateway for the payment, e.g. for referencing in batch files.
XID an32 M ID for all single transactions (authorisation, capture, credit note) for one payment assigned by FXC Gateway
TransID ans..64 M Merchant's transaction number.
Please note for some connections the different formats that are given within the specific parameters.
Status a..50 M OK or FAILED
Description ans..1024 M Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!
Code n8/td> M Error code according to FXC Gateway Response Codes Excel file.
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
RefNr ns..30 C Merchant's reference number (not with EVO Payments, for Card Complete in the format an..25, for Omnipay in the format ns..15)
AID n6 OC Only in the case of Card Complete: Authorization ID returned by Card Complete
Amount n..12 OC Only with Clearhaus: Amount in the smallest currency unit (e.g. EUR Cent)
If the actual amount differs from the requested amount this will be returned.
CodeExt n5 OC Only with Clearhaus: Only if configured: External error code (downstream system)
ErrorText ans.128 OC Only with Clearhaus: Detailed Clearhaus error message.
Is returned only if Status=FAILED. Use is possible only in agreement with FXC Support.
TransactionID ans36 OC Only with Clearhaus: Transaction number from Clearhaus

Response parameters for captures of credit card payments

Credit with reference

Credits (refunds) are possible via a Server-to-Server connection. FXC Gateway permits credits which relate to a capture previously activated by FXC Gateway and allows merchants to carry out credits without a reference transaction. This section describes the processing of credits with reference transactions. If you refer to a capture for a Credit, the amount of the Credit is limited to the amount of the previous capture.

To carry out a credit with a reference transaction, please use the following URL:

https://fxcpay.com/credit.aspx

Notice: For security reasons, FXC Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter Format CND Description
MerchantID ans..30 M MerchantID, assigned by FXC
PayID an32 M ID assigned by FXC Gateway for the payment to be credited
TransID ans..64 M TransactionID which should be unique for each payment.
Please note for some connections the different formats that are given within the specific parameters.
RefNr an..25 C
ans..30 M Only for CardComplete: Merchant's unique reference number
Only with Clearhaus (ns..30, optional): Unique reference number. Only printable ASCII characters from 0x20 to 0x7E
Only with Clearhaus (ns..30, optional): Merchant's unique reference number
MAC an640 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
Amount n..12 M Amount in the smallest currency unit (e.g. EUR Cent)
Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).
Currency a3 M Currency code, three digits DIN / ISO 4217
OrderDesc ans..768 O Description of refunded goods, unit prices, merchant’s comment etc. (not with Clearhaus)
Textfeld1 ans..30 O Card holder information: Name (not with Clearhaus)
Textfeld2 ans..30 O Card holder information: City (not with Clearhaus)
CHDesc ans..22 OC Only with Clearhaus: Text printed on the customer’s credit card bill. Only printable ASCII characters from 0x20 to 0x7E

Parameters for credits of credit card payments

The following table describes the FXC Gateway response parameters:

Parameter Format CND Description
MID ans..30 M MerchantID, assigned by FXC
PayID an32 M ID assigned by FXC Gateway for the payment, e.g. for referencing in batch files.
XID an32 M ID for all single transactions (authorisation, capture, credit note) for one payment assigned by FXC Gateway
TransID an..64 M Merchant's transaction number.
Please note for some connections the different formats that are given within the specific parameters.
Status a..50 M OK or FAILED
Description ans..1024 M Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!
Code n8 M Error code according to FXC Gateway Response Codes Excel file.
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
AID n6 OC Only in the case of Card Complete: Authorization ID returned by Card Complete
RefNr an..25 OC Only for Card Complete: If a RefNr has been transmitted, it is returned.
Only with Clearhaus (Format ans..30): Unique reference number. Only printable ASCII characters from 0x20 to 0x7E
Amount n..12 OC Only with Clearhaus: Amount in the smallest currency unit (e.g. EUR Cent)
If the actual amount differs from the requested amount this will be returned.
CodeExt n5 OC Only with Clearhaus: Only if configured: External error code (downstream system)
ErrorText ans.128 OC Only with Clearhaus: Detailed Clearhaus error message.
Is returned only if Status=FAILED. Use is possible only in agreement with FXC Support.
TransactionID ans36 OC Only with Clearhaus: Transaction number from Clearhaus

Response parameters for credits of credit card payments

Credit without reference

FXC Gateway can carry out Credits which do not relate to a previous capture. In this case the credit must be transferred to FXC Gateway as a completely new payment transaction. Please contact the FXC Helpdesk for help in using the described additional functions.

Notice: Please note that credits without reference to a previous capture generate higher costs with your Acquiring Bank. If you are frequently unable to make reference to the capture you should agree this with your Acquiring Bank.

To carry out a Credit without a reference transaction via a Server-to-Server connection, please use the following URL:

https://fxcpay.com/creditex.aspx

Notice: For security reasons, FXC Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter Format CND Description
MerchantID ans..30 M MerchantID, assigned by FXC
TransID ans..64 M TransactionID which should be unique for each payment.
Please note for some connections the different formats that are given within the specific parameters.
RefNr ns..30 O Merchant's reference number, for CardComplete in the format an..25
Amount n..12 M Amount in the smallest currency unit (e.g. EUR Cent)
Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).
Currency a3 M Currency code, three digits DIN / ISO 4217
CCNr n..16 M Credit card number at least 12-digit, numerical without spaces
CCCVC n..4 O Card verification number: The last 3 digits on the signature strip of the credit card. 4 numbers in the case of American Express.
CCExpiry n6 M Expiry date of the credit card in the format YYYYMM, e.g. 201707.
CCBrand a..22 M Credit card brand.
Please noite the spelling according to table of credit card brands!
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
OrderDesc ans..768 MC Not with Clearhaus: Description of refunded goods, unit prices, merchant's comment etc.
UserData ans..1024 OC Only with Clearhaus: If specified at request, FXC Gateway forwards the parameter with the payment result to the shop.
ReqID ans..32 O To avoid double payments, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction is submitted again with the same ReqID, FXC Gateway will not carry out the payment, but will just return the status of the original transaction.
Textfeld1 ans..32 O Not with Clearhaus: Card holder information: Name
Textfeld2 ans..30 O Not with Clearhaus: Card holder information: City
CHDesc ans..34 OC Only with Clearhaus, format ans..22: Text printed on the customer’s credit card bill. Only printable ASCII characters from 0x20 to 0x7E
Only for Credorax: Text printed on the customer's credit card bill.
This function must be enabled by Credorax and have the following structure.
1) merchant DBA name (up to 20 characters)
2) asterisk
3) additional text (up to 13 characters).
e.g. FXC *Test
This value can be alternatively permanently archived by FXC Support.
CreditCardHolder an..255 MC Only wiht Credorax, ECPCC: Name of the card holder
Email ans..64 Mc Only wiht Credorax, ECPCC: Email address of the customer
IPAddr ans..15 OC Only wiht Credorax, ECPCC: Customer´s IP address
PaymentOfWinnings ans..4 OC
CreditCardHolder ans..32 O In the case of the acquirer EMS (Omnipay) the merchant can control CFT credit notes in this way.
Transfer PaymentOfWinnings=True to credit a win rather than simply repaying a paid amount.

Further address parameters in case of ECPCC connection

Parameter Format CND Description
DateOfBirth n8 O Date of birth of the customer in format YYYYMMDD
Phone n..32 O Customer's phone number
FirstName ans..255 M First name of the customer
LastName ans..255 M Last name of the customer
AddrStreet ans..255 O Street name
AddressAddition ans..255 O Address c/o
AddrZip an..9 O Postcode
AddrCity ans..255 O City
AddrState a2 O Code of the customer's Federal State
AddrCountryCode a2 M Country code according to ISO-3166-1, alphanumeric 2 chars
sdFirstName ans..255 O First name in the delivery address
sdLastName ans..255 O Surname in the delivery address
sdStreet ans..255 O Street name in the delivery address
sdAddressAddition ans..255 O Address addition in the delivery address
sdZIPCode an..9 O Postcode in the delivery address
sdCity ans..255 O Town/city in the delivery address
sdState a2 O Code of Federal State in the delivery address
sdCountryCode a2 O Country code of delivery address according to ISO-3166-1, alphanumeric 2 chars

Parameters for credits of credit card payments without reference

The following table describes the FXC Gateway response parameters:

Parameter Format CND Description
MID ans..30 M MerchantID, assigned by FXC
PayID an32 M ID assigned by FXC Gateway for the payment, e.g. for referencing in batch files.
XID an32 M ID for all single transactions (authorisation, capture, credit note) for one payment assigned by FXC Gateway
TransID ans..64 M Merchant's transaction number.
Please note for some connections the different formats that are given within the specific parameters.
Status a..50 M OK or FAILED
Description ans..1024 M Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!
Code n8 M Error code according to FXC Gateway Response Codes Excel file.
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
AID n6 OC Only in the case of Card Complete: Authorization ID returned by Card Complete
RefNr an..25 OC Only for Card Complete: If a RefNr has been transmitted, it is returned.
Amount n..12 OC Only with Clearhaus: Amount in the smallest currency unit (e.g. EUR Cent)
If the actual amount differs from the requested amount this will be returned.
CodeExt n5 OC Only with Clearhaus: Only if configured: External error code (downstream system)
ErrorText ans.128 OC Only with Clearhaus: Detailed Clearhaus error message.
Is returned only if Status=FAILED. Use is possible only in agreement with FXC Support.
UserData ans..1024 OC Only with Clearhaus: If specified at request, FXC Gateway forwards the parameter with the payment result to the shop.
TransactionID ans36 OC Only with Clearhaus: Transaction number from Clearhaus

Response parameters for credits of credit card payments without reference

Reversal

A credit card authorisation lowers the customer's credit line. FXC Gateway can reverse an authorisation so that it no longer block the limit any more. Use the following URL:

https://fxcpay.com/reverse.aspx


Notice
: For security reasons, FXC Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

Notice: Reverse.aspx does not only reverse authorisations, but any LAST TRANSACTION STAGE! If the last transaction was a capture, Reverse.aspx initiates the reverse, e.g. a credit. Therefore, the utmost caution is urged. Use is at your own risk. We recommend checking the transaction status with Inquire.aspx before using Reverse.aspx.

The following table describes the encrypted payment request parameters:

Parameter Format CND Description
MerchantID ans..30 M MerchantID, assigned by FXC
PayID an32 M FXC Gateway ID for the identification of a payment
ans..30 M
TransID ans..64 M TransactionID which should be unique for each payment.
Please note for some connections the different formats that are given within the specific parameters.
Amount n..12 M Amount in the smallest currency unit (e.g. EUR Cent)
Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).
Currency a3 M Currency code, three digits DIN / ISO 4217
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
RefNr ans..30 OC Only with Clearhaus: Unique reference number. Only printable ASCII characters from 0x20 to 0x7E.

Parameters for reversals of credit card payments

The following table describes the FXC Gateway response parameters:

Parameter Format CND Description
MID ans..30 MC MerchantID, assigned by FXC
PayID an32 M ID assigned by FXC Gateway for the payment, e.g. for referencing in batch files.
XID an32 M ID for all single transactions (authorisation, capture, credit note) for one payment assigned by FXC Gateway
TransID ans..64 M Merchant's transaction number.
Please note for some connections the different formats that are given within the specific parameters.
Status a..50 M OK or FAILED
Description ans..1024 M Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!
Code n8 M Error code according to FXC Gateway Response Codes Excel file.
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm
RefNr an..25 OC Only for Card Complete: If a RefNr has been transmitted, it is returned.
Only with Clearhaus, format ans..30: Unique reference number. Only printable ASCII characters from 0x20 to 0x7E
AID n6 OC Only in the case of Card Complete: Authorization ID returned by Card Complete
CodeExt n5 OC Only with Clearhaus: Only if configured: External error code (downstream system)
ErrorText ans.128 OC Only with Clearhaus: Detailed Clearhaus error message.
Is returned only if Status=FAILED. Use is possible only in agreement with FXC Support.
TransactionID ans36 OC Only with Clearhaus: Transaction number from Clearhaus

Response parameters for reversals of credit card payments

Reversal of an authorisation extension

A credit card authorisation is valid for only 7 to 30 days. In order to maintain your payment claim in the case of longer delivery times, FXC Gateway enables the automatic renewal of the authorisation. Renewal of the authorisation is also important for instalments or partial deliveries because the outstanding amount is invalid in the case of partial captures.

If you use authorisation renewal, FXC Gateway renews your authorisations until the payment has been captured fully. Amongst other things the customer's card limit is reduced by the authorised amount. In order to restore the card limit again, for example because the order cannot be fully delivered, you need to specifically cancel the authorisation renewal with the following URL:

https://fxcpay.com/cancelAuth.aspx


Notice: CancelAuth cancels only the recurrence of the authorisation. If you wish to unblock the customer's card limit, please reverse the authorisation in accordance with the section above.

Notice: For security reasons, FXC Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter Format CND Description
MerchantID ans..30 M MerchantID, assigned by FXC
PayID an32 M ID assigned by FXC Gateway for the payment, e.g. for referencing in batch files.
TransID ans..64 M TransactionID which should be unique for each payment
MAC an64 M Hash Message Authentication Code (HMAC) with SHA-256 algorithm

Parameters for reversal of an authorisation extension

The following table describes the FXC Gateway response parameters:

Parameter Format CND Description
MID ans..30 M MerchantID, assigned by FXC
PayID an32 M ID assigned by FXC Gateway for the payment, e.g. for referencing in batch files.
TransID ans..64 M Merchant's transaction number
Status a..50 M OK or FAILED
Description ans..1024 M Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!
Code n8 M Error code according to FXC Gateway Response Codes Excel file.

Result parameters for reversals of an authorisation extension

Paynow

Silent Mode for credit cards with SSL and 3D Secure processing

The PayNow solution links the benefits of FXC Gateway forms and Server-to-Server connections: As opposed to the FXC Gateway form, where the form is loaded from the FXC Gateway server via calling payssl.aspx the PayNow form has to be provided by the merchant's system. The form uses the same parameters as described here in the image to the right.

In contrast to the FXC Gateway form the parameters are not forwarded as URL parameters as in the case when calling payssl.aspx, but as form input parameters.

After the customer has entered his credit card data, the payment data is forwarded to the PayNow page, where the further payment processing takes place incl. 3D-Secure. The form details must be directly forwarded to the PayNow page and may not be transmitted to the merchant's system! Also, no PCI-relevant data may be transmitted to the PayNow page as additional input parameters!

Notice: Please note, that automatic retry attempts at the FXC Gateway must be deactivated when using the Paynow.aspx. The background is that at a retry attempt FXC Gateway cannot send back the customer to the previously used special shop form. Please contact the FXC Support to deactivate the retry attempts.

The credit card data must be transmitted to paynow.aspx with the following parameters:

Parameter Format CND Description
CCNr n.16 M Credit card number at least 12-digit, numerical without spaces
CCCVC n3 O Card verification number: the last three digits on the signature strip of the credit cardCCCVC
CCExpiry n6 M Credit card expiry date in the format YYYYMM, e.g. 201807
CCBrand a..22 M Credit card brand.
Please noite the spelling according to table of credit card brands!

PayNow parameters for 3D Secure processing

PayNow
<form action=paynow.aspx> <input type="hidden" name="MerchantID" value=[mid]> <input type="hidden" name="Len" value=[len]> <input type="hidden" name="Data" value=[data]> : </form>
FXC Gateway form
payssl.aspx?MerchantID=[mid]&Len=[len]&Data=[data]

The Foreign Exchange Module

Authentication

Interfacing with any of the exposed API endpoints requires the requesting application to have gone through the authentication process.

API Keys are generated and assigned to each client's integrated application and are used during the authentication process.

The MerchantID and API Key values are the parameters used in the authentication process. Merchant administrator can manage their integrated applications in the FXC Gateway's Web Portal.

Endpoint Details

Type Externally facing RESTful Web API Endpoint.
Method GET
URL https://api.fxcpay.com/auth

Input Parameter(s)

Field Name Data Type Description
MerchantID String The Merchant ID assigned to the client. The MerchantID value will be the same across all applications.
ApiKey String The API Key assigned to the client application in the Web Portal

Example Request

https://api.fxcpay.com/auth?MerchantID=5asds5s68asdf5cvx123zefsa98&ApiKey= VG0RQ7L9A13NF7LSH031N0D9OY1WKOGIA10YGB7ITI320

Response(s)

Response Code Description
200 - OK Successful Auth process, therefore an Auth-Token is returned for subsequent requests.
Note: Auth-Token is valid for 2 hours.
Json Response Body:
"{ Auth-Token: eyJ0eXAiOiJKV1QiL CJhbGciOiJIUzI1NiJ9. eyJBdXRoTG9nIjoiNTlhNzQ1MDZmO Tc2ZTBjMjljMDM0ZWNlIiwiTWVyY2 hhbnRJRCI6IjU5OTMwMjY xZjk3NmUwNTQ5YzlkNjk4OSIsIkV4cG lyeVRpbWVzdGFtcCI6IjIwMTctMDgtMzEg MDY6MDY6NDYgR01UKzAyOjAwI n0.1Cm7CbUYtRx ZvaPKWn_STxTbzP9FYpVYmDeb-1xkijQ }"
202 - Accepted Unsuccessful Authentication.
Response body:
Authentication Failed.

Output Field(s)

Field Name Data Type Description
Auth-Token String Json Web Token (Jwt) to be used in subsequent requests to the API.

API Requests after Authentication

Every subsequent request to the API should have the Auth-Token in the HTTP Header.

HTTP Header
Auth-Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUz I1NiJ9.eyJBdXRoTG9nIjoiNTlhNzQ1MD ZmOTc2ZTBjMjljMDM0ZWNlIiwiTWVyY2hh bnRJRCI6IjU5OTMwMjYxZjk3NmUwNTQ5Yz lkNjk4OSIsIkV4cGlyeVRpbWVzdGFtcCI6IjI wMTctMDgtMzEgMDY6MDY6NDYgR01UKzA yOjAwIn0.1Cm7CbUYtRxZvaPKWn_STx TbzP9FYpVYmDeb-1xkijQ

Retrieving rates

The Foreign Exchange module provides FX Quotes for base currencies that have been setup for the client during initial registration.

The GetFXQuote endpoint returns FX quote objects to the requesting client application. The retrieved FX Quote is generated based on the currency pair requested as per the currency pair catalogue in the later section of the document.

Endpoint Details

Type Externally facing RESTful Web API Endpoint.
Method GET
URL https://api.fxcpay.com/getfxquote

Input Parameter(s)

Field Name Data Type Description
BaseCurrency String Base currency to be used
ExchangeCurrency String Exchange currency sought after (that a customer would like to use for payment)
FxTransactionType String Transaction type in question (Sale/Refund)

Example Request

https://api.fxcpay.com/getfxquote? BaseCurrency={BaseCurrency}&ExchangeCur rency={ExchangeCurrency}&fxTransac tionType={fxTransactionType}

Request Validation Rules

  • Auth-Token must be present in the HTTP Request Header.
  • Auth-Token must be valid.
  • Auth-Token must not have expired.
  • The currency pair requested must be available in the catalogue.

Response(s)

Response Code Description
200 - OK Successful FX Quote request will return a quote Json object.
Json Response Body:
{
   "FXQuoteID": "59a740ecf976e0d5d43653a0",
   "BaseCurrency": "USD",
   "ExchangeCurrency": "ZAR",
   "DateCreated": "2017-08-31 00:49:16 GMT+02:00",
   "ExpiryDate": "2017-08-31 08:00:46 GMT+02:00",
   "QuoteType": "Ask",
   "Rate": "19.1215",
   "QuoteInformation": "FX Quote generated for myF1shop",
   "signatureToken": "qVv3leGJISJXf+pW koofxQjRb2RYwsZixsHoha+a fiwQEWEC9nZp0J848e oBfpX9ps3BSylYCzIMhEF8f ++fg60VHxgRsakHsz6j+SAqFb XX2/8O3xY+V35Yd368 ghUyhOIab/gp1gm9/20JxNa RdX7bLN7dgBx94u1 CT3PWzB6REokpqSx1dD3fUt 4Cq8cA2voWZMs/g d34MN2dIyweudIj8XMtUSiA8tLNgYtkNilH9rb6Y dzEi0otAsA0QJ1qBnTWJH9ck4cogJsPryZW8a itwaqxU94gpc/53FiqZqIlGP6OioZwJlmUkCe vvIazD8qrxTy+7xnQFF9kcOyleA=="
}
202 - Accepted Unsuccessful request.
Response body will have either of the following:
Authentication Failed.
  • "API Key has expired."
  • "API Key has invalid signature"
  • "Invalid API Key"
  • "No Auth-Token"

Output Field(s)

Field Name Data Type Description
FXQuoteID String FX Quote identifier to be used when submitting an FX Transaction
BaseCurrency String Base currency configured for the client
ExchangeCurrency String Currency to be paid by the customer
DateCreated DateTime FX Quote Creation time stamp
ExpiryDate DateTime Quote expiry time stamp
QuoteType String Currency exchange operation type
Rate Decimal Exchange rate value
QuoteInformation String Message added to FX Quote.
signatureToken String Digital Signature applied to FX Quote.

Currency Catalogue

The following are the supported currencies.

AUD Australian Dollars JPY Japanese Yen
CAD Canadian Dollars NOK Norwegian Krona
CHF Swiss Francs NZD New Zealand Dollars
DKK Danish Krona SEK Swedish Krone
EUR Euro SGD Singapore Dollars
GBP British Pound USD US Dollars
HKD Hong Kong Dollars ZAR South African Rand

The currency pairs supported by the GetFXQuote endpoint are as follows:

AUD-USD EUR-ZAR GBP-USD
EUR-AUD GBP-AUD GBP-ZAR
EUR-CAD GBP-CAD NZD-USD
EUR-CHF GBP-CHF USD-CAD
EUR-DKK GBP-DKK USD-CHF
EUR-HKD GBP-EUR USD-DKK
EUR-JPY GBP-HKD USD-HKD
EUR-NOK GBP-JPY USD-JPY
EUR-NZD GBP-NOK USD-NOK
EUR-SEK GBP-NZD USD-SEK
EUR-SGD GBP-SEK USD-SGD
EUR-USD GBP-SGD USD-ZAR