Contents
| Table of Contents |
|---|
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:
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, assigned by BNP | ||
PayID | an32 | M | ID assigned by the payment platform for the payment | ||
TransID | ans..64 | M | TransactionID which should be unique for each payment | ||
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 | an12 | OC | Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional settlement file we cannot add the additional payment data. Notes:
| ||
MerchantID | ans..30 | M | Merchant ID, assigned by BNP | ||
PayID | an32 | M | ID assigned by the payment platform for the payment | ||
TransID | ans..64 | M | TransactionID which should be unique for each payment | ||
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 | ||
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. Please note that the payment platform must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly. | ||
| FinishAuth | a1 | C | Only with ETM: Transmit value <Y> in order to stop the renewal of guaranteed authorisations and rest amounts after partial captures. Please use this parameter only if you are using the additional function ETM (Extended Transactions Managament). | ||
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 | |||
|---|---|---|---|---|---|---|
| RefNr | an12 | OC | Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional settlement file we cannot add the additional payment data. Notes:
| |||
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 | |||
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 | |||
RefNr | an12 | OC | Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional settlement file we cannot add the additional payment data. Notes:
| |||
Partial captures are also possible by setting the « Amount » parameter with the partial amount to capture in the payment request, or via the back office by visualizing the transaction details then setting 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:
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.
(Further information about inquire.aspx you can find within the documentation Status requests.)
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 | 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 | ||
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. Please note that the payment platform must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly. |
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 | |||
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:
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 |
|---|---|---|---|
| RefNr | an12 | OC | Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional settlement file we cannot add the additional payment data. Notes:
|
MerchantID | ans..30 | M | Merchant ID, assigned by BNP |
PayID | an32 | M | ID assigned by the payment platform for the payment |
TransID | ans..64 | M | TransactionID which should be unique for each payment |
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 |
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. Please note that the payment platform must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly. |
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 | |||||
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 | |||||
Refunds without reference
The Payment platform can carry out Credits which do not relate to a previous capture. In this case the credit must be transferred to Payment platform as a completely new payment transaction. Please contact the BNP 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:
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, assigned by BNP | |||||||
TransID | ans..64 | M | TransactionID which should be unique for each payment | |||||||
| RefNr | an12 | OC | Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional settlement file we cannot add the additional payment data. Notes:
| whitespace
| underscore
| |||||
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 | |||||||
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 note the spelling! According to table of credit card brands! | |||||||
OrderDesc | ans..768 | O | Description of purchased goods, unit prices etc. | |||||||
| ReqID | an..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. Please note that the payment platform must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly. | |||||||
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, 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 (authorization, 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 | |||
One click / wallets
One-click payment can be carried out via tokenization. The token provides to the merchant a full card number substitute. The token is generated by the platform, but has the same options and functions as the real card number. This allows merchants to avoid the need for PCI DSS (Payment Card Industry Data Security Standard) certification.
The recurring customer does not have to re-enter their card details and the merchant can therefore offer a smooth and simple shopping experience to their customers and increase their conversion rate.
To do so, the merchant must use the PCNr (Pseudo Card Number) parameter to authorize one-click payments. This is possible with the CB2A protocol. This parameter is among the parameters in the response received from the payment platform. Please note that a first transaction is necessary to generate the PCNr token that you can store and use for the next payment. This first transaction can be done via the payment page. The second transaction is done via a server-to-server connection.
Recurring payment (subscription)
Recurring payment allows you to make automatic payments at regular intervals. When a user chooses to sign up for a subscription, there is a parameter that will be automatically set when sending payment requests, it is the RTF parameter that will have two possibilities:
- I = Initial payment to initiate a subscription.
- R = Recurring payment.
Pre-Authorization
If a merchant wants to use pre-authorizations, this information should be provided in the onboarding form.
There are two distinct types of pre-authorizations:
- Classic Pre-Authorizations
- PLBS - Pre-Authorizations for Goods and services
Note : A Pre-Authorization can be open for 30 days.
Classic Pre-Authorizations
Normal or classic Pre-Authorization is the standard procedure. That means we receive an estimated amount and perform the authorization, the amount to be captured can be the same or below the pre-authorized amount. After the first capture the remaining amount is currently canceled and can not be used for a following capture.
Steps:
- Merchant does a pre-authorization for the estimated amount (INITIALIZATION OF THE PRE-AUTHORIZATION)
- Merchant settles the transaction with final amount that must be less than or equal to the estimated amount (CLOSING OF THE PRE-AUTHORIZATION)
Example:
You book a hotel for 2 nights and the hotel does a pre-authorization for 200 EUR, you have an emergency and need to leave after only 1 night. The hotel captures 100EUR (1 night) thus closing the transaction.
PLBS (Paiement de Locations de Biens et de Services)
In the case of PLBS we do a pre-authorization for an estimated amount, capture a final amount, if the amount is higher than the estimated amount we need an extra authorization to be done for the new amount. PLBS is limited to specific merchants with specific MCC and has to be agreed with BNP to be activated.
Steps:
- Merchant does a pre-authorization for the estimated amount (INITIALIZATION OF THE PRE-AUTHORIZATION)
- Merchant settles the transaction with final amount that can exceed the estimated amount (CLOSING OF THE PRE-AUTHORIZATION)
- We create/send an extra authorization for the amount exceeding the pre-authorized amount and capture this new amount (ADDITIONAL INVOICE)
You book a hotel for 2 nights and the hotel does a pre-authorization for 200 EUR. You leave and the hotel realizes you emptied the mini bar (price 50 EUR). The hotel is going to create a complementary bill of the amount you owe. The hotels sends a capture of 250 Euros for the room and the mini bar bill. The Payment platform capture the originally pre-authorized amount (200 EURO) for the room. And then created a new authorization, additional billing for the 50 Euro from the mini-bar and capture this additional amount.