Skip to main content

Digital Wallets and Alternative Payment Methods

Apple Pay / Google Pay

The Gateway supports payments made using the following Digital Wallets, Apple Pay and Google Pay™. These wallets can be used to enhance mobile purchasing experiences for customers with supported devices and produce a payment token which can be passed to the Gateway instead of the Cardholder’s actual card details.

You can use these wallets with any Merchant Account that has been configured to accept them.

For more information on how to accept payment tokens, please contact customer support.

tip

Digital wallet support is not available with all Acquirers and must be enabled on your Merchant Account before they can be used. Please contact support to find out whether your Acquirer supports Digital Wallets and if the functionality can be enabled on your Merchant Account.

Benefits

  • The payment details are stored externally to the Gateway and can be used with any Merchant that supports the appropriate payment tokens.
  • Customers can select from previously stored payment details, making the checkout process more streamlined, resulting in fewer abandoned carts and thus increasing sales.
  • Compatible with existing card base fraud solutions such as Address Verification Service (AVS), 3-D Secure and third-party fraud providers.
  • There are no extra costs to add these payment methods to your Gateway account.
  • The transactions are controlled within the Merchant Management System (MMS) in the same manner as normal card transactions.

Limitations

  • Your Customer will need a digital wallet enabled device with some stored card details in order to make full use of this payment method.
  • The device needs to be integrated with the Gateway using third-party provided software.
  • Repeat transactions using the retrieved payment details are supported.

Configuration

The Merchant Account being used for the payments must be configured with your Digital Wallet credentials so that the Gateway can decrypt the payment token.

Apple Pay configuration

Apple Pay requires the Gateway to generate public/private key pair and then the public key must be shared with your Apple Pay enabled application in the guise of an Apple Pay payment process certificate.

To configure an Apple Pay payment processing certificate you must have enrolled in the Apple Developer Programand created a unique Apple Pay merchant identifier.

The payment processing certificate is associated with your merchant identifier and used to encrypt payment information. The certificate expires every 25 months. If the certificate is revoked, you can recreate it.

You would normally use the Merchant Management System (MMS) to configure your payment processing certificate by following the steps outlined below:

  1. Open the Apple Developer Certificates, Identifiers & Profiles webpage and select 'Identifiers' from the sidebar.
  2. Under 'Identifiers', select 'Merchant IDs' using the filter in the top-right.
  3. On the right, select your merchant identifier.
  4. Under 'Apple Pay Payment Processing Certificate', click 'Create Certificate'.
  5. Download our certificate signing request (CSR) from the MMS and save to a file.
  6. Click 'Choose File' and select the CSR you just downloaded.
  7. Click 'Continue'.
  8. Click 'Download' to download the payment processing certificate and save to a file.
  9. Upload the payment processing certificate to the MMS.

Google Pay configuration

Google Pay requires no specific configuration however you must use your Google Merchant Identifier, our Gateway identifier of ‘crst’, and the correct Merchant Account identifier when configuring your Google Pay enabled application.

If you have not yet obtained your Google Merchant identifier, please create this before proceeding.

Once created, this will need to be entered in the Google Pay Preferences section in the MMS (found on Digital Wallets tab of the Preferences page)

Request Fields

Digital Wallet payments require the secure payment token generated by the wallet enabled application to be sent to the Gateway in the paymentToken field. The type of token must be specified by also sending the paymentMethod field with a value of ‘applepay’ or ‘googlepay’.

NameMandatoryDescription
paymentMethodYesThe type of payment token sent.

Value must be one of:
applepay – to indicate an Apple Pay token
googlepay – to indicate a Google Pay token
paymentTokenYesMust contain the secure payment token produced by the wallet enabled application.

Response Fields

There are no additional response fields.

Digital Wallet Tokens

Digital Wallet payments operate the same as normal card payments, the main difference is that the card details are passed from the wallet application within an encrypted payment token. Once the Gateway has extracted the card details then it can use it with 3-D Secure and Fraud checking services as normal.

FPAN/DPAN tokens

Apple Pay and Google Pay (Mobile) payment tokens contain an EMV tokenised card number also known as a device-specific number (DPAN) rather than the Cardholder’s actual card number (FPAN). With these tokens the expiry date is the date the DPAN expires rather than the value printed on the Cardholder’s card. The card mask returned by the Gateway will be the masked DPAN, the Gateway is not able to return the last 4 digits of the FPAN. The card issuing details returned are the same as those of the original FPAN. Google Pay (Web) payment tokens contain the Cardholder’s original card number (FPAN) and expiry date. This means that the card mask and expiry date will be those of the original card.

AVS/CV2 Checking

Digital wallet payment tokens do not contain any address or CVV details. The Cardholder’s billing address can be passed in the transaction along with the payment token so that address checking can be performed. The Gateway and Acquirer will not perform CVV checks with these payment tokens effectively disabling CVV checks for the transaction disregarding your preferences.

3-D Secure Authentication

DPAN based tokens will usually contain 3-D Secure data and so the Gateway will send this data to the Acquirer to gain the benefits of an authenticated transaction without the need to challenge the Cardholder. This makes using the digital wallet a much simpler and frictionless method of payment. FPAN based tokens can be passed to the Gateway’s 3-D Secure processing and undergo the normal authentication journey as a manually entered card number.

Risk Checking

Both FPAN and DPAN based tokens can be used with risk checking via Kount in the same manner as a normal card transaction.

Transaction Lifecycle and Recurring Transactions

Both FPAN and DPAN based tokens will follow the standard transaction lifecycle and can be cancelled, captured, refunded or used as the basis of subsequent transactions in the same manner as a normal card transaction.

PPRO Transactions (APMs)

PPRO is an additional payment method that is available to all Merchants using the Gateway that have a PPRO account.

To use PPRO you will be supplied with a separate PPRO Merchant account that can be grouped with your main Merchant Account using the account mapping facility as documented in the merchant account mapping section. This allows transactions to be sent using your main Merchant Account and then routed automatically to the PPRO Merchant Account in the same mapping group.

PPRO is an Acquirer that offers many Alternative Payment Methods (APM), that you can then offer to your Customers.

E-wallets, SMS payments and PSP services are some of the many payment methods PPRO support (eg Alipay, EasyPay, Bancontact). This could allow a business to facilitate overseas transactions or alternative payment methods using a different payment method suitable for that country or business plan.

All transactions created with this payment method will appear in the Merchant Management System (MMS) together with the payment method that was used to process the transaction.

PPRO transactions cannot be used for ad-hoc Credential on File (COF) repeat transactions or for recurring billing.

For more information on how to accept PPRO transactions please contact customer support.

Benefits

  • Multiple alternative payment methods could be used.
  • Expands range of payment methods for international use.
  • Supports a variety of e-wallets, SMS and PSP’s.
  • Ability to perform refunds on supported payment methods.
  • Transactions are controlled within the Merchant Management System (MMS) in the same manner as normal card transactions.

Limitations

  • You will need a PPRO account.
  • Payment authorisation is not always instantaneous and may require additional ‘QUERY’ requests.
  • An alternative payment method may only support one or a limited set of currencies or countries.
  • Alternative payment methods require a browser in order to display their Checkout.

Implementation

PPRO transactions require you to display the alternative payment method’s Checkout to your Customer as part of the transaction flow. The transaction must be done in two stages with the Checkout being displayed between the stages.

PPRO only supports the SALE and REFUND_SALE actions. This section explains how to make payment requests. Management requests are performed as detailed in the management operations section.

To customise the alternative payment method’s Checkout experience, you may send various options in the checkoutOptions field in your initial request.

Additional information available from the alternative payment method’s Checkout will be made available in the checkoutDetails response field.

The direct integration uses two complex fields to pass data between PPRO and the Gateway. The checkoutRequest field will be provided by the Gateway and is a record whose name/value properties represent the data provided in the checkoutURL and is provided for information purposes only. The corresponding checkoutResponse field should be returned to the Gateway and must be 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 and checkoutResponse fields are formatted using the record format detailed in the format guide, 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 payment method tag listed in the ppro payment method tag. The request must also have a checkoutRedirectURL containing the URL of a page on your server to return to when the alternative payment method’s Checkout is closed. In addition, you may send checkoutOptions to provide further custom fields required by the alternative payment method as detailed in the ppro payment specific fields section.

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 mapping 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 that the buyer’s browser should be redirected to in order to complete the payment. The response will also contain a unique checkoutRef which must be echoed back in the continuation requests.

On completion of the third-party payment the browser will be directed 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 alternative payment methods 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 detailed in the format guide.

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

Request Fields

These fields should be sent in addition to the basic request fields.

