PayPal

brand-paypal.png

PayPal is an international e-commerce business allowing payments and money transfers to be made online.

  Supported customer countries   No restrictions on customer countries.
  Supported currencies   AUD, CAD, EUR, GBP, JPY, USD
  Refunds

  Full and partial refunds permitted.

  Chargebacks

  Disputes are managed by PayPal.

 

Process overview

ppg-paypal-01.png

 

Configuration

  1. To enable this payment method on your account, please follow the steps outlined in our Enabling PayPal guide.
  2. Once you have completed the above, you will need to modify your POST to Payment Pages as needed:

    Field name

    Required during payment session

    (Either included in POST by merchant or entered by customer on Payment Pages)

    Required in POST Description
    customerprefixname
    Conditional No

    These delivery fields are required when paypaladdressoverride is 0 or 1.

    You must submit at least one of the customer name fields.

    At least one of the customer name fields are required when paypaladdressoverride is 0 or 1.

    customerfirstname
    Conditional No
    customermiddlename Conditional No
    customerlastname
    Conditional No
    customersuffixname
    Conditional No
    customerpremise Conditional No
    customertown Conditional No
    customercountryiso2a Conditional No
    customerpostcode Conditional No
    customercounty Conditional No

    The county entered for the delivery address.

    This is displayed as “State code (eg. NY)” on pages with US locale and “County” on other configurations.

    For US addresses, the state would be entered in this field.

    Valid formats:

    • Preferred: Two character state code, e.g. “NY”.
    • Full state name (no abbreviations), e.g. “New York”.

    Required if customercountryiso2a is one of the following: AR, BR, CA, CN, ID, IN, IT, JP, MX, TH, US

    orderreference No No If submitting the order reference field, the value of this field is sent to PayPal as the invoice id. PayPal performs checks for duplicate invoice ids, so please ensure any order reference submitted in the POST is unique to each transaction.

    Note: You can configure your PayPal account to disable the check on duplicate invoice ids. Contact PayPal Support for further information.

    Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction.

    paypaladdressoverride No No By default, the customer selects their delivery address from their PayPal account. Alternatively, the customer can use the address entered on your website. This behaviour is controlled by sending the paypaladdressoverride field in the initial POST to the Payment Pages:
    • 0 – Customer will be offered a choice between the delivery address entered on your website and addresses on their PayPal account.
    • 1 – Customer will use the delivery address entered on your website.
    • 2 – Customer will not be prompted to choose a delivery address on PayPal’s website (best suited to online services and downloads).
    paypallocaleiso2a No No Use this field to localise the content displayed on the PayPal checkout. For a full list of supported values that can be submitted in this field (e.g. paypallocaleiso2a=GB for the UK), please refer to PayPal’s documentation.
    ruleidentifier No No

    If your POST to the Payment Pages already includes all fields required by the payment method, you can streamline the checkout process for the customer by also submitting ruleidentifier=STR-14.

    This allows the customer’s browser to immediately go to the pages hosted by the payment method to complete the transaction. (We refer to this as Journey C)

    Click here to learn about different journeys.

  To ensure the customer cannot modify the delivery address submitted to the Payment Pages, the fields above must be added to your designated fields for your request site security.

  PayPal do not support iframe integration.

 

Notifications

Once a payment has been authorised, funds will be settled at a later time, as determined by PayPal.

  The settlement notification may not be sent immediately after processing the payment.
In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.

  You can have your site reference(s) configured to request PayPal transactions are settled immediately.
Contact our Support Team for further information.

Before you begin testing, we recommend that you contact our Support Team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:

  • When a payment is authorised.
  • When funds have been settled.

 

Configuring the authorisation notification

We recommend including at least the following fields in your authorisation notification:

  • Auth code (authcode)
  • Base Amount (baseamount) (e.g. £10.50 is “1050”)*
  • Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
  • Billing Country (billingcountryiso2a)
  • Currency (currencyiso3a)
  • Error Code (errorcode)
  • Live Status (livestatus)
  • Order Reference (orderreference)
  • Payment Type (paymenttypedescription)
  • PayPal Email (paypalemail)
  • PayPal Payer Id (paypalpayerid)
  • Request Type (requesttypedescription)
  • Settle Status (settlestatus)
  • Site Reference (sitereference)
  • Transaction Reference (transactionreference)
  • Transaction Started Timestamp (transactionstartedtimestamp)

*Please choose your preferred format.

 

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

  • Settle Status (settlestatus)
  • Site Reference (sitereference)
  • Transaction Reference (transactionreference)

 

Check the notification

You will need to check the contents of each notification received and respond accordingly by following the processes outlined in our URL notifications documentation. In particular, you will need to look at the updated settlestatus value:

  • On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
  • On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

 

Testing

You will need to test your solution before you can begin processing live payments. Test transactions are processed through your test Site Reference.

When performing test transactions, your browser will be redirected to our simulated PayPal checkout page. Follow the instructions on-screen to complete a payment, after which, you will be redirected back to the Payment Pages.

 

Refunds

After processing a payment, it is possible to refund the customer using MyST.

  To ensure our records remain in sync with PayPal, we strongly recommend that you only perform refunds through Trust Payments. Do not perform refunds directly using your PayPal admin portal.

Standard PayPal refunds are settled immediately (settlestatus “100”). However, under certain conditions defined by PayPal, refunds can be set to settlestatus “10” (“settling”), which is an intermediate step prior to settlement.

  If a PayPal refund on your account is in settlestatus “10”, it is recommended you query it with our Support Team, in case further actions need to be completed to ensure settlement.

 

Requirements

  • You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
  • You cannot refund a greater amount than was originally settled.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request