Skip to main content

Direct Implementation

PPRO transactions require you to redirect your Customer’s browser to the appropriate PPRO APM Checkout as part of the transaction flow. The transaction must be done in two stages with the Checkout being displayed between the stages.

PPRO APM’s support payments made using the SALE action, and the majority support the refunds and partial refunds using the REFUND_SALE action. This section explains how to make payment requests. Refund requests are performed as detailed in the Management Requests section.

Some PPRO APMs may require further payment data which you may send using the checkoutOptions field in your initial request as detailed in the PPRO Checkout Options (Hosted and Direct Integration) section.

Additional information available from a PPRO APM Checkout may be made available in the checkoutDetails and acquirerResponseDetails response fields.

The direct integration uses two complex fields to pass data between the PPRO APM Checkout and the Gateway, the checkoutRequest and checkoutResponse fields.

The checkoutRequest field will optionally be provided by the Gateway and is a record whose name/value properties must be sent to the Checkout, at the provided checkoutURL, via a HTTP POST request. If not provided, then the Checkout can be opened using a normal HTTP GET request.

The corresponding checkoutResponse field will be returned by the Gateway and is a record containing name/value properties received from the Checkout when it redirects the Cardholder’s browser back to the URL provided using the checkoutRedirectURL on completion.

The contents of the checkoutOptions, checkoutDetails, checkoutRequest, checkoutResponse and acquirerResponseDetails fields are formatted using the record format, the checkoutOptions field also supports being provided using the serialised record format.

Payment Request​

To request that a transaction be processed via PPRO the request must contain a paymentMethod of ‘ppro.xxxx’, where ‘xxxx’ is the PPRO APM tag listed in the Payment Method Tags section below.

The request must also have a checkoutRedirectURL containing the URL of a page on your server to return to when the Checkout is closed. In addition, you may send checkoutOptions to provide further fields required by the APM as detailed in the Payment Specific Fields section below.

When the Gateway receives these fields, assuming there are no other errors with the request, it will attempt to find a suitable PPRO Merchant Account in the current account mapping group (Refer to the Merchant Account Routing section).

If the Gateway is unable to find a suitable account, then the transaction will be aborted, and it will respond with a responseCode of 66364 (INVALID PAYMENTMETHOD).

Otherwise, the Gateway will respond with a responseCode of 65826 (CHECKOUT REQUIRED) and included in the response will be a checkoutURL field containing the URL of a PPRO APM Checkout that your Customer’s browser should be redirected to so that the payment may be completed. The response will also contain a unique checkoutRef which is used by the Gateway to identify this checkout session.

On completion of the PPRO APM Checkout it will redirect the browser to the checkoutRedirectURL you provided, complete with information about the payment in a HTTP POST request. The posted data will contain a checkoutResponse field that will contain any specific response data for the payment method.

Payment Specific Fields​

Most of the information required by the PPRO APM Checkout can be supplied using the standard Gateway request fields. However, there may be specific mandatory fields required by a payment method which are not available using the standard fields. In these cases, these fields can be sent in the checkoutOptions data, the value of which must be formatted using the record or serialised record formats.

For example, most European services may require the nationalid and consumerref fields.

Recurring transactions will require the use of iban (optionally sequencetype) and in follow-up payments; mandatereference, mandatesignaturedate, and sequencetype.

These fields are detailed in your PPRO integration guide as SPECIN fields.

Customer support will be able to guide you on any mandatory options as you will find the transaction will fail with a responseCode of 65550 (PROCESSOR_ERROR - Invalid request data) if any are missing.

Payment Method Tags​

To specify which APM is required you need to send the paymentMethod field with a value using the format is ‘ppro.xxxx_’_, where ‘xxxx’ is the APM tag as assigned by PPRO.

For example, to use the APM “AstroPay Card” that has a tag of “astropaycard” (all lowercase), the resulting paymentMethod value be “ppro.astropaycard”.

The table below is a guide to the tag names available. This list is fluid as PPRO add and remove methods.

If you know of a payment method that is not on this list or the payment method cannot be used; please contact customer support for advice.

APM NameAPM Tag
Affin bankaffinbank
7-Elevenseveneleven
AliPayalipay
AmBankambank
Argencardargencard
AstroPay Cardastropaycard
AstroPay Directastropaydirect
Auraaura
Balotobaloto
Banamexbanamex
Banco do Brasilbancodobrasil
Banco de Chilebancodechile
Banco de Occidentebancodeoccidente
Bancomerbancomer
Bank Islambankislam
Bancontactbcmc
Bitpaybitpay
Blik (direct only)blik
Boleto Bancarioboleto
Bradescobradesco
Cabalcabal
Cartao Mercado Livrecartaomercadolivre
Carullacarulla
Credit/Debit Cardccauth
Credit/Debit Cardccweb
Cencosudcencosud
CIMB Clickscimbclicks
CMRcmr
Daviviendadavivienda
Sofortüberweisung (Direct Pay)directpay
Dragonpaydragonpay
EasyPayeasypay
Efectyefecty
Eloelo
Emprese de Energiaempresedeenergia
eNETSenets
Entercashentercash
EPSeps
Estonian Banksestonianbanks
Giropaygiropay
Hipercardhipercard
Hong Leong Bankhongleongbank
iDEALideal
Instant Transferinstanttransfer
International Pay-Outsint_payout
Itauitau
Latvian Bankslatvianbanks
Lithuanian Bankslithuanianbanks
Magnamagna
Maximamaxima
Maybank2umaybanktwou
Multibancomultibanco
MyBankmybank
MyClear FPXmyclearfpx
Naranjanaranja
Narvesennarvesen
Nativanativa
OXXOoxxo
Przelewy24p24
Przelewy24 Payoutp24payout
Pago Facilpagofacil
PayPostpaypost
Paysafe Cardpaysafecard
Paysbuypaysbuy
Payserapaysera
PayUpayu
Perlas Terminalsperlas
OLIpoli
Prestopresto
PSEpse
Pugglepaypugglepay
QIWIqiwi
QIWI Payoutqiwipayout
Rapipagorapipago
Redpagosredpagos
RHB Bankrhbbank
SafetyPaysafetypay
Santandersantander
SEPA DirectDebitsepadirectdebit
SEPA Payoutsepapayout
SingPostsingpost
Skrillskrill
Surtimaxsurtimax
Tarjeta Shoppingtarjetashopping
Trustlytrustly
TrustPaytrustpay
Twinttwint
UnionPayunionpay
Verkkopankki – Finish Online Bankingverkkopankki
Webpaywebpay
Yellow Payyellowpay