NamemandatoryDescription
paymentMethodYesPayment method to be used with PPRO (eg ppro.astropay, ppro.alipay, etc.).Refer to the Payment Method Tag section.
checkoutRedirectURLYesURL on Merchant’s server to return to when the Alternative Payment Method’s Checkout is closed.
checkoutOptionsNoRecord containing options used to customise the alternative payment methods Checkout. See the checkout options section. Whilst the Gateway does not see this field as mandatory, PPRO may have payment methods that require additional configuration using checkout options.

Payment Response

Initial Response Fields

These fields will be returned, in addition to the request fields above and the basic response fields for the start of a PPRO transaction and the PPRO checkout process.

NamemandatoryDescription
checkoutRefYesUnique reference required to continue this transaction when the PPRO Checkout has completed.
checkoutNameYesThe paymentMethod you used to identify the PPRO payment method.
checkoutRedirectURLYesThe URL to redirect the Customer to, to start the checkout process.
checkoutOptionsYesRecord containing any Checkout options provided in the request.
checkoutDetailsYesRecord containing additional information provided from the payment method used during checkout.
checkoutRequestYesRecord containing the redirect secret, checksum and request status.

Completion Response Fields

Fields from the initial response in the previous section may be present as well as the fields below and will not contain any card details.

NamemandatoryDescription
checkoutResponseYesContaining additional information provided by the Checkout. Any change in the payment’s status will be given in responseMessage and responseCode.

Not all payment methods give an immediate payment status. This will require a further QUERY to the Gateway to see whether this value has changed to a status of ‘tendered’.
checkoutStatusYesA string containing the result of the checkout process. This is not used to identify the transaction’s payment status.

Payment Method Tag

To specify which alternative payment method is required you need to send the paymentMethod field with a value using the format ‘ppro.XXXX’, where XXXX is the alternative payment method’s tag name as assigned by PPRO.

For example, to use the alternative payment method AstroPay Card that has a tag name of “astropaycard” (all lowercase); the resulting payment method code would be “ppro.astropaycard”. This allows the Gateway to know that you’re attempting to use AstroPay Card using the PPRO payment method.

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.

Payment Method TagPayment Method Name
affinbankAffin bank
alipayAliPay
ambankAmBank
argencardArgencard
astropaycardAstroPay Card
astropaydirectAstroPay Direct
auraAura
balotoBaloto
banamexBanamex
bancodobrasilBanco Do Brasil
bancodechileBanco de Chile
bancodeoccidenteBanco de Occidente
bancomerBancomer
bankislamBank Islam
bcmcBancontact
bitpayBitPay
boletoBoleto Bancario
bradescoBradesco
cabalCabal
cartaomercadolivreCartao Mercado Livre
carullaCarulla
ccauthCredit/Debit Card
ccwebCredit/Debit Card
cencosudCencosud
cimbclicksCIMB Clicks
cmrCMR
daviviendaDavivienda
directpaySofortüberweisung (Direct Pay)
dragonpayDragonpay
easypayEasyPay
efectyEfecty
eloElo
empresedeenergiaEmprese de Energia
enetseNETS
entercashEntercash
epsEPS
estonianbanksEstonian Banks
giropayGiropay
hipercardHipercard
hongleongbankHong Leong Bank
idealiDEAL
instanttransferInstant Transfer
int_payoutInternational Pay-Outs
itauItau
latvianbanksLatvian Banks
lithuanianbanksLithuanian Banks
magnaMagna
maximaMaxima
maybanktwouMaybank2u
multibancoMultibanco
mybankMyBank
myclearfpxMyClear FPX
naranjaNaranja
narvesenNarvesen
nativaNativa
oxxoOXXO
p24Przelewy24
p24payoutPrzelewy24 Payout
pagofacilPago Facil
paypostPayPost
paysafecardPaysafe Card
paysbuyPaysbuy
payseraPaysera
payuPayU
perlasPerlas Terminals
poliOLI
prestoPresto
psePSE
pugglepayPugglepay
qiwiQIWI
qiwipayoutQIWI Payout
rapipagoRapipago
redpagosRedpagos
rhbbankRHB Bank
safetypaySafetyPay
santanderSantander
sepadirectdebitSEPA DirectDebit
sepapayoutSEPA Payout
seveneleven7eleven
singpostSingPost
skrillSkrill
surtimaxSurtimax
tarjetashoppingTarjeta Shopping
trustlyTrustly
trustpayTrustPay
unionpayUnionPay
verkkopankkiVerkkopankki – Finish Online Banking
webpayWebpay
yellowpayYellow Pay

Checkout Options

The following options may be set in the checkoutOptions field to customise the Checkout. The options must be formatted using the record or serialised record formats detailed in the format guide.

NameDescription
nationalidConsumer’s national ID (up to 30 characters).
consumerrefUnique reference identifying the consumer within 1 to 20 characters and a format of A-Za-z0-9.%,&/+*$-
siteidUnique site identifier. Required for clients serving multiple points of sale and forwarded onwards whilst using the qiwi payment method.
ibanValid IBAN of consumer/destination account.
sequencetypeSequence type of the direct debit.

Possible values are:
oneOff – The direct debit is executed once (default)
first – First direct debit in a series of recurring ones
mandatereferenceMandate reference as returned on the first transaction in the sequence (found from mandatereference in checkoutDetails)
mandatesignaturedateDate of the initial transaction.
bicValid BIC (8 or 11 alphanumeric letters) – optionally supplied to skip the bank selection page (by using the bank referenced by BIC as supplied)
clientipOptional IP address of the consumer during checkout using Trustly (127.0.0.1 is not allowed!)
addressCustomer’s billing address

This information is supplied to PPRO by default using the Gateway field customerAddress
cityCustomer’s billing city

This information is supplied to PPRO by default using the Gateway field customerTown.
phoneCustomer’s phone

This information is supplied to PPRO by default using the Gateway field customerPhone.
mobilephoneCustomers mobile phone

This information is supplied to PPRO by default using the Gateway field customerMobile.
dobMCC 6012 Date of Birth

This information is supplied to PPRO by default using the Gateway field receiverDateOfBirth.
dynamicdescriptorStatement narrative

This information is supplied to PPRO by default using the Gateway field statementNarrative1.

Notifications and "Tendered" Payments

Whilst some payment methods give an immediate payment status (ie direct card payment methods rather than SMS and e-wallet systems), some payments may come back with the status of ‘tendered’. At this time, online shopping modules will not be able to monitor the transaction status. The use of a QUERY request may be of use. Please ask customer support in this matter who will be able to give more information and may be able to provide better advice for your situation.

Notifications from PPRO regarding the payment status, seconds, minutes or hours after the checkout will automatically update the transaction status.

PayPal Transactions

PayPal is an additional payment method that is available to all Merchants using the Gateway who have a PayPal account.

To use PayPal, you will be supplied with a separate PayPal Merchant Account that can be grouped with your main Merchant Account using the account mapping facility as documented in the merchant account mapping section. This allows transactions to be sent using your main Merchant Account and then routed automatically to the PayPal Merchant Account in the same mapping group.

It allows you to offer payment via PayPal in addition to normal card payments.

PayPal transactions will appear in the Merchant Management System (MMS) alongside any card payments and can be captured, cancelled and refunded in the same way as card payments.

PayPal transactions can also be used for recurring billing but require you to indicate in the initial transaction that it will be the basis for recurring billing and that a billing agreement will be entered between your Customer and PayPal when they agree to the payment.

PayPal transactions cannot be used for ad-hoc Credentials on File (COF) repeat transactions unless a billing agreement has been set up.

For more information on how to accept PayPal transactions, please contact customer support.

Benefits

  • Provides your customers with the flexibility of paying by using their PayPal account when this is more suitable to them than using a traditional credit or debit card.
  • The in-context PayPal Express Checkout helps improve conversion rates with an easier way to pay without customers leaving your website.
  • There are no extra costs for adding a PayPal Merchant Account. However, you will still be liable for the PayPal transaction fees.
  • The full PayPal transaction information is available and returned as part of the transaction.
  • Transactions are controlled within the Merchant Management System (MMS) in the same manner as normal card transactions.

Limitations

  • You will need a PayPal account.
  • Recurring transactions are not supported unless as part of a prearranged billing agreement.
  • Independent refunds that are not tied to a previous sale transaction are not supported without prior agreement.
  • Transactions require a browser in order to display the PayPal Checkout.
  • The PayPal Checkout cannot be opened from within a browser IFRAME and so care must be taken to ensure that any PayPal Checkout button is not placed within such an IFRAME.

Implementation

PayPal transactions require you to display the PayPal Checkout to your Customer as part of the transaction flow. The transaction must be done in two stages, with the Checkout being displayed between the stages. They can also be optionally done in three stages allowing you to display an order confirmation after the Checkout and before authorising the transaction. You can change the amount at this stage to allow for shipping costs when you know the confirmed delivery address the Customer selected as part of the PayPal Checkout.

