Integration

Each credit card has its subscription, meaning there are multiple services supporting credit card payments, one for each type of credit card. However, since all these credit cards work similarly, they are described together here. When referring to generic credit card payment details, we will use "credit card". If something is specific to a single card, the card will be named specifically.

Using the credit card service, a customer can pay using a credit card. The customer is presented with a screen where the credit card information can be provided.

MPI-Enabled Credit Cards

A credit card can be MPI-enabled; in this case, the customer will be redirected to a URL where the 3D Secure info can be provided. After completing this, the payment will proceed. After finishing the payment, the customer will be redirected back to the merchant's website.

The merchant starts by sending the request for a credit card payment to a BPE transaction gateway. The gateway processes the request and sends a response to the merchant. The response will contain a redirect URL to which the customer must be redirected. Once the customer reaches this page, they can enter their credit card details. If the card is not secured with a 3D Secure code, the payment is processed immediately, and the customer will be redirected back to the merchant's website along with the result. If the card is secured with a 3D Secure code, the customer is redirected to the 3D Secure page for their specific credit card, which is an external website of the card issuer. After completing the process on this page, the customer returns to the BPE transaction gateway, and the Payment Engine will process the credit card payment. The customer is then redirected back to the merchant's website along with the payment result. Additionally, the Payment Engine can perform a Transaction Push, updating the status of the payment.

For more information about 3D Secure, click here.

Service Codes and Actions

The following cards are available:

• Credit Cards
  • MasterCard: mastercard
  • Visa: visa
  • American Express: amex
• Debit Cards
  • VPay: vpay
  • Maestro: maestro
  • Visa Electron: visaelectron
  • Carte Bleue: cartebleuevisa
  • Carte Bancaire: cartebancaire
  • Dankort: dankort
  • Nexi: nexi
• Prepaid Cards
  • Postepay: postepay

Below are the available actions. All of them can be sent with the channel 'Web', with one exception: if the credit card acquirer is Worldline, then you should use channel 'Backoffice' for the action "Capture".

• Pay: Let the customer perform the initial payment.
• PayRecurrent: Lets the merchant perform a repeated payment on the initial payment.
• Refund: Performs a refund on an earlier credit card payment.
• Authorize: Makes a reservation on a credit card, so that at a later moment the actual capture can be made without user interaction.
• Capture: Performs a payment using an earlier Authorize.
• PreAuthorizeRecurrent: Lets the merchant reserve (hold) funds on a previously registered card as a Merchant-Initiated Transaction, without the shopper present and without 3-D Secure. The reservation is settled later with a normal Capture.

Merchant-Initiated reservations with PreAuthorizeRecurrent

PreAuthorizeRecurrent lets you reserve funds on a card the shopper has already registered, without the shopper being present and without a 3-D Secure challenge. It is designed for unattended, recurring reserve-and-capture flows such as fuel charging, where an estimated amount is held when service starts and the exact amount is captured when it ends.

How it works

1. Register the card (CIT, once). Send a PreAuthorize with the basic parameter StartRecurrent = true on the "visa" or "mastercard" service. This transaction is authenticated with 3-D Secure, registers the card, starts the recurring mandate, and stores the card's scheme (network) transaction reference. Keep the returned transaction Key.

2. Reserve (MIT, each time). Send a PreAuthorizeRecurrent with the stored Key as OriginalTransactionKey and the amount to hold. Buckaroo reuses the stored credentials and the scheme reference to place the hold — no 3-D Secure, no card data, no shopper interaction. The response carries "Recurring": true and a null PaymentKey.

3. Capture (settle). When the final amount is known, send a Capture whose OriginalTransactionKey is the Key of the PreAuthorizeRecurrent from step 2. Capture the exact amount (full or partial, up to the reserved amount).

   Notes

• The service (visa / mastercard) of the PreAuthorizeRecurrent must match the service of the registering transaction.
• The Capture in step 3 references the PreAuthorizeRecurrent's own Key, not the registering transaction's Key. The PreAuthorizeRecurrent is what holds the funds.
• No 3-D Secure is performed on PreAuthorizeRecurrent because it is merchant-initiated. The cardholder authentication happened once, on the registering transaction in step 1.
• PreAuthorizeRecurrent vs PayRecurrent: both are merchant-initiated recurring charges that reuse the registered card. PayRecurrent takes the money immediately; PreAuthorizeRecurrent only reserves it and requires a later Capture. Choose PreAuthorizeRecurrent when the final amount is not yet known at the time of the charge.