Pay with PayPal

APMs v1
Last updated January 2023

Initiate a PayPal payment and instantly trigger the settlement process.

Take a sale

POST your request to the paypal:sale action link.

Sale example request


PayPal sale request body:

  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "MindPalaceLtd"
  "instruction": {
    "description": {
      "line1": "order description"
    "paymentInstrument": {
      "type": "PAYPAL",
      "shippingAddress": {
        "firstName": "James",
        "lastName": "Moriarty",
        "street": "The Palatine Centre",
        "postalCode": "DH1 3LE",
        "city": "Durham",
        "state": "County Durham",
        "countryCode": "GB"
      "billingAddress": {
        "firstName": "Sherlock",
        "lastName": "Holmes",
        "address1": "221B Baker Street",
        "address2": "Marylebone",
        "address3": "Westminster",
        "postalCode": "NW1 6XE",
        "city": "London",
        "state": "Greater London",
        "countryCode": "GB"
    "value": {
      "currency": "GBP",
      "amount": 1

Parameter descriptions

transactionReferenceA unique transaction reference for this sale.
merchant.entityUsed to route the sale request in Access Worldpay, created as part of on-boarding.
instructionAn object containing all the payment information related to the sale request.
instruction.description.line1A field containing the order description.
instruction.paymentInstrumentAn object containing customer details.
paymentInstrument.typeThe type of payment instrument. The value must be "PAYPAL".
paymentInstrument.shippingAddressAn object containing the shipping address information. If included in the request, you must send atleast:
  • street
  • postalCode
  • city
  • countryCode
paymentInstrument.shippingAddress.firstNameThe customer's first name.
paymentInstrument.shippingAddress.lastNameThe customer's last name.
paymentInstrument.shippingAddress.streetThe street name of the shipping address. Mandatory if you include shippingAddress in the request.
paymentInstrument.shippingAddress.postalCodeThe post code/ zip code of the shipping address. Mandatory if you include shippingAddress in the request.
paymentInstrument.shippingAddress.cityThe city of the shipping address. Mandatory if you include shippingAddress in the request.
paymentInstrument.shippingAddress.stateThe state of the shipping address.
paymentInstrument.shippingAddress.countryCodeThecountry codeof the shipping address. Mandatory if you include shippingAddress in the request.
paymentInstrument.billingAddressAn object containing the billing address information.
paymentInstrument.billingAddress.firstNameThe customer's first name.
paymentInstrument.billingAddress.lastNameThe customer's last name.
paymentInstrument.billingAddress.shopperEmailAddressThe customer's email address.
paymentInstrument.billingAddress.address1First line of the billing address.
paymentInstrument.billingAddress.address2Second line of the billing address.
paymentInstrument.billingAddress.address3Third line of the billing address.
paymentInstrument.billingAddress.postalCodeThe post code/ zip code of the billing address.
paymentInstrument.billingAddress.cityThe city of the billing address.
paymentInstrument.billingAddress.stateThe state of the billing address.
paymentInstrument.billingAddress.countryCodeThecountry codeof the billing address.
instruction.valueAn object containing the value of the sale.
instruction.value.currencyAn identifier for the currency being used.
instruction.value.amountAn identifier for the amount being used.

Sale response

Successful order

You receive:

  • an HTTP code 201
  • PayPal orderId (This is used in conjunction with your PayPal smart button to redirect a customer to their PayPal account)
  • an outcome
  • links toqueryyour payment

Example response:

  "orderId": "orderId",
  "outcome" : "pendingSale",
  "_links": {
    "action:events": {
      "href": ""
    "curies": [
        "name": "action",
        "href": "{rel}",
        "templated": true

You receive an outcome of pendingSale. This doesn't mean that the payment has been fully processed. The customer must now complete their payment using the PayPal Smart Button.

Find out the latest status of your payment by using our notification or query service described in ourmanage your paymentsection.

Note: In case of an error, you can get further information in ourerror reference.

Next steps

Manage your payment