Creditcards

Buckaroo Payment Engine 3.0

Version: 1.06 Date: 28 November 2012

Version history
Version 1.00 1.01 1.02 1.03 1.04 1.05 1.06 Date 16-04-2012 02-05-2012 15-06-2012 15-07-2012 19-09-2012 27-11-2012 28-11-2012 Changes Initial release. Added missing information, to complete the manual. Added Refund, Authorize, Capture and CancelAuthorize actions. Added Statuscodes & Transaction types Added Payremainder action Clarifications updated 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

1. Table of Contents 2. OVERVIEW ................................................................................................................. 4

2.1 2.2 Introduction..................................................................................................................................... 4 Work Flow ....................................................................................................................................... 4

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

3.1
3.1.1 3.1.2 3.1.3 3.1.4

Pay ................................................................................................................................................... 5
Request Variables ............................................................................................................................... 5 Response Variables............................................................................................................................. 6 Status Codes ....................................................................................................................................... 6 Transaction Types ............................................................................................................................... 6

3.2
3.2.1 3.2.2 3.2.3 3.2.4

PayRecurrent ................................................................................................................................... 7
Request Variables ............................................................................................................................... 7 Response Variables............................................................................................................................. 7 Status Codes ....................................................................................................................................... 7 Transaction Types............................................................................................................................... 7

3.3
3.3.1 3.3.2 3.3.3 3.3.4

Refund ............................................................................................................................................. 8
Request Variables ............................................................................................................................... 8 Response Variables............................................................................................................................. 8 Status Codes ....................................................................................................................................... 8 Transaction Types ............................................................................................................................... 9

3.4
3.4.1 3.4.2 3.4.3 3.4.4

Authorize ......................................................................................................................................... 9
Request Variables ............................................................................................................................... 9 Response Variables............................................................................................................................. 9 Status Codes ..................................................................................................................................... 10 Transaction Types ............................................................................................................................. 10

3.5
3.5.1 3.5.2 3.5.3 3.5.4

Capture .......................................................................................................................................... 10
Request Variables ............................................................................................................................. 11 Response Variables........................................................................................................................... 11 Status Codes ..................................................................................................................................... 11 Transaction Types ............................................................................................................................. 11

3.6
3.6.1 3.6.2

CancelAuthorize ............................................................................................................................ 12
Request Variables ............................................................................................................................. 12 Response Variables........................................................................................................................... 12

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

Transaction Push

Transaction Response

BPE Transaction Gateway

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 4

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 Visa American Express Maestro VPay Visa Electron mastercard visa Amex maestro Vpay visaelectron

All credit cards support the following actions: Action Pay PayRecurrent Refund Authorize Capture CancelAuthorize Type Primary Primary Primary Primary Primary Primary Description Lets the customer perform the initial payment. Lets the merchant perform a repeated payment on the initial payment. Performs a refund on an earlier credit card payment. Makes a reservation on a credit card, so that at a later moment the actual capture can be made without user interaction. Performs a payment, using an earlier Authorize. 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 customercode StartRecurrent

Description Code chosen by merchant to recognize the customer of this transaction 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.

Type String Boolean

Required No No (Defaults to false)

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 490 491 492 791 690 890 Success: the credit card transaction has been completed. Failure: the request failed. Validation Failure: The request contains errors. Technical Error: The request failed due to a technical error (for example a failure in the credit card processor) Pending Processing: the Payment Engine is processing the transaction.1 Rejected: Authorization of the credit card transaction failed. 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 V030 V031 V032 V034 V035 V036 V041 V042 V043 V044 V046 V047 V086 American Express via OmniPay Mastercard via OmniPay Visa via OmniPay Maestro via OmniPay Visa Electron via OmniPay American Express via American Express Visa Electron via Aexp American Express via PayOn Mastercard via PayOn Visa via PayOn Maestro via PayOn Visa Electron via PayOn VPay via PayOn

Service amex mastercard visa maestro visaelectron amex visaelectron amex mastercard visa maestro visaelectron vpay

1 2

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

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 isnt needed, since the credit card details do not have to be entered again.

3.3.1

Request Variables

Name originaltransaction
3

Description Transaction key of the initial payment. Please note: This is a basic request variable, not a service specific variable.

Type String

Required Yes

3.3.2

Response Variables

This action does not have service specific response variables.

3.3.3

Status Codes

The following status codes can be returned in the response to this request: Type 190 490 491 492 690 Description Success: the credit card transaction has been completed. Failure: the request failed. Validation Failure: The request contains errors. Technical Error: The request failed due to a technical error (for example a failure in the credit card processor) Rejected: Authorization of the credit card transaction failed.

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 791 Pending input: the request has been received, possibly the gateway is waiting for the customer to enter his details. Pending Processing: the Payment Engine is processing the transaction.

3.3.4

Transaction Types

The following transaction types are used by pay.

3

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

