BPE 3.0 Service Creditcards.1.06

1

Version: 1.06

Date: 28 November 2012

Creditcards

Buckaroo Payment Engine 3.0

2

Version history

Version Date Changes

1.00 16-04-2012 Initial release.

1.01 02-05-2012 Added missing information, to complete the manual.

1.02 15-06-2012 Added Refund, Authorize, Capture and CancelAuthorize actions.

1.03 15-07-2012 Added Statuscodes & Transaction types

1.04 19-09-2012 Added Payremainder action

1.05 27-11-2012 Clarifications updated

1.06 28-11-2012 Clarification Visa Electron added

© Buckaroo BV, Netherlands 2012

No part of this document may be reproduced or copied without the express

permission of Buckaroo BV

3

1. Table of Contents

2. OVERVIEW ................................................................................................................. 4

2.1 Introduction ..................................................................................................................................... 4

2.2 Work Flow ....................................................................................................................................... 4

3. SERVICECODES AND ACTIONS ..................................................................................... 5

3.1 Pay ................................................................................................................................................... 5

3.1.1 Request Variables ............................................................................................................................... 5

3.1.2 Response Variables............................................................................................................................. 6

3.1.3 Status Codes ....................................................................................................................................... 6

3.1.4 Transaction Types ............................................................................................................................... 6

3.2 PayRecurrent ................................................................................................................................... 7



3.2.3 Status Codes ....................................................................................................................................... 7


3.3 Refund ............................................................................................................................................. 8



3.3.3 Status Codes ....................................................................................................................................... 8


3.4 Authorize ......................................................................................................................................... 9



3.4.3 Status Codes ..................................................................................................................................... 10

3.4.4 Transaction Types ............................................................................................................................. 10

3.5 Capture .......................................................................................................................................... 10

3.5.1 Request Variables ............................................................................................................................. 11

3.5.2 Response Variables........................................................................................................................... 11

3.5.3 Status Codes ..................................................................................................................................... 11

3.5.4 Transaction Types ............................................................................................................................. 11

3.6 CancelAuthorize ............................................................................................................................ 12

3.6.1 Request Variables ............................................................................................................................. 12

3.6.2 Response Variables........................................................................................................................... 12

4

2. Overview

2.1 Introduction

Starting in BPE 3.0, each credit card has its own subscription. This means that there are multiple services

supporting credit card payment, one for each type of credit card. However, since all these credit cards

work in a similar way, all of them are described together in this document. When talking about generic

credit card payment details, we will use credit card to reference to this. 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 in which the credit card information can be provided.

A credit card can be mpi-enabled; in this case the customer will be redirected to a URL where the

customer can provide the 3D Secure info. After completing this, the payment will proceed. After

finishing the payment, the customer will be redirected back to the web site of the merchant.

2.2 Work Flow

The general flow of a credit card payment is shown in the figure below:

Start

Merchant

BPE Transaction Gateway

Transaction Push

TransactionResponse

3D Secure Page

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. If the request is sent to a

gateway that without a customer redirect, the response will contain a redirect URL to which the

customer must be redirected. If in the original request the customer was already redirected to out

5

public gateway, the customer is automatically redirected to this page by the transaction gateway. Once

the customer reaches this page, he can enter its credit card details. Once these have been entered and

verified and 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 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 its specific credit

card. After completing the process at this page, the customer returns to the BPE transaction gateway,

and the Payment Engine will process the credit card payment, after which the customer is also

redirected back to the merchant website, along with the payment result. Additionally, the Payment

Engine will also perform a Transaction Push, with the status of the payment.

3. Servicecodes and Actions

Each credit card has its own service code, which are specified in the table below:

Credit Card Servicecode

MasterCard mastercard

Visa visa

American Express Amex

Maestro maestro

VPay Vpay

Visa Electron visaelectron

All credit cards support the following actions:

Action Type Description

Pay Primary Let’s the customer perform the initial payment.

PayRecurrent Primary Let’s the merchant perform a repeated payment on the initial payment.

Refund Primary Performs a refund on an earlier credit card payment.

Authorize Primary Makes a reservation on a credit card, so that at a later moment the actual

capture can be made without user interaction.

Capture Primary Performs a payment, using an earlier Authorize.

CancelAuthorize Primary Cancels an earlier Authorize, releasing the reservation on the credit card.

3.1 Pay

The Pay action is the default action. The action is used to perform a single payment with a credit card.

3.1.1 Request Variables

Name Description Type Required

customercode Code chosen by merchant to recognize the

customer of this transaction

String No

StartRecurrent Set this to true when this is the initial

payment for a recurrent payment sequence.

Please note: This is a basic request variable,

not a service specific variable.

Boolean No

(Defaults to false)

6

3.1.2 Response Variables

This action does not have service specific response variables.

3.1.3 Status Codes

The following status codes can be returned in the response to this request:

