Last Updated: 10 October 2024 | Change Log

PayPal

A secure and globally accepted online payment transfer.

Note

Make yourself familiar with our API Principles to ensure a resilient integration.

Product Overview

Why use PayPal

PayPal is a global payment method with strong consumer recognition and trust. It is also one of the most popular APMs in the world. PayPal opens up a large customer base who already have PayPal accounts and can make purchases with a payment flow that they are comfortable with.

It is accepted in over 200 countries, supports 25 currencies and is a mainstay of APM payments.

Feature summary

Payment typeCountriesRecurringReversalsPartial ReversalsDisputesAuth onlyAuth and Settlement (Sale)
Digital WalletGlobal acceptance
  • Partial refund - yes
  • Partial cancel- No
Handled directly via PayPal

Acceptance currencies

CurrencyCurrency Codes
Australian DollarAUD
Brazilian RealBRL
Canadian DollarCAD
Czech KorunaCZK
Danish KroneDKK
EuroEUR
Hong Kong DollarHKD
Hungarian ForintHUF
Indian RupeeINR
Israeli New ShekelILS
Japanese YenJPY
Malaysian RinggitMYR
Mexican PesoMXN
New Taiwan DollarTWD
New Zealand DollarNZD
Norwegian KroneNOK
Philippine PesoPHP
Polish ZłotyPLN
Pound SterlingGBP
Singapore DollarSGD
Swedish KronaSEK
Swiss FrancCHF
Thai BahtTHB
United States DollarUSD

Payment flows

There are two different ways to integrate PayPal:

  • Redirect URL mechanism
  • Smart Button

Redirect URL

Your customer's are redirected to a web broswer to log into PayPal

Smart Button

Your customer clicks on the Smart Button, a pop-up window opens on top of their payment screen.

You must integrate using the PayPal SDK using the JavaScript SDK script configuration developer guide.

Important

The payment-source within the Paypal SDK must be "paypal" when integrating with Access Worldpay. This enables the PayPal option within the SDK. Other payment methods, offered by the PayPal SDK, will not work with Access Worldpay.

You can also customize the Paypal Smart button. The options are:

  • the size, color and shape of the button
  • the language that appears on the buttons
  • the layout of the button: horizontal or vertical

Set your headers

Setting your headers is an important part of an API request. The headers represent the meta-data associated with your API request.

Authorization: {your_credentials}
Content-Type: application/json
WP-Api-Version: 2023-06-01
HeaderDescription
AuthorizationWe use the Authorization header to identify and authenticate you within Access Worldpay. You must use the Authorization header for any request you send to our APM API, unless you are using client certificate authentication over TLS. If you must use this, read our reference guide on Authenticating with SSL/TLS.
Content-TypeWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a POST or a PUT.
WP-Api-VersionWe use the WP-Api-Version header to identify which version of our APM API you are using. You must use the WP-Api-Version header for any request you send to our API.

If you're using both the Content-Type and WP-Api-Version headers, they must match.

Note

Replace {your_credentials} with your base64-encoded Basic Auth username and password. To get your Access Worldpay credentials contact your Implementation Manager.

Request

POST https://try.access.worldpay.com/apmPayments

Example request

application/json
{ "transactionReference": "Memory265-13/08/1876", "merchant": { "entity": "default" }, "instruction": { "narrative": { "line1": "MindPalace" }, "value": { "amount": 35, "currency": "GBP" }, "paymentInstrument": { "type": "paypal", "requestAutoSettlement": { "enabled": true }, "shopperEmailAddress": "shopper@example.com", "billingAddress": { "address1": "221B Baker Street", "address2": "Marylebone", "address3": "Westminster", "postalCode": "NW1 6XE", "city": "London", "state": "Greater London", "countryCode": "GB" }, "shippingAddress": { "address1": "The Palatine Centre", "postalCode": "DH1 3LE", "city": "Durham", "state": "County Durham", "countryCode": "GB" }, "successURL": "https://example.com/success", "pendingURL": "https://example.com/pending", "failureURL": "https://example.com/failure", "cancelURL": "https://example.com/cancel" } } }

Parameters