PayPal supports the normal payment and management actions. This section explains how to make payment requests. Management requests are performed as detailed in the management operations section.

To customise the PayPal Checkout experience, you may send various options in the checkoutOptions field in your initial request.

Additional information available from the PayPal Checkout will be made available in the checkoutDetails response field.

The direct integration uses two complex fields to pass data between the PayPal Checkout and the Gateway. The checkoutRequest field will be provided by the Gateway and is a record whose name/value properties should be used with the PayPal JavaScript SDK to open the Checkout. The corresponding checkoutResponse field should be returned to the Gateway and must be 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 and checkoutResponse fields are formatted using the record format detailed in the format guide, the checkoutOptions field also supports being provided using the serialised record format.

Initial Request (Checkout Preparation)

To request that a transaction be processed via PayPal the request must contain a paymentMethod of ‘paypal’ and 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 customise the Checkout experience. When the Gateway receives this paymentMethod, assuming there are no other errors with the request, it will attempt to find a suitable PayPal Merchant Account in the current account mapping group (refer to the merchant account mapping 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 required to load Checkout and a checkoutRequest containing any data required to be sent to the Checkout. The response will also contain a unique checkoutRef which must be echoed back in the continuation requests.

At this point your server must redirect the Customer’s browser to the provided checkoutURL. Alternatively, the checkoutURL can be used in conjunction with the PayPal In-Context JavaScript code to implement an In-context Checkout which allows the Merchants website to remain visible in the background. Further details on how to use the In-Context Checkout are provided in the PayPal guide at https://developer.paypal.com/docs/classic/express-checkout/in-context/enable_in_context_checkout/.

Request Fields

These fields should be sent in addition to the basic request fields.

NameMandatoryDescription
paymentMethodYesMust contain the value ‘paypal’ in lower case letters only.
checkoutRedirectURLYesURL on Merchant’s server to return to when the PayPal Checkout is closed.
checkoutOptionsNoRecord containing options used to customise the PayPal Checkout. See the checkout options section.

Response Fields

These fields will be returned, in addition to the request fields above and the basic response fields.

NameMandatoryDescription
checkoutRefYesUnique reference required to continue this transaction when the PayPal Checkout has completed.
checkoutNameYesUnique name of the Checkout. For PayPal this is the value paypal.
checkoutURLYesURL required to load the PayPal Checkout.
acquirerResponseDetailsYesRecord containing details about the PayPal response containing any error messages and codes. This can be used together with the normal responseCode and responseMessage response fields to determine further the reason for any failure.
checkoutRequestNoRecord containing details to send to the PayPal Checkout.
checkoutOptionsNoRecord containing any Checkout options passed in the request.

Continuation Request (Checkout Details and Authorise)

On completion of the PayPal Checkout it will redirect the Customer’s browser to the checkoutRedirectURL provided including a token and status URL parameters. If the checkout was successful, the status will be ‘success’ alternatively if the Checkout was cancelled the status will be ‘cancel’. The received redirect request parameters inclusive of these token and status parameters should then be sent to the Gateway in the checkoutResponse fields of a new request. The checkoutResponse field can be sent either as the original URL query string received or as an array of the decoded query parameters. This new request will load the Checkout details including any delivery address if required and send the transaction to PayPal for authorisation, returning the result as per a normal authorisation transaction. The new request must contain the checkoutRef received in the initial response.

Request Fields

These fields may be sent alone. It is only necessary to send the checkoutRef and the checkoutResponse in the continuation request because the checkoutRef will identify the Merchant Account and initial request. The message does not need to be signed. You can send any of the normal request fields to modify or supplement the initial request – however, in this case the request should be signed. The checkoutRedirectURL and checkoutOptions fields sent in the initial request cannot be modified and any sent in the second request must match those used in the first request, or the second request will fail with a responseCode of 64442 (REQUEST MISMATCH).

NameMandatoryDescription
checkoutRefYesUnique reference returned in the initial response.
checkoutResponseYesThe GET and or POST data received by the checkoutRedirectURL page.
checkoutOnlyNoPass Y to complete the processing as far as the next Checkout stage and then return with the loaded Checkout details.

Response Fields

These fields will be returned, in addition to the request fields above and the basic response fields.

NameMandatoryDescription
checkoutRefYesProvided if checkoutOnly was used in the continuation response to indicate that a further request will be sent to finalise the transaction.
checkoutNameYesUnique name of the Checkout. For PayPal this is the value paypal.
checkoutDetailsYesRecord containing options used to customise the PayPal Checkout. Refer to the checkout details section.
acquirerResponseDetailsYesRecord containing details about the PayPal response containing any error messages and codes. This can be used together with the normal responseCode and responseMessage response fields to determine further the reason for any failure.
customerXXXXNoCustomer details if provided by the PayPal Checkout. The response will include the Customer/billing address details if provided by the PayPal Checkout.
deliveryXXXXNoDelivery details if provided by the PayPal Checkout.The response will include the delivery address details if provided by the PayPal Checkout.

Separate Checkout Details and Authorisation Requests

You can choose to obtain the Checkout details before actually sending the transaction for authorisation by sending the checkoutOnly field in the above continuation request. If this field is sent with a value of ‘Y’ then the Gateway will load the Checkout details and then return them to you without sending the request for authorisation. You can then display them and/or adjust the amount, for example, according to delivery charges appropriate to the received delivery address. You should then send a new request containing the checkoutRef received to continue the transaction and authorise it.

Note: this stage can be repeated multiple times by including the checkoutOnly field with a value of ‘Y’ each time. To complete the transaction, the final request must not contain the checkoutOnly field or it must not have a value of ‘Y’.

Checkout Options

The following options may be set in the checkoutOptions field to customise the PayPal Checkout. The options must be formatted using the record or serialised record formats detailed in the format guide.

NameDescription
inContextUse the in-context PayPal Checkout rather than the full screen Checkout when possible.

Possible values are:
0 – use the full screen Checkout.
1 – use the in-context Checkout if possible.
userActionDetermines whether buyers complete their purchases on PayPal or on your website.

Possible values are:
commit – sets the submit button text to ‘Pay Now’ on the PayPal Checkout. This text lets buyers know that they complete their purchases if they click the button.
continue– sets the submit button text to ‘Continue’ on the PayPal Checkout. This text lets buyers know that they will return to the Merchant’s cart to complete their purchases if they click the button.
maxAmountThe expected maximum total amount of the order, including shipping and taxes. PayPal refer to this field as MAXAMT.
reqBillingAddressDetermines whether the buyer’s billing address on file with PayPal is returned. This feature must be enabled by PayPal.
reqConfirmShippingDetermines whether the buyer’s shipping address on file with PayPal must be a confirmed address.

Possible values are:
0 – does not need to be confirmed
1 – must be confirmed
noShippingDetermines whether PayPal displays shipping address.
Possible values are:
0 – display the shipping address
1 – do not display shipping address and remove shipping information
2 – If no deliveryXXXX fields passed, PayPal obtains them from the buyer's account profile.
addrOverrideDetermines whether the PayPal Checkout displays the shipping address sent using the deliveryXXXX fields and not the shipping address on file with PayPal for this buyer. Displaying the PayPal street address on file does not allow the buyer to edit that address.

Possible values are:
0 – PayPal should not display the address.
1 – PayPal should display the address.
localeCodeLocale of the pages displayed by PayPal during Express Checkout. It is either a two-letter country code or five-character locale code supported by PayPal.
allowNoteEnables the buyer to enter a note to the merchant on the PayPal page during Checkout. The note is returned in the checkoutDetails response field.
pageStyleName of the Custom Payment Page Style used for the PayPal Checkout. It is the same name as the Page Style Name used when adding styles in the PayPal Account.
payflowColorThe HTML hex colour code for the PayPal Checkout’s background colour. By default, the colour is white (FFFFFF).
cardBorderColorThe HTML hex colour code for the PayPal Checkout’s principal identifying colour. The colour will be blended to white in a gradient fill that borders the cart review area.
hdrImgURL for the image you want to appear at the top left of the payment page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal requires that you provide an image that is stored on a secure (https) server. If you do not specify an image, the business name displays.
logoImgA URL to your logo image. Use a valid graphics format, such as .gif, .jpg, or .png. Limit the image to 190 pixels wide by 60 pixels high. PayPal crops images that are larger. PayPal places your logo image at the top of the cart review area.
landingPageType of PayPal Checkout to display.

Possible values are:
Billing – Non-PayPal account
Login – PayPal account login
channelTypeType of channel.

Possible values are:
Merchant – Non-auction seller
eBayItem – eBay auction
solutionTypeType of Checkout flow.

Possible values are:
Sole – Buyer does not need to create a PayPal account to check out. This is referred to as PayPal Account Optional.
Mark – Buyer must have a PayPal account to check out.
totalTypeType declaration for the label to be displayed in MiniCart for UX.

Possible values are:
Total
EstimatedTotal
brandNameA label that overrides the business name in the PayPal account on the PayPal Checkout.
customerServiceNumberMerchant Customer Service number displayed on the PayPal Checkout.
buyerEmailOptInEnableEnables the buyer to provide an email address on the PayPal pages to be notified of promotions or special events.

Possible values are:
0 – Do not enable buyer to provide email.
1 – Enable the buyer to provide email.
noteToBuyerA note from the merchant to the buyer that will be displayed in the PayPal Checkout.
paymentActionDefines how to obtain payment. This can be used to override any captureDelay setting that can also be used to indicate a Sale or Authorisation only.

Possible values are:
Sale – sale with immediate capture.
Authorization – authorisation subject to later capture (note spelling).
Order – order subject to later authorisation and capture.
allowedPaymentMethodThe payment method type. Specify the value InstantPaymentOnly
insuranceOptionOfferedIndicates whether insurance is available as an option that the buyer can choose on the PayPal Review page.

Possible values are:
true – The Insurance option displays 'Yes' and the insuranceAmount. If true, the total shipping insurance for this order must be a positive number.
false – The Insurance option displays 'No'.
multiShippingIndicates whether this payment is associated with multiple shipping addresses.

Possible values are:
0 – Single/No shipping address.
1 – Multiple shipping addresses.
noteTextThe category of a payment.

Possible values are:
1 – International shipping
2 – Local delivery
3 – BOPIS, Buy online pick-up in store
4 – PUDO, Pick-up drop-off
locationTypeType of merchant location. Required if the items purchased will not be shipped, such as, BOPIS (Buy Online Pick-up In Store) or PUDO (Pick-Up Drop-Off) transactions.

Possible values are:
1 – Consumer.
2 – Store, for BOPIS transactions.
3 – PickupDropoff, for PUDO transactions.
locationIDLocation ID specified by the merchant for BOPIS (Buy Online Pick-up In Store) or PUDO (Pick-Up Drop-Off) transactions.
sellerPayPalAccountIDUnique identifier for the Merchant. For parallel payments, this field is required and must contain the Payer Id or the email address of the Merchant.
invNumMerchant’s invoice or tracking number.
customCustom field for your own use. buyerID
buyerIDThe unique identifier provided by eBay for this buyer. The value may or may not be the same as the username. In the case of eBay, it is different.
buyerUsernameThe username of the user at the marketplaces site.
buyerRegistrationDateDate when the user registered with the marketplace. In UTC/GMT format, for example, 2013-08-24T05:38:48Z.
allowPushFundingIndicates whether the Merchant can accept push funding.

Possible values are:
0 – Merchant cannot accept push funding.
1 – Merchant can accept push funding.
userSelectedFundingSourceThis element could be used to specify the preferred funding option for a guest user. However, the landingPage Checkout option must also be set to Billing, otherwise, it is ignored.

Possible values are:
ChinaUnionPay.
CreditCard.
ELV.
QIWI.
billingTypeType of billing agreement for reference transactions. You must have permission from PayPal to use this field.

Possible values are:
MerchantInitiatedBilling – PayPal creates a billing agreement for each transaction associated with buyer.
MerchantInitiatedBillingSingleAgreement – PayPal creates a single billing agreement for all transactions associated with buyer. Use this value unless you need per-transaction billing agreements.
billingAgreementDescriptionDescription of goods or services associated with the billing agreement. This field is required for each recurring payment billing agreement. PayPal recommends that the description contain a brief summary of the billing agreement terms and conditions. For example, buyer is billed at "9.99 per month for 2 years".
paymentTypeType of PayPal payment you require for the billing agreement.

Possible values are:
Any – The merchant accepts any payment method for the billing agreement, even if it could take a few working days for the movement of funds to the merchant account. This includes echeck, in addition to credit or debit cards and PayPal balance.
InstantOnly – The payment options accepted by the merchant are credit cards, debit cards or PayPal balance only because the merchant expects immediate payment.
taxIDTypeBuyer's tax ID type. This field is required for Brazil and used for Brazil only.

For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for businesses.
taxIDBuyer's tax ID. This field is required for Brazil and used for Brazil only.

For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14 single-byte characters for businesses
returnFMFDetailsFlag to indicate whether you want the results returned by Fraud Management Filters when doing a recurring/reference transaction.

Possible values are:
0 – Do not receive FMF details (default).
1 – Receive FMF details.
riskSessionCorrelationIDThe ID of the risk session for correlation purposes when doing a recurring/reference transaction.
merchantSessionIDThe buyer session identification token when doing a recurring/reference transaction.
buttonSourcePayPal Partner’s BN Code (if required). The BN code is the unique button source code provided by PayPal to its partners and added by its partners to the PayPal buttons used by merchants to offer the PayPal Services that are enabled through Partner Product. The button source code provides a means of identifying and tracking referred merchants' payments.

For further information on the options, refer to the PayPal Express Checkout documentation: https://developer.paypal.com/docs/classic/api/merchant/SetExpressCheckout_API_Operation_NVP/.

Purchase Details

The following request fields may be sent to provide information on the purchased items and to populate the cart on the PayPal Checkout.

NameMandatoryDescription
shippingAmountNoShipping costs.
shippingDiscountAmountNoDiscount applied to shipping costs.
handlingAmountNoHandling costs.
insuranceAmountNoInsurance costs.
itemXXDescriptionNoDescription of XXth item purchased.
itemXXQuantityNoQuantity of XXth item purchased.
itemXXAmountNoGross amount for XXth item purchased.
itemXXTaxAmountNoTax amount for XXth item purchased.
itemXXProductCodeNoProduct code for XXth item purchased.
itemXXProductURLNoShopping cart URL for XXth item purchased.
itemXXSizeNoSize of XXth item purchased in the format ‘LengthxWidthxHeight Unit’.
itemXXWeightNoWeight of XXth item purchased in the format ‘Weight Unit’.
itemsNoNested array of line items.

Note: The shopping cart items must total to the amount specified in the transaction. If they do not, cart items will not be sent to the PayPal Checkout.

Checkout Details

The following details may be provided in the checkoutDetails field included in the response. The details will be returned using the record format detailed in the format guide.

NameMandatoryDescription
correlationIDNoCorrelation ID, which uniquely identifies the transaction to PayPal.
checkoutStatusNoStatus of the Checkout session. If payment is completed, the transaction identification number of the resulting transaction is returned.

Possible values are:
PaymentActionNotInitiated
PaymentActionFailed
PaymentActionInProgress
PaymentActionCompleted
invNumNoMerchant’s invoice or tracking number, as set sent in checkoutDetails.invNum or assigned by the Gateway.
customNoMerchant’s invoice or tracking number, as set sent in checkoutDetails.custom or assigned by the Gateway.
payPalAdjustmentNoA discount or gift certificate offered by PayPal to the buyer. This amount is represented by a negative amount. If the buyer has a negative PayPal account balance, PayPal adds the negative balance to the transaction amount, which is represented as a positive value.
buyerMarketingEmailNoBuyer's marketing email address. Only available if email option was enabled in the initial request using checkoutOptions.buyerEmailOptInEnable option.
noteNoBuyer’s note to the Merchant. Only available if the leaving of notes was enabled in the initial request using checkoutOptions.allowNote option.
cartChangeToleranceNoIndicates whether a cart's contents can be modified. If this parameter is not returned, then assume the cart can be modified. This will return NONE if financing was used in Germany.

Possible values are:
NONE – The cart cannot be changed.
FLEXIBLE – The cart can be changed.
payerIDNoBuyer’s PayPal Customer Account ID.
payerStatusNoBuyer’s PayPal status.

Possible values are:
verified
unverified
billingNameNoBuyer’s name. Also returned in customerName. Permission is needed from PayPal to support this field.
firstNameNoBuyer’s first name. Also returned in customerName. These fields are used when no permission to use billingName.
middleNameNoBuyer’s middle name. Also returned in customerName.
lastNameNoBuyer’s last name. Also returned in customerName.
suffixNoBuyer’s name suffix. Also returned in customerName.
businessNoBuyer's business name. Also returned in customerCompany.
streetNoBuyer’s street first line. Also returned in customerAddress.
street2NoBuyer’s street second line. Also returned in customerAddress.
cityNoBuyer’s city Also returned in customerTown.
stateNoBuyer’s state. Also returned in customerCounty.
zipNoBuyer’s postal code. Also returned in customerPostcode.
countryCodeNoBuyer's country code. (ISO 2 char. code) Also returned in customerCountryCode.
countryNameNoBuyer's country name.
phoneNumNoBuyer's contact phone number. Also returned in customerPhone.
emailNoBuyer’s email address. Also returned in customerEmail.
shipToNameNoName of person/entity to ship to. Also returned in deliveryName.
shipToStreetNoShip to street first line. Also returned in deliveryAddress.
shipToStreet2NoShip to street second line. Also returned in deliveryAddress.
shipToCityNoShip to city. Also returned in deliveryTown.
shipToStateNoShip to state. Also returned in deliveryCounty.
shipToZipNoShip to postal code. Also returned in deliveryPostcode.
shipToCountryCodeNoShip to country code. (ISO 2 char. code) Also returned in deliveryCountryCode.
shipToCountryNameNoShip to country name.
shipToPhoneNumNoShip to phone number. Also returned in deliveryPhone.
shipToAddressStatusNoStatus of shipping address on file with PayPal.

Possible values are:
none
Confirmed
Unconfirmed
addressNormalizationStatusNoThe PayPal address normalisation status for Brazilian addresses.

Possible values are:
None
Normalized
Unnormalized
UserPreferred

This field is passed directly to PayPal and therefore the field name and value must be spelt ‘ize’ and not ‘ise’.
amountNoTotal amount for this order.
itemAmountNoTotal item amount for this order.
taxAmountNoTax amount for this order.
exchangeRateNoExchange rate for this order.
shippingAmountNoShipping amount for this order.
handlingAmountNoHandling amount for this order.
insuranceAmountNoInsurance amount for this order.
shipDiscountAmountNoShipping discount amount for this order.
descNoDescription of items the buyer is purchasing.
currencyCodeNoISO 3-letter currency code.
isFinancingNoIndicates whether the Customer ultimately was approved for and chose to make the payment using the approved instalment credit.

Possible values are:
FALSE – financing not in use
TRUE – financing approved and used
financingFeeAmountNoThe transaction financing fee associated with the payment. This will be set to the instalment fee amount that is the same as the estimated cost of credit or the interest/fees amount the user will have to pay during the lifetime of the loan. This field will only be included in instalment credit orders. In the case of “same as cash” or “no interest” offers, this will be set to 0.
financingTermNoThe length of the financing term, in months. Example values are 6, 12, 18 and 24 months.
financingMonthlyPaymentNoThis is the estimated amount per month that the Customer will need to pay including fees and interest.
financingTotalCostNoThis is the estimated total payment amount including interest and fees that the user will pay during the lifetime of the loan.
financingDiscountAmountNoDiscount amount for the buyer if paid in one instalment.
regularTakeFeeAmountNoFee of the regular take rate on the transaction amount. It could be equal to financingDiscountAmount in the case of non-instalment transactions.
noteTextNoNote to Merchant.
transactionIDNoPayPal transaction ID.
allowedPaymentMethodNoThe payment method type as specified in the initial request.
paymentRequestIDNoA unique identifier of the specific payment request.
bucketCategoryTypeNoThe category of a payment as specified in the initial request.
instrumentCategoryNoIdentifies the category of the promotional payment instrument.

Possible values are:
1 – PayPal Credit® (formerly Bill Me Later®).
2 – A Private Label Credit Card (PLCC) or co-branded payment card.
instrumentIDNoAn instrument ID (issued by the external party) corresponding to the funding source used in the payment.
shippingCalculationModeNoDescribes how the options that were presented to the buyer were determined.

Possible values are:
API – Callback
API – Flatrate
insuranceOptionSelectedNoThe option that the buyer chose for insurance.

Possible values are:
Yes – opted for insurance.
No – did not opt for insurance.
shippingOptionIsDefaultNoIndicates whether the buyer chose the default shipping option.

Possible values are:
true – chose the default shipping option.
false – did not choose the default shipping option.
shippingOptionAmountNoThe shipping amount that the buyer chose.
shippingOptionNameNoThe name of the shipping option, such as Air or Ground.
scheduledShippingDateNoThe scheduled shipping date is returned only if scheduled shipping options are passed in the request.
scheduledShippingPeriodNoThe scheduled shipping period is returned only if scheduled shipping options are passed in the request.
sellerPayPalAcountIDNoUnique identifier for the merchant. For parallel payments, this field contains either the Payer Id or the email address of the merchant.
taxIDTypeNoBuyer's tax ID type. This field is required for Brazil and used for Brazil only. For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for businesses.
taxIDNoBuyer's tax ID. This field is required for Brazil and used for Brazil only. For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14 single-byte characters for businesses.
billingAgreementIDNoIdentification number of the billing agreement. When the buyer approves the billing agreement, it becomes valid and remains valid until it is cancelled by the buyer.
billingAgreementAcceptedStatusNoIndicates whether the buyer accepted the billing agreement for a recurring payment. Currently, this field is always returned in the response for agreement based products, such as subscriptions; reference transactions; recurring payments; and regular single payment transactions.

0 – Not accepted.
1 – Accepted.
paymentStatusNoStatus of the payment.

Possible values are:
None – No status.
Canceled-Reversal – A reversal has been cancelled: for example, when you win a dispute and the funds for the reversal have been returned to you.
Completed – The payment has been completed and the funds have been added successfully to your account balance.
Denied – You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the pendingReason element.
Expired – The authorisation period for this payment has been reached.
Failed – The payment has failed. This happens only if the payment was made from your buyer's bank account.
In-Progress – The transaction has not terminated: for example, an authorisation may be awaiting completion.
Partially-Refunded – The payment has been partially refunded.
Pending – The payment is pending. See the pendingReason field for more information.
Refunded – You refunded the payment.
Reversed – A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the reasonCode element.
Processed – A payment has been accepted.
Voided – An authorisation for this transaction has been voided.
refundStatusNoStatus of the refund.

Possible value are:
none – returned if the refund fails
instant – refund was instant
delayed – refund was delayed
pendingReasonNoThe reason the payment is pending.

Possible values are:
none – No pending reason.
address – The payment is pending because your buyer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to accept or deny each of these payments manually. To change your preference, go to the Preferences section of your Profile.
authorization – The payment is pending because it has been authorised but not settled. You must capture the funds first.
echeck – The payment is pending because it was made by an eCheck that has not yet cleared.
intl – The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview.
multi-currency – You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment.
order – The payment is pending because it is part of an order that has been authorised but not settled.
payment-review – The payment is pending while it is being reviewed by PayPal for risk.
regulatory-review – The payment is pending while we make sure it meets regulatory requirements. You will be contacted again in from 24 to 72 hours with the outcome of the review.
unilateral – The payment is pending because it was made to an email address that is not yet registered or confirmed.
verify – The payment is pending because you are not yet verified. You must verify your account before you can accept this payment.
other – The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service.

pendingReason is returned in the response only if paymentStatus is Pending.
reasonCodeNoThe reason for a reversal if the transaction type is reversal.

Possible values are:
none – No reason code.
chargeback – A reversal has occurred on this transaction due to a chargeback by your buyer.
guarantee – A reversal has occurred on this transaction due to your buyer triggering a money-back guarantee.
buyer-complaint – A reversal has occurred on this transaction due to a complaint about the transaction from your buyer.
refund – A reversal has occurred on this transaction because you have given the buyer a refund.
other – A reversal has occurred on this transaction due to a reason not listed above.
protectionEligibilityTypeNoThe kind of seller protection in force for the transaction.

Possible values are:
ItemNotReceivedEligible – Merchant is protected by PayPal's Seller Protection Policy for Item Not Received.
UnauthorizedPaymentEligible7 – Merchant is protected by PayPal's Seller Protection Policy for Unauthorised Payments.
Ineligible – Merchant is not protected under the Seller Protection Policy. (Multiple values are separated by commas)
feeAmountNoPayPal fee amount charged for the transaction.
settleAmountNoAmount deposited in your PayPal account after a currency conversion.
storeIDNoStore identifier as entered in the transaction.
terminalIDNoTerminal identifier as entered in the transaction.

Transaction Lifecycle

PayPal transactions will use the normal Authorise, Capture life cycle as documented in the section Authorise, Capture and Settlement with the following differences. In addition, the PayPal paymentAction option can be included in the checkoutOptions field to alter the normal payment lifecycle further, to allow an Order, Authorise, Capture model or a straight Sale model to be specified.

Order

If a paymentAction with a value of ‘Order’ is sent, then PayPal will store the transaction but delay authorising it until instructed. To instruct PayPal to authorise the transaction, a further management request can be sent to the Gateway with an action of ‘AUTHORISE’ and the xref of the transaction to authorise. Alternatively, the AUTHORISE command can be selected in the Merchant Management System (MMS). The transaction will be left in the ‘received’ state.

Authorise

If no paymentAction is specified or a paymentAction with a value of ‘Authorize’ is sent, then PayPal will authorise the transaction on receipt as per a standard card transaction and you can capture it later if you used the captureDelay field. Note that the value uses the PayPal spelling ‘Authorize’, and not the British spelling ‘Authorise’.

For the first three days (by default) of the authorisation, funds are reserved. This is known as the honour period. After the honour period, captures can still be attempted, but may be returned with insufficient funds.

Authorisations have a fixed expiry period of 29 days.

Sale

If a paymentAction with a value of ‘Sale’ is sent, then PayPal will immediately capture the transaction after authorisation. The transaction will be regarded as having been settled and you will not be able to capture it manually and it will not be sent for settlement that evening. The transaction will be left in either the accepted or rejected terminal states depending on whether PayPal accepted or rejected the transaction.

Capture

Transactions that have been authorised by PayPal and not immediately settled due to a paymentAction of ‘Sale’ will be able to be captured as normal.

Captures are sent to PayPal immediately and the PayPal response and the transaction will be left in either the accepted or rejected terminal state depending on whether PayPal accepted or rejected the capture request.

There is no need to wait for the nightly settlement batch to run as with normal card transactions. This means that it is not possible to change the amount to be captured or cancel the transaction one a capture has been requested.

Note: PayPal allows multiple captures where they sum the individual capture amounts – ie in a different manner from the Gateway’s, where only a single capture operation can be processed.

Refund

PayPal transactions can be refunded in the same way as normal card transactions. However, in the same way as capture requests, these will be sent to PayPal immediately and not batched up to be sent as part of the nightly settlement process. This means that the transaction will be left in either the accepted or rejected terminal state, depending on whether PayPal accepted or rejected the refund request.

Refunds can be made for full or partial amounts, with multiple refunds allowed up to the original authorised amount.

By default, PayPal allows a Merchant up to 60 days from the original authorised transaction date to perform refunds.

Cancel

You should cancel any transactions that you do not wish to capture in order to prevent ‘pending’ transactions on the Customer’s PayPal account.

Authorisations should be cancelled when an initial authorisation was created to confirm the validity of funds during checkout, but the goods will not ship for a significant amount of time (>29 days). Cancelling the transaction will mean that you will have to contact the Customer for an alternative payment method.

All transactions must be completed by being captured or cancelled.

Pending Payments

PayPal may put a transaction into a pending state when flagged for additional fraud review. This state is known to PayPal as payment review or IPR.

IPR transactions will be automatically cancelled by the Gateway and treated as referred transactions with a responseCode of 2 and a responseMessage indicating the reason that the transaction was put into a pending state. Unlike card referred transactions, an authorisation code cannot be obtained from PayPal verbally and then the transaction resent.

Reference Transactions

PayPal does not allow ad hoc Credentials on File (COF) type repeat or recurring transactions using the xref of a reference transaction unless that transaction has specifically started a PayPal Billing Agreement.

If you want to be able to make future repeat or recurring transactions, then the initial transaction must include the billingType and billingAgreementDescription options in the checkoutOptions so as to identify this transaction as the start of a recurring billing sequence.

This will cause the Gateway to request PayPal to set up a Billing Agreement between you and the Customer. In this case, the PayPal Billing Agreement ID will be returned as part of the checkoutDetails and displayed on the Merchant Management System (MMS) as part of the payment details, so that you can easily see which PayPal transactions can be used for recurring billing.

Amazon Pay Transactions

Amazon Pay is an additional payment method that is available to all Merchants using the Gateway that have an Amazon Pay account.

To use Amazon Pay, you will be supplied with a separate Amazon Pay Merchant account that can be grouped with your main Merchant account using the account mapping facility as documented in the merchant account mapping section. This allows transactions to be sent using your main Merchant Account and then routed automatically to the Amazon Pay Merchant Account in the same mapping group.

It allows you to offer payment via Amazon Pay in addition to normal card payments.

Amazon Pay transactions will appear in the Merchant Management System (MMS) alongside any card payments and can be captured, cancelled and refunded in the same way as card payments.

Amazon Pay transactions can also be used for recurring billing but require you to indicate in the initial transaction that it will be the basis for recurring billing and a billing agreement will be entered into between your Customer and Amazon Pay when they agree to the payment.

Amazon Pay transactions cannot be used for ad-hoc Credentials on File (COF) repeat transactions unless a billing agreement has been set up.

For more information on how to accept Amazon Pay transactions, please contact customer support.

Benefits

  • Provides your customers with the flexibility of paying using their Amazon Pay account when this is more suitable to them.
  • The Amazon Pay Checkout can be added as an overlay on the standard checkout to help improve conversion rates with an easier way to pay without customers leaving your website.
  • There are no extra costs to add an Amazon Pay Merchant Account. However, you will still be liable for the Amazon Pay transaction fees.
  • The full Amazon Pay transaction information is available and returned as part of the transaction.
  • Transactions are controlled within the Merchant Management System (MMS) in the same manner as normal card transactions.

Limitations

  • You will need an Amazon Pay account.
  • Recurring transactions are not supported unless part of a prearranged billing agreement.
  • Independent refunds that are not tied to a previous sale transaction are not supported without prior agreement.
  • Transactions require a browser in order to display the Amazon Pay Checkout widgets.

Implementation

Amazon Pay transactions require you to display an Amazon Pay Checkout to your Customer as part of the transaction flow. The transaction must be done in two stages, with the Checkout page being displayed between the stages. They can also optionally be done in three stages, allowing you to display an order confirmation after the Checkout page and before authorising the transaction. You can change the amount at this stage to allow for shipping costs when you know the confirmed delivery address the Customer selected as part of the Amazon Pay Checkout.

Amazon Pay do not provide a ready built Checkout page and require you to create one on your servers using the JavaScript widget toolkit they provide.

Amazon Pay supports the normal payment and management actions. This section explains how to make payment requests. Management requests are performed as detailed in the management operations section.

To customise the Amazon Pay Checkout experience, you may send various options in the checkoutOptions field in your initial request.

Additional information available from the Amazon Pay Checkout will be made available in the checkoutDetails response field.

The direct integration uses two complex fields to pass data between the Amazon Pay JavaScript widgets and the Gateway. The checkoutRequest field will be provided by the Gateway and is a record whose name/value properties should be used to help initialise the widgets. The corresponding checkoutResponse field should be returned to the Gateway and must be a record containing name/value properties received from the widgets.

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

Initial Request (Checkout Preparation)

To request that a transaction be processed via Amazon Pay, the request must contain a paymentMethod of ‘amazonpay’ In addition, you may send checkoutOptions to customise the Checkout experience. When the Gateway receives this paymentMethod, assuming there are no other errors with the request, it will attempt to find a suitable Amazon Pay Merchant Account in the current account mapping group (refer to the merchant account mapping 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 the response will include a checkoutURL field containing the URL required to load the Amazon Pay JavaScript Widgets; and a checkoutRequest containing any data required by those Widgets. The response will also contain a unique checkoutRef that must be echoed back in the continuation requests.

At this point, your server must create an Amazon Pay Checkout page using their JavaScript Widgets. Further details on how to use the Widgets are provided in the Amazon Pay guide at https://developer.amazonpay.com/docs/classic/express-checkout/in-context/enable_in_context_checkout/.

Request Fields

These fields should be sent in addition to the basic request fields excluding any card details.

NameMandatoryDescription
paymentMethodYesMust contain the value ‘amazonpay’ in lower case letters only.
checkoutRedirectURLNoReserved for future use.
checkoutOptionsNoRecord containing options used to customise the Amazon Pay Checkout. See the checkout options section.

Response Fields

These fields will be returned, in addition to the request fields above and the basic response fields.

NameMandatoryDescription
checkoutRefYesUnique reference required to continue this transaction when the Amazon Pay Checkout has completed.
checkoutNameYesUnique name of the Checkout. For Amazon Pay this is the value amazonpay.
checkoutURLYesURL required to load the Amazon Pay JavaScript Widgets.
acquirerResponseDetailsYesRecord containing details about the Amazon Pay response containing any error messages and codes. This can be used together with the normal responseCode and responseMessage response fields to further determine the reason for any failure.
checkoutRequestNoRecord containing data required for the Amazon Pay Widgets such as:

• merchantID – Amazon Pay merchant id
• clientID – Amazon Pay client id
• sandbox – true if Amazon Pay sandbox
• region – Amazon Pay API region code
• scope – Login Widget scope parameter
checkoutOptionsNoRecord containing any Checkout options passed in the request.

Continuation Request (Checkout Details and Authorise)

On completion of the Amazon Pay Widgets, the Merchant should send the information created by the Widgets to the Gateway together with a status value. If the Checkout was successful, the status will be ‘success’; alternatively, if the Checkout was cancelled, the status will be ‘cancel’. Any accessToken generated by the Amazon Pay Login Widget; orderReferenceID, generated by the Wallet or Address Widgets; and billingAgreementID generated by the optional Billing Widget, must be added to the checkoutResponse field and sent in a new request to the Gateway. The checkoutResponse field can be sent either as a URL query string; as a JSON encoded string; or as an array of parameters. This new request will load the Checkout details, including any purchase and delivery address details as required, and send the transaction to Amazon Pay for authorisation, returning the result as in the case of a normal authorisation transaction. The new request must contain the checkoutRef received in the initial response.

Request Fields

These fields may be sent alone. It is only necessary to send the checkoutRef and the checkoutResponse in the continuation request because the checkoutRef will identify the Merchant Account and initial request. The message does not need to be signed. You can send any of the normal request fields to modify or supplement the initial request – however, in this case the request should be signed. The checkoutRedirectURL and checkoutOptions fields sent in the initial request cannot be modified and any sent in the second request must match those used in the first request, or the second request will fail with a responseCode of 64442 (REQUEST MISMATCH).

NameMandatoryDescription
checkoutRefYesUnique reference returned in the initial response.
checkoutResponseYesThe data received from the Amazon Pay Checkout Widgets together with a status value.
checkoutOnlyNoPass Y to complete the processing as far as the next Checkout stage and then return with the loaded Checkout details.

Response Fields

These fields will be returned, in addition to the request fields above and the basic response fields.

NameMandatoryDescription
checkoutRefYesProvided if checkoutOnly was used in the continuation response to indicate that a further request will be sent to finalise the transaction.
checkoutNameYesUnique name of the Checkout. For Amazon Pay this is the value amazonpay.
checkoutDetailsYesRecord containing options used to customise the Amazon Pay Checkout. Refer to the checkout details section.
acquirerResponseDetailsYesRecord containing details about the Amazon Pay response containing any error messages and codes. This can be used together with the normal responseCode and responseMessage response fields to determine further the reason for any failure.
customerXXXXNoCustomer details if provided by the Amazon Pay Checkout. The response will include the Customer/billing address details if provided by the Amazon Pay Checkout.
deliveryXXXXNoDelivery details if provided by the Amazon Pay Checkout.The response will include the delivery address details if provided by the Amazon Pay Checkout.
receiverXXXXNoBuyer details if provided by Amazon Pay. Amazon Pay will usually provide the buyer’s name, postcode and email only, which are returned in the receiverName, receiverPostcode and receiverEmail fields accordingly

Separate Checkout Details and Authorisation Requests

You can choose to obtain the Checkout details before actually sending the transaction for authorisation by sending the checkoutOnly field in the above continuation request. If this field is sent with a value of ‘Y’ then the Gateway will load the Checkout details and then return them to you without sending the request for authorisation. You can then display them and/or adjust the amount, for example, according to delivery charges appropriate to the received delivery address. You should then send a new request containing the checkou`tRef received to continue the transaction and authorise it.

Note: this stage can be repeated multiple times by including the checkoutOnly field with a value of ‘Y’ each time. To complete the transaction, the final request must not contain the checkoutOnly field or it must not have a value of ‘Y’.

Checkout Options

The following options may be set in the checkoutOptions field to customise the Amazon Pay Checkout. The options must be formatted using the record or serialised record formats detailed in the format guide.

NameDescription
billingAgreementRequiredCan be used to specify that a billing agreement must be started. Alternatively, the rtAgreementType standard integration field can be used with a value of ‘recurring’ or ‘instalment’.
shippingAddressRequiredIndication that the shipping address is required, and the Address Checkout Widget will be used.
sellerOrderIDThe Merchant specified identifier for this order. If not sent, then any value in the merchantOrderRef standard integration field is used.
sellerNoteRepresents a description of the order that is displayed in emails to the buyer.
sellerAuthorizationNoteA description for the authorisation transaction that is shown in emails to the buyer.
sellerCaptureNoteA description for the capture that is displayed in emails to the buyer.
sellerBillingAgreementIDThe Merchant specified identifier for this billing agreement. If not sent, then any value in the rtPolicyRef standard integration field is used.
customInformationAny additional information that you want to include with this order reference
supplementaryDataSupplementary data.
softDescriptorThe description to be shown on the buyer's payment statement.
billingAgreementRequiredCan be used to specify that a billing agreement must be started. Alternatively, the rtAgreementType standard integration field can be used with a value of ‘recurring’ or ‘instalment’.
shippingAddressRequiredIndication that the shipping address is required, and the Address Checkout Widget will be used.

For further information on the options refer to the Amazon Pay API Reference Guide: https://pay.amazon.com/us/developer/documentation/apireference/201751630.

Checkout Details

The checkoutDetails field included in the response above will contain the following values and any further values received from Amazon Pay allowing the Merchant to see the full Amazon Pay order information. The details will be returned using the record format detailed in the format guide.

NameMandatoryDescription
referenceIDNoAmazon Pay reference id. Either the orderReferenceID or the billingReferenceID where appropriate.
accessTokenNoAmazon Pay access token as sent in the continuation request checkoutResponse data.
bilingAgreementIDNoAmazon Pay billing agreement id as sent in the continuation request checkoutResponse data.
orderReferenceIDNoAmazon Pay order reference id as sent in the continuation request checkoutResponse data.

Transaction Lifecycle

Amazon Pay transactions will use the normal Authorise, Capture life cycle as documented in the section Authorise, Capture and Settlement with the following differences.

Capture

Captures made by the Direct Integration or Merchant Management System (MMS) are sent to Amazon Pay immediately the transaction will be left in either the accepted or rejected terminal state depending on whether Amazon Pay accepted or rejected the capture request. Unlike card payments, captures do not flag the transaction to be included in the nightly settlement batch and therefore, when done they cannot be redone. This means that it is not possible to change the amount to be captured or cancel the transaction when a capture has been requested.

Captures that are not explicitly performed such as normal transactions or those with a captureDelay are still done as part of the nightly settlement batch.

Transactions that are not captured within 3 days will be placed in a pending state in the Amazon Pay system which is reflected as the tendered state in the Gateway and will show on the Merchant Management System as being settled.

Refund Sale

Amazon Pay transactions can be refunded the same as normal card transactions. however, like capture requests, these will be sent to Amazon Pay immediately and not batched up and sent as part of the nightly settlement process. This means the transaction will be left in either the accepted or rejected state depending on whether Amazon Pay accepted or rejected the refund request.

Refunds can be made for full or partial amounts, with multiple refunds allowed up to the original authorised amount.

Reference Transactions

Amazon Pay does not allow ad hoc Credentials on File (COF) type repeat or recurring transactions using the xref of a reference transaction unless that transaction has specifically started an Amazon Pay Billing Agreement.

If you want to be able to make future repeat or recurring transactions, then the initial transaction must include an rtAgreementType of recurring or instalment. Alternatively, the billingAgreementRequired option can be included in the checkoutOptions so as to identify this transaction as the start of a recurring billing sequence.

This will cause the Gateway to request Amazon Pay setup a Billing Agreement between you and the Customer. In this case the Amazon Pay Billing Consent Widget must be used in the Checkout and the billingAgreementID it creates sent in the checkoutResponse data in the continuation request. Any billing agreement id will be displayed on the Merchant Management System (MMS) as part of the payment details so that you can easily see which Amazon Pay transactions can be used for recurring billing.

Pay by Bank app (PBBA) Transactions

Pay by Bank app (PBBA) is an additional payment method that is available to all Merchants using the Gateway that have a Pay by Bank app account and an OBN Global Acquiring account.

PBBA, formerly known as Zapp, is an innovative, secure, and fully digital payment option in the UK, built and operated by VocaLink, a Mastercard company. It allows your Customers to pay, in real time, using the banking app on their phone. It's designed to make online checkout easier, whilst using all the security of their bank. Payments work through secure digital tokens, meaning your Customers never reveal any of their financial details when they are shopping.

To use PBBA you will be supplied with a separate PBBA Merchant account that can be grouped with your main Merchant Account using the account mapping facility as documented in the merchant account mapping section. This allows transactions to be sent using your main Merchant Account and then routed automatically to the PBBA Merchant Account in the same mapping group.

All transactions created with this payment method will appear in the Merchant Management System (MMS) together with the payment method that was used to process the transaction.

PBBA transactions cannot be used for ad-hoc Credentials on File (COF) repeat transactions or for recurring billing.

For more information on how to accept PBBA transactions please contact customer support.

Benefits

  • Increased conversion rate through a simple, quick payment process.
  • Secure payment processing in real time.
  • Lower transaction cost compared to card payments.
  • Minimal fraud risk thanks to ‘Request to Pay’ technology.
  • Quick and convenient processing of refunds and disputes.
  • Integration on websites and in mobile apps.
  • Transactions are controlled within the Merchant Management System (MMS) in the same manner as normal card transactions.

Limitations

  • You will need a PBBA account and OBN Acquiring account.
  • Recurring transactions are not supported.
  • Independent refunds are not supported.
  • Transactions require a browser or mobile device in order to display the PBBA Checkout.
  • Your Customer will need a mobile device in order to display their Banking app.
  • Payment authorisation is not instantaneous and will require additional ‘QUERY’ requests.
  • Only available in the UK.
  • Transactions require a browser or mobile device in order to display the PBBA Checkout.
  • Customers require a mobile device in order to display their Banking app.

Implementation

PBBA transactions are designed to be integrated with and invoked by the Merchant Button Integration Library code made available by Mastercard for embedding the PBBA payment button on your website or mobile application (The current PBBA Merchant Integration Libraries are available from Mastercard).

PBBA only supports the SALE, REFUND_SALE, CANCEL and CAPTURE actions. This section explains how to make payment requests. Management requests are performed as detailed in the management operations section.

Payment Request

To request that a transaction be processed via PBBA, the request must contain a paymentMethod of ‘pbba’. In addition, you must send checkoutOptions to provide information about the Customer’s device. When the Gateway receives these two fields, assuming there are no other errors with the request, it will attempt to find a suitable PBBA Merchant Account in the current account mapping group (refer to the merchant account mapping 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 initiate the PBBA transaction and respond with a responseCode of 0 (SUCCESS) and included in the response will be a checkoutDetails field containing the Basket Reference Number (BRN) that should be displayed to the Customer.

Please note that the payment has not completed until the Customer enters the BRN into their mobile banking application and confirms the payment. The response will contain a state of received until the Gateway has received confirmation from the banking network that the payment has been confirmed by the Customer.

To determine when payment has completed you may periodically poll the Gateway using a QUERY request to check the state of the transaction. For more information on the QUERY request, please refer to the management operations section.

Request Fields

NamemandatoryDescription
paymentMethodYesPayment method to be used. Must be pbba.
checkoutOptionsNoRecord containing options used to customise the PBBA Checkout. See the checkout options section. Whilst the Gateway does not see this field as mandatory, PBBA mandates that certain options are provided.

Response Fields

These fields will be returned in addition to the request fields above and the basic request fields.

NamemandatoryDescription
checkoutDetailsYesRecord containing values made available by the PBBA Checkout. Refer to the checkout details section.

Checkout Options

The following options must be sent in the checkoutOptions Direct Integration field to customise the Checkout. Unlike other payment methods these options are mandatory and must be sent. The options must be formatted using the record or serialised record formats detailed in the format guide.

NameDescription
device.typeConsumer device type. This field is mandatory and has no default value.

Possible values are:
ATM – ATM device
MOBLPHN – Mobile phone device
PCLAPTP – PC or Laptop device
TABLET – tablet device
OTHERS – other device type
device.osConsumer device operating system. This field is mandatory and has no default value.

Possible values are:
AND – Android
IOS – Apple iOS
WIN – Microsoft Windows
WINMOB – Microsoft Windows Mobile
OTHERS – other operating system
browser.userAgentContent of HTTP User-Agent header received from the Consumer’s device. Maximum 127 characters.
browser.timeZoneTime zone offset in minutes between UTC and the Consumer’s device. The offset is positive if the local time zone is behind UTC and negative if it is ahead.
browser.screenResolutionScreen resolution of the Consumer’s device. Formatted as the height and width separated by a ‘x’. The height and width must be between 1 and 9999 pixels.
browser.acceptEncodingContent of HTTP Accept-Encoding header received from the Consumer’s device. Maximum of 127 characters.
browser.acceptLanguageContent of HTTP Accept-Encoding header received from the Consumer’s device. Maximum of 127 characters.

The category.name format of the sub-field name indicates that option’s value is a record called category containing a sub-field called name.

Checkout Details

The checkoutDetails field included in the response above will contain the following values which should be provided to the client-side PBBA Integration Library. The details will be returned using the record format detailed in the format guide.

NamemandatoryDescription
transactionIDYesTransaction identifier.
settlementIDYesSettlement retrieval identifier.
pbbaCodeYesBasket reference number (BRN).
secureTokenYesSecure token for client-size use.
retrievalExpiryIntervalYesRetrieval expiry time interval.
confirmationExpiryIntervalYesConfirmation expiry time interval.
cookieSentStatusYesCookie sent status.
payConnectIDNoReserved for future use.
cookieExpiryDaysNoReserved for future use.
riskScoreNoReserved for future use.
bankNameNoReserved for future use.

Refunds

Refund requests require that a reason code be included in either the orderRef or cancelReason fields.

The codes are as follows; DUPLICATEORDER, GOODSRETURNED, ORDERCANCELLED, MERCHANTOUTOFSTOCK, GOODSNOTRECV, LATECONFIRMATION, DISPUTES.

The code must be in uppercase and must appear as a separate word anywhere in the field’s value.

For example, if refunding due to the purchased item being out of stock you could set the value to just “MERCHANTOUTOFSTOCK” or to a more complete description such as “Refund: Green polo shirt, XXL (MERCHANTOUTOFSTOCK)”.

This also applies to refunds made by the Merchant Management System (MMS) where the reason code must be entered when prompted for the reason for the refund.

Only the refund code is sent to the PBBA system, any other text is stored by the Gateway for your benefit and viewable in the Merchant Management System (MMS).

SecurePlus Transactions

SecurePlus is available if you have a Planet Merchant Account. It is a secure e-commerce payment solution designed to allow you to accept China UnionPay debit cards via the Planet Acquirer, with a reduced the risk of fraudulent transactions while providing a friction-free payment process for your Customers. SecurePlus divides the online payment process into separate authentication and authorisation transaction flows that authenticates the cardholder’s identity before you submit the authorisation request.

To use SecurePlus you will be supplied with a separate Planet Merchant Account that can be grouped with your main Merchant Account using the account mapping facility as documented in the merchant account mapping section. This allows transactions to be sent using your main Merchant Account and then routed automatically to the Planet Merchant Account in the same mapping group.

When UnionPay debit cards are issued, the Cardholder must register their mobile number with the Issuer. The SMS code authentication works at the time of checkout by submitting the payment details to UnionPay together with the Cardholder’s mobile number. The Issuer verifies the card and registered mobile number and sends an SMS message to the Cardholder’s mobile phone containing a unique 6-digit code. The Cardholder then enters this code into an authentication dialog provided by the Gateway so that it can be sent to UnionPay for verification. If approved, the final financial transaction is submitted.

The authentication process is only required for debit cards. To accommodate the use of cards stored in secure online wallet, the card authentication has some built-in flexibility when other compensating controls are employed.

SecurePlus transactions will appear in the Merchant Management System (MMS) alongside any card payments and can be captured, cancelled and refunded in the same way as card payments.

SecurePlus transactions can also be used for recurring billing with the SMS authentication not been required on recurring transactions as long as the initial transaction was successfully SMS authenticated.

For more information on how to accept SecurePlus transactions, please contact customer support.

tip

SecurePlus transactions are only available with a Planet Merchant Account.

Benefits

  • Authorisations are available immediately and returned as part of the transaction.
  • Provides your customers the flexibility of paying using their UnionPay debit card when this is more suitable to them than using other payment methods.
  • Can be implemented with little or no extra integration work if you already support 3-D Secure transactions.
  • There are no extra Gateway costs to use SecurePlus. Your Acquirer may charge to add this onto your business account; however, you may also find that your transaction charges are lower as a result of using 3-D Secure.
  • Fully configurable within the Merchant Management System (MMS).

Limitations

  • You will need a Planet Acquiring account, however, such an account can also be used to process all your other card transactions.
  • Only UnionPay debit cards are supported, however, UnionPay credit cards can be accepted without the need for SecurePlus.
  • You must currently provide the Gateway with the Cardholder’s mobile phone number at the time of the transaction. The Hosted Payment Page will prompt the Cardholder for this information if it detects that a UnionPay debit card is being supplied.
  • The Cardholder must have access to their registered mobile phone during the payment process.
  • Transactions require a browser in order to display the Customer SMS code entry dialog.

Implementation

SecurePlus transactions require you to support the 3-D Secure integration as documented in the 3-D Secure section. In addition, the Cardholder’s mobile phone number must be provided in the transaction request.

Request Fields

These fields should be sent in addition to basic 3-D Secure request fields.

NamemandatoryDescription
customerMobileYesMust contain the Cardholder’s mobile phone number as registered with the Issuer. The number must be international format with a leading + symbol followed by up to 3 digits then a space then up to 10 more digits.

Response Fields

There are no additional response fields for SecurePlus other those defined for 3-D Secure.