Type Description

190 Success: the credit card transaction has been completed.

490 Failure: the request failed.

491 Validation Failure: The request contains errors.

492 Technical Error: The request failed due to a technical error (for example a failure in the

credit card processor)

791 Pending Processing: the Payment Engine is processing the transaction.1

690 Rejected: Authorization of the credit card transaction failed.

890 Cancelled by user: The customer cancelled the credit card transaction request.2

During the whole process, the transaction can have additional statuses, normally these are not

communicated back to the merchant website. They can only be encountered when querying manually

for a status or when looking in the plaza. The following additional statuses can be encountered:

Type Description

790 Pending input: the request has been received, possibly the gateway is waiting for the

customer to enter his details.

3.1.4 Transaction Types

The following transaction types are used by pay.

Type Description Service

V030 American Express via OmniPay amex

V031 Mastercard via OmniPay mastercard

V032 Visa via OmniPay visa

V034 Maestro via OmniPay maestro

V035 Visa Electron via OmniPay visaelectron

V036 American Express via American Express amex

V041 Visa Electron via Aexp visaelectron

V042 American Express via PayOn amex

V043 Mastercard via PayOn mastercard

V044 Visa via PayOn visa

V046 Maestro via PayOn maestro

V047 Visa Electron via PayOn visaelectron

V086 VPay via PayOn vpay

1 Only on gateways where the user is not sent to the payment engine with the request.

2 Only on gateways where the user is redirected to the payment engine.

7

3.2 Payremainder

The payremainder action is used to complete a partial payment (For more information, consult the

Partial Payment implementation manual). The Payremainder action uses the same variables,

statuscodes and transaction types as the Pay action.

3.3 PayRecurrent

The PayRecurrent action is used to perform a repeated payment by credit card on an initial payment.

For a recurrent payment, the customer isn’t needed, since the credit card details do not have to be

entered again.



originaltransaction3 Transaction key of the initial payment.



String Yes



3.3.3 Status Codes


Type Description










Type Description



791 Pending Processing: the Payment Engine is processing the transaction.


The following transaction types are used by pay.

3 The original transaction should have the variable ‘StartRecurrent’ set to true.

8








V041 Visa Electron via Aexp visaelectron visaelectron







3.4 Refund

The Refund action can be used to perform a refund on an earlier credit card transaction. There is no

customer interaction needed to do this.



originaltransaction Transaction key of the payment that needs

to be refunded.



String Yes



3.4.3 Status Codes


Type Description

190 Success: the credit card refund has been completed.






9




Type Description





The following transaction types are used by refund.


V066 American Express refund via OmniPay amex

V067 Mastercard refund via OmniPay mastercard

V068 Visa refund via OmniPay visa

V070 Maestro refund via OmniPay maestro

V071 Visa Electron refund via OmniPay visaelectron

V072 American Express refund via American Express amex

V078 American Express refund via PayOn amex

V079 Mastercard refund via PayOn mastercard

V080 Visa refund via PayOn visa

V082 Maestro refund via PayOn maestro

V083 Visa Electron refund via PayOn visaelectron

V085 VPay refund via PayOn Vpay

3.5 Authorize

The Authorize action allows a merchant to make a reservation for a specific amount an a customer’s

creditcard. Referring to this authorization, it is then possible at a later time to perform 1 or more

charges on the customers creditcard for a total of up to the requested amount.

Please note: Since an authorize make a reservation on a credit card, it lowers the available spending

limit on a credit card. Always perform a CancelAuthorize when the reservation is no longer needed.



customercode Code chosen by merchant to recognize the

customer of this transaction

String No



10

3.5.3 Status Codes


Type Description

190 Success: the credit card authorization has been completed.





791 Pending Processing: the Payment Engine is processing the authorization.4


890 Cancelled by user: The customer cancelled the credit card authorization request.5




Type Description




The following transaction types are used by authorize.














3.6 Capture

The Capture action allows the merchant to perform a charge on a previously created authorization. The

customer is not needed to perform this charge. The maximum capture amount is the amount of the

previously requested Authorize, minus any capture amounts previously requested on the same

authorize.

4 Only on gateways where the user is not sent to the payment engine with the request.

5 Only on gateways where the user is redirected to the payment engine.

11



originaltransaction Transaction key of the Authorize on which

this Capture needs to be performed.



String Yes



3.6.3 Status Codes


Type Description










Type Description





The following transaction types are used by capture.








V041 Visa Electron via Aexp visaelectron visaelectron





12



3.7 CancelAuthorize

The CancelAuthorize action releases a reservation made on a creditcard by previously done Authorize.

Since a reservation lowers the spending limit on a customer’s creditcard, authorizations that are no

longer needed should be cancelled.



originaltransaction Transaction key of the Authorize that needs

to be cancelled.



String Yes



Documents

BPE 3.0 Service Creditcards.1.06