ParameterRequired?DescriptionData typeLength
merchantAn object that contains information about the merchant.ObjectN/A
merchant.entityDirect your payment to assist with billing, reporting and reconciliation. This is mandatory for Authentication and Queries.
Contact your Implementation Manager for more details.
StringMust be between 1 and 32 characters.
transactionReferenceA unique reference generated by you that is used to identify a payment throughout its lifecycle. See transaction reference format.StringMust be between 1 to 64 characters.
instructionAn object that contains all the information related to the payment.ObjectN/A
instruction.narrativeAn object that helps your customers better identify you on their statement.ObjectSee our formatting rules
instruction.narrative.line1The first line of the narrative which appears on your customer's statement (If a character is not supported it is replaced with a space.).
See narrative line1 format for more details.
Object24
instruction.valueAn object that contains information about the payment transaction.ObjectN/A
instruction.value.amountThe payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2,50. You can find the relevant exponent in our currency table.IntegerN/A
instruction.value.currencyThe payment currency. Refer to the individual APM page for supported currencies.Integer3
instruction.paymentInstrumentAn object that contains information about the payment method.ObjectN/A
instruction.paymentInstrument.typeAn object that contains the payment type and details. It defines which alternative payment method you wish to use. For PayPal the value is paypal.ObjectN/A
instruction.paymentInstrument.requestAutoSettlementSettles the transaction automatically when set to "true".ObjectBoolean
"true" or "false". Default: "false".
paymentInstrument.shopperEmailAddressThe email adddress of your customer.StringN/A
instruction.paymentInstrument.cancelURLWhen your customer cancels a transaction, we redirect your customer to that cancel URL.StringN/A
instruction.paymentInstrument.failureURLWhen a payment fails, we redirect your customer to the failure URL.StringN/A
instruction.paymentInstrument.pendingURLWhen we receive the payment result for a pending payment transaction, we redirect your customer to that pending URL.StringN/A
instruction.paymentInstrument.successURLWhen we receive the payment result for a successful payment, we redirect your customer to that success URL.StringN/A
paymentInstrument.billingAddressThe billing address of your customer.ObjectN/A
paymentInstrument.billingAddress.address1ConditionalFirst line of the billing address.
Condition: Must be provided if you send paymentInstrument.billingAddress.
String1-85
paymentInstrument.billingAddress.address2Second line of the billing address.String0-85
paymentInstrument.billingAddress.address3Third line of the billing address.String0-85
paymentInstrument.billingAddress.cityThe city of the billing address.String0-50
paymentInstrument.billingAddress.countryCodeConditionalThe country of the billing address.
Condition: Must be provided if you send paymentInstrument.billingAddress. Follows alpha 2 ISO 3166-1 standard.
String2
paymentInstrument.billingAddress.postalCodeConditionalThe poste code of the billing address.
Condition: Must be provided if you send paymentInstrument.billingAddress.
String1-15
paymentInstrument.billingAddress.stateThe state of the billing address.String1-50
paymentInstrument.shippingAddressThe shipping address of your customer.ObjectN/A
paymentInstrument.shippingAddress.address1ConditionalFirst line of the shipping address.
Condition: Must be provided if you send paymentInstrument.shippingAddress.
String1-85
paymentInstrument.shippingAddress.address2Second line of the shipping address.String0-85
paymentInstrument.shippingAddress.address3Third line of the shipping address.String0-85
paymentInstrument.shippingAddress.cityThe city of the shipping address.String0-50
paymentInstrument.shippingAddress.countryCodeConditionalThe country of the shipping address.
Condition: Must be provided if you send paymentInstrument.shipppingAddress. Follows alpha 2 ISO 3166-1 standard.
String2
paymentInstrument.shippingddress.postalCodeConditionalThe poste code of the shipping address.
Condition: Must be provided if you send paymentInstrument.shippingAddress.
String1-15
paymentInstrument.shippingAddress.stateThe state of the shipping address.String1-50
Recommendation

We suggest you provide the cancelURL,failureURL, pendingURL and successURL attribute to redirect your customer to, once you have received the payment result.

Response

Successful request response

  • an HTTP code 201
  • an id which is unique to the payment - we recommend storing the "id" as this can be used to manage the payment later
  • a url to redirect your customer to the APM provider to complete the payment
  • a link to query the payment status
  • an object which will give flow information such as method (e.g. paypal), type (sdk for a Smart Button flow or redirect for a Redirect URL flow) and an sdk token
Note
  • for the Smart Button flow use the sdkReference to generate the Smart Button
  • for the redirect flow use the url in the response to redirect your customer

Example Response

{
    "paymentId": "nFxASqw-LV9HE_rr1mMONP6OuaBhNYiq0jRwvvUBRLffpu0O_8mOnTpFSIM9gnTSg8thuF8qvuzMKHjhAUKA-SBywF4F_ufX78jkgX7yoPwA8HF_HMLM0RSLDKrlDpMxs5bSRRbjItu_Me3kIkraos_XGMXXDzWYsmzASPr6BGo",
    "lastEvent": "pending",
    "_links": {
        "self": {
            "href": "https://access.worldpay.com/apmPayments/nFxASqw-LV9HE_rr1mMONP6OuaBhNYiq0jRwvvUBRLffpu0O_8mOnTpFSIM9gnTSg8thuF8qvuzMKHjhAUKA-SBywF4F_ufX78jkgX7yoPwA8HF_HMLM0RSLDKrlDpMxs5bSRRbjItu_Me3kIkraos_XGMXXDzWYsmzASPr6BGo"
        },
        "_actions": {
            "confirmPayment": {
                "href": "https://access.worldpay.com/apmPayments/nFxASqw-LV9HE_rr1mMONP6OuaBhNYiq0jRwvvUBRLffpu[…]rlDpMxs5bSRRbjItu_Me3kIkraos_XGMXXDzWYsmzASPr6BGo/confirmations"
            },
            "paymentInstrument": {
                "method": "paypal",
                "type": "sdk",
                "sdkReference": "2HG28153DX910101U"
            }
        }
    }
}
Note

In case of an error, you can get further information in our error reference.

PayPal Smart Button flow

Payment confirmation

Once your customer has closed the PayPal iframe, you must confirm the payment when using the PayPal Smart Button. This is done by using the confirmPayment href returned in the payment request response.

Make a POST request on the link:actions action link returned in your payment response.

POST https://try.access.worldpay.com/apmPayments/nFxASqw-LV9HE_rr1mMONDTNO21DI7iBqIBDP8tbNT_pHfdVKepSMngqe9EDiBI1pHXEu-SbvqJyvSludyCd-2L21mL7uoB8zl62Ayz7E3GblXYsLnrW2-IZDMChfXfwWt7xrjVsKEPMGearp4PdIQp8hQ6k4_KTkZa_frsM4TQ/confirmations

Note

No request body is needed for this request.

Next Steps


Manage your PayPal payment