Integration Guide |
Version 1.0 |
As of 19.03.2020 |
Contents
Document history
Date | Name | Change |
|---|---|---|
19.03.2020 | Peter Posse | Original version |
Card payments integration
General information about card payments
General information
Axepta BNP Paribas's payment platform processes all major cards and currencies worldwide. Card data is protected against unauthorized 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 an authentication feature.
Transaction processing can be made via
- Payment platform forms
- Server-to-server connection
- Batch transfer
3D Secure
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.
Merchants benefit from authentication with 3D Secure because the card schemes provide a liability shift.
From a technical perspective 3D Secure is an authentication process which precedes the payment: Once the card data has been entered, the payment platform checks the identity of the card holder and does not process the payment until the authentication is done.
For further steps it is important to know if the card connection is made via form interface or via Server-to-Server connection. In the first case the payment platform form assumes the further authentication process, with Server-to-Server connection the merchant has to manage the authentication through a separate interface.
Payment page form & card's date are hosted by BNP Paribas (payssl.aspx)
Chart of process flow
Process of a transaction with 3D Secure
- The customer selects the card payment method in the shop and enters the card information.
- The payment platform receives the data and checks, via a connection to the scheme (Visa, MasterCard, Diners, JCB or American Express) whether this card is registered for Verified, SecureCode, Diners ProtectBuy, JCB-Card J/Secure or SafeKey. If the card is not registered a 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 the transaction is using 3DS authentication and a secured payment claim is obtained based on the Liability Shift in case the card holder disputes the payment.
- The payment platform opens a new browser window which connects the customer to its bank. In this window the customer enters the password received by his bank.
If the password is correct, the payment platform obtains a confirmation (as signature). Only after confirmation does the payment platform start the payment and send the transaction with the signature to BNP Paribas.
Request parameters
In order to make a card payment via the payment platform form, go to the following URL:
This section explains the parameters which are the same for each connection. The second table explains all response parameters which are also the same for all card connections.
Notice: For security reasons, the payment platform 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 BNP Paribas. Additionally, this parameter has to be passed in plain language too. |
TransID | ans..64 | M | TransactionID which should be unique for each payment |
Amount | n..10 | 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..10 | 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 the payment platform 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 the payment platform and shop, please use the parameter UserData. |
URLFailure | ans..256 | M | Complete URL which calls up the payment platform 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 the payment platform and shop, please use the parameter UserData. |
Response | a7 | O | Status response sent by the payment platform to URLSuccess and URLFailure, should be encrypted. For this purpose, transmit Response=encrypt parameter. |
URLNotify | ans..256 | M | Complete URL which the payment platform 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..1024 | O | If specified at request, the payment platform 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. <Number>: 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, the payment platform 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 |
AccVerify | a3 | = | If AccVerify=Yes the card will be checked at the acquirer according to the acquirer’s interface description. The merchant has to submit only this parameter, the parameter "Amount" is optional. If "Amount" is used, we replace the amount according to acquirer’s interface description. At payment always Amount=0 is stored. Allowed value: yes |
RTF | a1 | O | for repeat payments (subscriptions): I = Initial payment of a new subscription R = Routine payment (Recurring) |
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 BNP template, please transfer the template name “ct_compatible”. If you want to use the responsive BNP template for mobile devices, please transfer the template name “ct_responsive”. |
Language | a2 (enum) | O | Language code: <de> German, <al> Albanian, <at> Austrian, <cz/cs> Czech, <dk> Danish, <en> English, <fi> Finish, <fr> French, <gr> Greek, <hu> Hungarian, <it> Italian, <jp> Japanese, <nl> Dutch, <no> Norwegian, <pl> Polish, <pt> Portuguese, <ro> Romanian, <ru> Russian, <es> Spanish, <se> Swedish, <sk> Slovakian, <sl> Slovenian, <tr> Turkey, <zh> Simplified Chinese. No details mean the language is German. |
CCSelect | a..16 | O | Determines preselected card type in the form |
URLBack | ans..256 | O | URL for "Cancel" button |
CustomField[n] | ans..50 | O | Field that can be used individually by the merchant. Presently 9 fields from CustomField1 to CustomField9 are supported. |
The following table describes the result parameters that the payment platform 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 | ID of merchant, assigned by BNP |
PayID | an32 | M | ID assigned by the payment platform 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 the payment platform |
TransID | ans..64 | M | Merchant’s transaction number |
RefNr | ns..30 | O | Merchant’s unique reference number |
Status | a..50 | M | OK or AUTHORIZED (URLSuccess) as well as FAILED (URLFailure) |
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 the payment platform Response Codes Excel file |
MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm |
UserData | ans..1024 | O | If specified at request, the payment platform forwards the parameter with the payment result to the shop |
PCNr | n16 | O | Pseudo Card Number: Random number generated by the payment platform which represents a genuine 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 | a..22 | OC | In combination with PCNr: Designation of card brand Please note the spelling! According to table of card brands! |
CCExpiry | n6 | OC | In combination with PCNr: Expiry date of the 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 | For 3D Secure: ACS E-Commerce indicator: defines the security level of a card payment via different communication paths: MOTO, SSL, Verified by Visa etc. |
DDD | a1 | C | for 3D Secure Authentication Hosting: Y - fully authenticated (complete authentication done) N - not enrolled (checked, but Issuer does not participate) U - uneledgeble (technical error) A – attempt (card does not participate) B – bypass (bypass, only for Cardinal Commerce) |
Type | ans..20 | C | For 3D Secure in the response to URLSuccess and 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. |
The decrypted payment platform response within the Data parameter looks like this:
PayID=a234b678e01f34567090e23d567890ce&XID=50f35e768edf34c4e090e23d567890ce&Trans ID=100000001&Status=AUTHORIZED&Description=AUTHORIZED&Code=00000000
Payment page form is hosted by the merchant & card's data are hosted by BNP Paribas (paynow.aspx)
Same 3DS Process as for re direct.
Silent order post links the benefits of the payment platform forms and Server-to-Server connections: AS opposed to the payment platform form, where the form is loaded from the payment platform server by calling payssl.aspx, the Silent order post form has to be provided by the merchant’s system. The form uses the same parameters as described here below.
In contrast to the payment platform form, the parameters are not forwarded as URL parameters as is the case when calling the payssl.aspx, but as form input parameters.
Payssl.aspx | Paynow.aspx |
|---|---|
payssl.aspx?MerchantID=[mid]&Len=[len]&Data=[data] | <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> |
The card data must be transmitted to paynow.aspx with the following parameters:
Parameter | Format | CND | Description | |
|---|---|---|---|---|
CCNr | n..16 | M | card number at least 12-digit, numerical without spaces | |
CCCVC | n3 | O | Card verification number: The last 3 digits on the signature strip of the card | |
CCExpiry | n6 | M | Expiry date of the card in the format YYYYMM, e.g. 201807 | |
CCBrand | a..22 | M | Designation of card brand. Please note the spelling! According to table of card brands | |
After the customer has entered his card data, the payment data is forwarded to the Silent order post page, where the further payment processing takes place via 3D-Secure. The form details must be directly forwarded to the Silent order post page and may not be transmitted to the merchant’s system! Also, no PCI-relevant data may be transmitted to the Silent order post page as additional input parameters!
Notice: Please note, that automatic retry attempts at the payment platform must be deactivated when using the Paynow.aspx. The background is that at a retry attempt, the payment platform cannot send back the customer to the previously used special shop form. Please contact the BNP Paribas Support to deactivate the retry attempts.
HTML form example:
Payment page form & card's data are hosted by the merchant (Server-to-Server)
Chart of process flow via Server-to-Server
Process of a transaction with 3D Secure via Server-to-Server connection
To carry out authentication, the payment platform 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.
In the next steps, there are two different cases in which the payment platform responds:
- Case 1: card registered for a 3D Secure system with a pop-up payment page
If the card is registered for Verified or SecureCode, ProtectBuy, J/Secure or SafeKey, the payment platform 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 the payment platform 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 2 describes an alternative in the form of an iFrame variant.
The following example 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> |
Notice: You can also use this code if you only want to verify the identity of the card holder without making a card payment. Our Support team can set your account in a way that the payment platform 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 via POST to the following URL:
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 2: card registered for a 3D Secure system with an iFramed payment page
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, the payment platform returns the following parameters via the socket connection.
Parameter | Format | CND | Description | ||
|---|---|---|---|---|---|
ACSURL | ans.. | C | Only in the case of registered 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 the payment platform 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 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> |
Notice: You can also use this code if you only want to verify the identity of the card holder without immediately making a card payment (Authentication Hosting). BNP Paribas Support can configure your checkout so that the payment platform 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:
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.
Call of interface: general parameters
Notice: For card payments with 3D Secure, please note the different cases as explained separately in the previous chapter. If the 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 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, you receive the listed parameter as a response.
To carry out a TLS card payment via a Server-to-Server connection, call the following URL:
Notice: For security reasons, the payment platform 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. 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. | |
RefNr | ns..30 | O | Merchant’s unique reference number | |
Amount | n..10 | 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..10 | 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 | |
CCNr | n..19 | M | Card number at least 12-digit, numerical without spaces. You can optionally transmit also a pseudo card number (PCN) | |
CCCVC | n..4 | O | Card verification number (CVV): for Visa and MasterCard the last 3 numbers on the signature strip of the card. For American Express the last 4 numbers. | |
CCExpiry | n6 | M | In combination with TOKEN: Expiry date of the card in the format YYYYMM (201706). | |
CCBrand | a..22 | M | Designation of card brand. Please note the spelling! According to table of 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. <Number>: 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. Shop URL selected by the ACS (Access Control Server) of the cardholder’s bank for the transmission of authentication result. The bank transmits the following parameters: PayID, TransID and MerchantID via GET et the parameter PAResponse via POST to the TermURL. | |
UserAgent | ans..128 | C | Only for 3DSecure. User’s browser type calling the page. For exemple: 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 merchant's clients accept. E.g. image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd. ms-powerpoint, ap-plication/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, the payment platform will not carry out the payment, but will just return the status of the original transaction. | |
AccVerify | a3 | O | If AccVerify=Yes the card will be checked at the acquirer according to the ac-quirer’s interface description. The merchant has to submit only this parameter; the parameter "Amount" is optional. If "Amount" is used we replace the amount according to acquirer’s interface description. At payment always Amount=0 is stored. Allowed value: yes | |
RTF | a1 | O | For regular payment (Subscription) : I = Initial payment for the new subscription R = Recurring payment | |
The following table gives the parameters with which the payment platform responds:
Parameter | Format | CND | Description |
|---|---|---|---|
MID | ans..30 | M | MerchantID |
PayID | an32 | M | ID assigned by the payment platform for the payment, e.g. for referencing in batch files |
XID | an32 | M | ID for all single transactions (authorisation, capture, refund note) for one payment assigned by the payment platform |
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 | 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 the payment platform Response Codes |
MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm |
PCNr | n16 | O | TOKEN (Pseudo Card Number): Random number generated by the payment platform which represents a genuine card number. The TOKEN (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 refunds. |
CCExpiry | n6 | OC | In combination with TOKEN: Expiry date of the card in the format YYYYMM (201706). |
CCBrand | a..22 | OC | In combination with PCNr: Designation of card brand Please note the spelling! According to table of card brands! |
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 | For 3D Secure: ACS E-Commerce indicator: defines the security level of a card payment via different communication paths: MOTO, SSL, Verified by Visa etc. |
DDD | a1 | C | For 3D Secure Authentication Hosting: Y - fully authenticated (complete authentication done) N - not enrolled (checked, but Issuer does not participate) U - uneledgeble (technical error) A – attempt (card does not participate) B – bypass (bypass, only for Cardinal Commerce) |
ACSXID | ans..40 | O | Only for cases 2 and 3 (with pop up and without pop up: page 31 and 32 of this guide) with hosting authentication: ID to identify the transaction. The ACSXID is transferred with the authorisation to the acquirer |
Payment via batch
This section describes the parameters that must be transferred within the data set (Record) for executing a card payment and which information can be found within the response file about the payment status.
The structure for a card payment within a Batch file to be submitted is the following:
HEAD,<MerchantID>,<Date>,<Version> CC,Authorize,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>, [<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<Zone>] CC,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>,[<FinishAuth,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>] CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>, [<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>,<Zone>] CC,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID>[,<FinishAuth>,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>] CC,CreditEx,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>, [<CCCVC>,]<CCExpiry>,<OrderDesc>[,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder>] CC,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>),<PayID> FOOT,<CountRecords>,<SumAmount> |
Example for batch versions:
Version 1.2: CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc> CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<cardholder> Version 1.21: CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<approvalcode>,<cardholder> Version 1.3: CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCCVC>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF> Version 1.5: CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<Zone> |
The following table describes the individual fields and values used within the data set (record) in the batch file:
| Parameter | Format | CND | Description |
|---|---|---|---|
Type | a..11 | M | HEAD for Header, FOOT for Footer, CC for card |
Action | a..20 | M | The parameter Action defines the type of transaction: Authorize (authorisation) Capture Sale Credit CreditEx (credit note without previous capture; please agree this with Support beforehand) Reverse (cancellation) |
Amount | n..10 | 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 |
TransID | ans..64 | M | TransactionID which should be unique for each payment |
RefNr | ns..30 | O | Merchant’s unique reference number, which serves as payout reference |
PayID | an32 | M | ID for this transaction given by the payment platform |
OrderDesc | ans..127 | O | Description of purchased goods, unit prices etc. |
CCBrand | a..22 | C | Card brand. Please note the spelling! According to table of card brands! |
CCNr | n..16 | C | Card number at least 12-digit, numerical without spaces. You can optionally transmit also a pseudo card number (PCN) |
PCNr | n..16 | O | You can optionally transmit also a pseudo card number (PCN) instead of the real card number |
CCCVC | n..4 | O | Card verification number in Version 1.3: In the case of Visa and MasterCard the last 3 numbers on the signature strip of the card. 4 numbers in the case of American Express. |
CCExpiry | n6 | O | Expiry date of the card in the format YYYYMM, e.g. 201707. |
FinishAuth | ans1 | O | Version=1.4: If using the authorisation renewal, cancel repeat with the value Y in the field FinishAuth in the case of Capture or Credit. Example: You capture a partial delivery. The rest of the order cannot be supplied. You therefore enter Y in the FinishAuth field for Part-capture so that the payment platform does not authorise the remaining amount. Please note for this also the following section about Cancel authorisation renewals. |
The following table describes the response parameters which the batch Manager saves in the “Record” area for each transaction (standard parameters not explained here, such as <TransID> or <RefNR> and request parameters are returned unchanged and correspond to the call as specified before):
| Parameter | Format | CND | Description |
|---|---|---|---|
Action | a..20 | M | The parameter Action defines the type of transaction like capture or credit – see above. |
PayID | an32 | M | ID for this transaction given by the payment platform |
Status | a..50 | M | OK or FAILED |
Code | n8 | M | Error code according to the payment platform Response Codes Excel file |
PCNr | n..16 | C | The Pseudo Card Number is only returned in the case of transaction types Authorize or Sale & CreditEx. It starts with 0 and the last 3 digits correspond to those of the real card number. |
Card payments management
Capture
The merchant can choose one of these different options of capture:
- Manual capture
- Automatic capture
- Automatic capture with customized delay (number from 1 to 696)
When choosing the manual mode, it’s necessary for the merchant to validate manually each transaction. A transaction must be validated before 7 days. Captures are possible via a Server-to-Server connection. To perform captures via a Server-to-Server connection please use the following URL:
https://paymentpage.axepta.bnpparibas/capture.aspx
When choosing the automatic, capture is made every day at the end of the day.
When choosing the automatic mode with customized delay, the merchant sets a delay in hours (from 1 to 696) that corresponds to the frequency of capture
Notice: For security reasons, the payment platform 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, |
PayID | an32 | M | ID assigned by the payment platform for the payment, |
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. |
MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm |
Amount | n..10 | 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, three digits DIN / ISO 4217 |
RefNr | ns..30 | C | Merchant's reference number |
Textfeld1 | ans..30 | O | Card holder information: Name |
Textfeld2 | ans..30 | O | Card holder information: City |
The following table describes the payment platform‘s response parameters:
| Parameter | Format | CND | Description | |||
|---|---|---|---|---|---|---|
MID | ans..30 | M | MerchantID | |||
PayID | an32 | M | ID assigned by the payment platform for the payment, e.g. for referencing in batch files. | |||
XID | an32 | M | ID for all single transactions (authorisation, capture, refund) for one payment assigned by the payment platform | |||
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 the payment platform Response Codes Excel file | |||
MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm | |||
RefNr | An..12 | C | Merchant's reference number | |||
Partial captures are also possible by setting the « Amount » parameter with the partial amount to capture.
Cancellation
Cancellation function allows to cancel a transaction before it gets captured.
BNP Paribas manages the cancellation requests by proceeding to 2 verifications:
- The amount: It’s forbidden to cancel an amount that is superior to the initial amount of the transaction.
- Payment capture time: Once a payment is captured, it can’t be cancelled anymore.
To make a cancellation, use the following URL:
https://paymentpage.axepta.bnpparibas/reverse.aspx
Notice: For security reasons, the payment platform rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.
Notice: Reverse.aspx does not only reverse authorizations, but any last transaction stage. If the last transaction was a capture, Reverse.aspx initiates the reverse, e.g. a refund. 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 |
PayID | an32 | M | the payment platform ID for the identification of a payment |
TransID | an.. ans..64 | M | TransactionID which should be unique for each payment. |
Amount | n..10 | 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 |
The following table describes the payment platform response parameters:
| Paramater | Format | CND | Description | |||
|---|---|---|---|---|---|---|
MID | ans..30 | MC | MerchantID | |||
PayID | an32 | M | ID assigned by the payment platform for the payment, e.g. for referencing in batch files. | |||
XID | an32 | M | ID for all single transactions (authorisation, capture, refund) for one payment assigned by the payment platform | |||
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 the payment platform Response Codes Excel file | |||
MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm | |||
Refunds
Refunds allow to re-credit a customer who was previously debited (product not delivered, product damaged, product sent back…). The customer’s bank account is credited with the exact amount as the debit amount of the merchant. The merchant can refund a customer until 12 months following the purchase.
Refunds are not permitted for unpaid transactions.
Refunds are possible via a Server-to-Server connection. The payment platform permits refunds which relate to a capture previously activated by the payment platform and allows merchants to carry out refunds without a reference transaction. This section describes the processing of refunds with reference transactions. If you refer to a capture for a refund, the amount of the refund is limited to the amount of the previous capture.
To carry out a refund with a reference transaction, please use the following URL:
https://paymentpage.axepta.bnpparibas/credit.aspx
Notice: For security reasons, the payment platform 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, |
PayID | an32 | M | ID assigned by the payment platform for the payment, |
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. |
MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm |
Amount | n..10 | 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, three digits DIN / ISO 4217 |
OrderDesc | ans..768 | O | Merchant's reference number |
Textfeld1 | ans..30 | O | Card holder information: Name |
Textfeld2 | ans..30 | O | Card holder information: City |
The following table describes the payment platform response parameters:
| Parameter | Format | CND | Description | |||
|---|---|---|---|---|---|---|
MID | ans..30 | M | MerchantID | |||
PayID | an32 | M | ID assigned by the payment platform for the payment, e.g. for referencing in batch files. | |||
XID | an32 | M | ID for all single transactions (authorization, capture, refund) for one payment assigned by the payment platform | |||
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 | |||
Code | n8 | M | Error code according to the payment platform Response Codes Excel file | |||
MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm | |||
One click / wallets
One Click payment can be handled via Tokenization. The token provides merchant with a fully-fledged replacement for the card’s number. The token is generated by the platform but retains the same options and functions as the real card number. This enables merchants to avoid the process of obtaining PCI DSS (Payment Card Industry Data Security Standard) certification.
There is also an added benefit for returning customers, in that they won't need to re-enter their card details.
One click benefits:
- improving the customer´s journey for recurring buyers
- favors impulsive purchases at the same time
The merchant can use the parameter PCNr to make enable 1-Click payments. This could be possible with the CB2A protocol, if they can handle:
- an original transaction is needed for the TOKEN to be generated
- reception of the TOKEN from BNP Paribas in the response sent by the payment platform
Recurring payment (subscription)
Recurring payment allows automatic payments to be made at regular time intervals. When a user makes a subscription, there is a parameter that will be automatically defined when sending payment requests; it is the RTF parameter which will have two possibilities:
- I = Initial payment to initiate a subscription.
- R = Recurring payment.