Type V030 V031 V032 V034 V035 V036 V041 V042 V043 V044 V046 V047 V086

Description American Express via OmniPay Mastercard via OmniPay Visa via OmniPay Maestro via OmniPay Visa Electron via OmniPay American Express via American Express Visa Electron via Aexp American Express via PayOn Mastercard via PayOn Visa via PayOn Maestro via PayOn Visa Electron via PayOn VPay via PayOn

Service amex mastercard visa maestro visaelectron amex visaelectron visaelectron amex mastercard visa maestro visaelectron vpay

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.

3.4.1

Request Variables

Name originaltransaction

Description Transaction key of the payment that needs to be refunded. Please note: This is a basic request variable, not a service specific variable.

Type String

Required Yes

3.4.2

Response Variables

This action does not have service specific response variables.

3.4.3

Status Codes

The following status codes can be returned in the response to this request: Type Description 190 490 491 492 690 Success: the credit card refund has been completed. Failure: the request failed. Validation Failure: The request contains errors. Technical Error: The request failed due to a technical error (for example a failure in the credit card processor) Rejected: Authorization of the credit card transaction failed.

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 791 Pending input: the request has been received, possibly the gateway is waiting for the customer to enter his details. Pending Processing: the Payment Engine is processing the transaction.

3.4.4

Transaction Types

The following transaction types are used by refund. Type Description V066 V067 V068 V070 V071 V072 V078 V079 V080 V082 V083 V085 American Express refund via OmniPay Mastercard refund via OmniPay Visa refund via OmniPay Maestro refund via OmniPay Visa Electron refund via OmniPay American Express refund via American Express American Express refund via PayOn Mastercard refund via PayOn Visa refund via PayOn Maestro refund via PayOn Visa Electron refund via PayOn VPay refund via PayOn

Service amex mastercard visa maestro visaelectron amex amex mastercard visa maestro visaelectron Vpay

3.5

Authorize
The Authorize action allows a merchant to make a reservation for a specific amount an a customers 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.

3.5.1

Request Variables

Name customercode

Description Code chosen by merchant to recognize the customer of this transaction

Type String

Required No

3.5.2

Response Variables

This action does not have service specific response variables.

3.5.3

Status Codes

The following status codes can be returned in the response to this request: Type Description 190 490 491 492 791 690 890 Success: the credit card authorization has been completed. Failure: the request failed. Validation Failure: The request contains errors. Technical Error: The request failed due to a technical error (for example a failure in the credit card processor) Pending Processing: the Payment Engine is processing the authorization.4 Rejected: Authorization of the credit card transaction failed. Cancelled by user: The customer cancelled the credit card authorization request.5

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.5.4

Transaction Types

The following transaction types are used by authorize. Type Description V048 V049 V050 V052 V053 V054 V060 V061 V062 V064 V065 V084 American Express via OmniPay Mastercard via OmniPay Visa via OmniPay Maestro via OmniPay Visa Electron via OmniPay American Express via American Express American Express via PayOn Mastercard via PayOn Visa via PayOn Maestro via PayOn Visa Electron via PayOn VPay via PayOn

Service amex mastercard visa maestro visaelectron amex amex mastercard visa maestro visaelectron vpay

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 5

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

10

3.6.1

Request Variables

Name originaltransaction

Description Transaction key of the Authorize on which this Capture needs to be performed. Please note: This is a basic request variable, not a service specific variable.

Type String

Required Yes

3.6.2

Response Variables

This action does not have service specific response variables.

3.6.3

Status Codes

The following status codes can be returned in the response to this request: Type Description 190 490 491 492 690 Success: the credit card transaction has been completed. Failure: the request failed. Validation Failure: The request contains errors. Technical Error: The request failed due to a technical error (for example a failure in the credit card processor) Rejected: Authorization of the credit card transaction failed.

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 791 Pending input: the request has been received, possibly the gateway is waiting for the customer to enter his details. Pending Processing: the Payment Engine is processing the transaction.

3.6.4

Transaction Types

The following transaction types are used by capture. Type Description V030 V031 V032 V034 V035 V036 V041 V042 V043 V044 V046 American Express via OmniPay Mastercard via OmniPay Visa via OmniPay Maestro via OmniPay Visa Electron via OmniPay American Express via American Express Visa Electron via Aexp American Express via PayOn Mastercard via PayOn Visa via PayOn Maestro via PayOn

Service amex mastercard visa maestro visaelectron amex visaelectron visaelectron amex mastercard visa maestro 11

V047 V086

Visa Electron via PayOn VPay via PayOn

visaelectron vpay

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 customers creditcard, authorizations that are no longer needed should be cancelled.

3.7.1

Request Variables

Name originaltransaction

Description Transaction key of the Authorize that needs to be cancelled. Please note: This is a basic request variable, not a service specific variable.

Type String

Required Yes

3.7.2

Response Variables

This action does not have service specific response variables.

12