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 Name | APM Tag |
|---|---|
| Affin bank | affinbank |
| 7-Eleven | seveneleven |
| AliPay | alipay |
| AmBank | ambank |
| Argencard | argencard |
| AstroPay Card | astropaycard |
| AstroPay Direct | astropaydirect |
| Aura | aura |
| Baloto | baloto |
| Banamex | banamex |
| Banco do Brasil | bancodobrasil |
| Banco de Chile | bancodechile |
| Banco de Occidente | bancodeoccidente |
| Bancomer | bancomer |
| Bank Islam | bankislam |
| Bancontact | bcmc |
| Bitpay | bitpay |
| Blik (direct only) | blik |
| Boleto Bancario | boleto |
| Bradesco | bradesco |
| Cabal | cabal |
| Cartao Mercado Livre | cartaomercadolivre |
| Carulla | carulla |
| Credit/Debit Card | ccauth |
| Credit/Debit Card | ccweb |
| Cencosud | cencosud |
| CIMB Clicks | cimbclicks |
| CMR | cmr |
| Davivienda | davivienda |
| Sofortüberweisung (Direct Pay) | directpay |
| Dragonpay | dragonpay |
| EasyPay | easypay |
| Efecty | efecty |
| Elo | elo |
| Emprese de Energia | empresedeenergia |
| eNETS | enets |
| Entercash | entercash |
| EPS | eps |
| Estonian Banks | estonianbanks |
| Giropay | giropay |
| Hipercard | hipercard |
| Hong Leong Bank | hongleongbank |
| iDEAL | ideal |
| Instant Transfer | instanttransfer |
| International Pay-Outs | int_payout |
| Itau | itau |
| Latvian Banks | latvianbanks |
| Lithuanian Banks | lithuanianbanks |
| Magna | magna |
| Maxima | maxima |
| Maybank2u | maybanktwou |
| Multibanco | multibanco |
| MyBank | mybank |
| MyClear FPX | myclearfpx |
| Naranja | naranja |
| Narvesen | narvesen |
| Nativa | nativa |
| OXXO | oxxo |
| Przelewy24 | p24 |
| Przelewy24 Payout | p24payout |
| Pago Facil | pagofacil |
| PayPost | paypost |
| Paysafe Card | paysafecard |
| Paysbuy | paysbuy |
| Paysera | paysera |
| PayU | payu |
| Perlas Terminals | perlas |
| OLI | poli |
| Presto | presto |
| PSE | pse |
| Pugglepay | pugglepay |
| QIWI | qiwi |
| QIWI Payout | qiwipayout |
| Rapipago | rapipago |
| Redpagos | redpagos |
| RHB Bank | rhbbank |
| SafetyPay | safetypay |
| Santander | santander |
| SEPA DirectDebit | sepadirectdebit |
| SEPA Payout | sepapayout |
| SingPost | singpost |
| Skrill | skrill |
| Surtimax | surtimax |
| Tarjeta Shopping | tarjetashopping |
| Trustly | trustly |
| TrustPay | trustpay |
| Twint | twint |
| UnionPay | unionpay |
| Verkkopankki – Finish Online Banking | verkkopankki |
| Webpay | webpay |
| Yellow Pay | yellowpay |