API Reference
API Reference
Start typing to search…

PayPal

Table of Contents

  • [1 Introduction]
  • [2 Payment Flow]
  • [3 Resources and Operations]
    • [3.1 Get Redirect URL Request]
    • [3.2 Get Redirect URL Response]
    • [3.3 Capture/Refund/ReversePreAuth request]
    • [3.4 Capture/Refund/ReversePreAuth response]
    • [3.5 Get status and details of transaction request & response]

1. Introduction

Merchants integrated to AnyPay can now offer PayPal payment methods to their clients, such as Capture, Refund, ReversePreauthorization. These methods are available via PXP Checkout and work similarly to their card corresponding methods.

2. Payment Flow

3. Resources and Operations

3.1 Get Redirect URL Request

This request is used for PayPal Redirect Authorisation

Resource: POST /api/v5/checkout

Request Parameters

Name

Required

Data Type

Description

merchantId

Mandatory

String

Unique Merchant Id provided by PXP

storeId

Mandatory

String

Unique Store Id provided by PXP

userId

Mandatory

String

A username allocated to a service user when the service is set up

type

Mandatory

String

A combination of how the card was captured and transaction type of the transaction. i.e. ecom.sale, ecom.preAuthorization.

amount

Mandatory

String

The monetary value of the transaction in minor units.
See Note1

currencyCode

Mandatory

String

The currency of the transaction. A three character code in accordance with ISO 4217

clientSystemTransactionId

Mandatory

String

The merchant’s own unique reference for the transaction

providerDiscretionaryData

Optional

String

The merchants external facing order number with the consumer, which if supported, will be passed to the Provider as an additional descriptor.

Details

providerMerchantId

Optional

String

The merchant Id that will be used when requesting authorization through the acquirer. If the providerMerchantId is not populated PXP will associate the Merchant Id based on card and currency.

checkoutDetails

skinId

Optional

String

The skinId to reference the style of the page. If not supplied PXP will default to the skin previously agreed with the merchant during setup.

language

Optional

String

The language that the Checkout screen will be displayed in

paymentMethod

Mandatory

String

The hard value is PayPalV2

cardholderId

Optional

String

The cardholderId used to uniquely identify the card holder such as account number for card holder that the merchant holds.

cardholderFirstName

Optional

String

The cardholder’s first name.

cardholderLastName

Optional

String

The cardholder’s last name.

cardholderEmail

Optional

String

The e-mail address of the card holder.

cardholderMobilePhone

Optional

String

The mobile phone number of the card holder in the format {1-3 Digit country calling code}-{Phone Number}

cardholderHomePhone

Optional

String

The home phone number of card holder.

cardholderWorkPhone

Optional

String

The work phone number of card holder.

redirectUrlTimeout

Optional

Int32

The timeout value in seconds to be set against the transaction request. 0 = no expiration, maximum time is 900 seconds.

addressDetails

billingAddress

houseNumber

Mandatory

String

The house number of the cardholder’s billing address.

Street

Mandatory

String

The street name of the card holder’s billing address

City

Mandatory

String

The city of the card holder’s billing address

zipPostalCode

Mandatory

String

The zip or postal code of the card holder’s billing address

State

Optional

String

The region or state in ISO 3166-2 format.

countryCode

Mandatory

String

The ISO 3166 alpha-3 country code of the card holder’s billing address

shippingAddress

firstName

Optional

String

The shipping address first name

lastName

Optional

String

The shipping address last name

telephoneNumber

Optional

String

The phone number of where the item is being shipped.

Email

Optional

String

The email address of the person that the delivery is being shipped to

houseNumber

Optional

String

The house number of the shipping address

Street

Optional

String

The street name of the shipping address

City

Optional

String

The city of the shipping address

zipPostalCode

Optional

String

The zip or postal code of the shipping address.

State

Optional

String

The region or state in ISO 3166-2 format

countryCode

Optional

String

The ISO 3166 alpha-3 country code of the cardholder’s shipping address

redirectDetails

returnUrl

Mandatory

String

The URL where the customer will be redirected, in case he wants to go back to the merchant’s website.

successUrl

Mandatory

String

The URL where the customer will be redirected, when the payment was successful.

pendingUrl

Mandatory

String

The URL where the customer will be redirected, when the payment is pending by the APM provider.

errorUrl

Mandatory

String

The URL where the customer will be redirected, when the payment was unsuccessful for any reason.

cancelUrl

Mandatory

String

The URL where the customer will be redirected, when the payment was cancelled on the APM site. If not applicable for chosen APM, then populate this with the same “errorUrl”.

refusedUrl

Mandatory

String

The URL where the customer will be redirected, when the payment was cancelled on the APM site. If not applicable for chosen APM, then populate this with the same “errorUrl”.

shoppingCardDetails

totalTaxAmount

Conditional

String

The monetary value of the total tax amount in minor units for the entire order, including any shipping tax. Sum of all itemDetail.item.totalTaxAmount already calculated at a per line level plus shippingTaxAmount. Required if taxRate > 0 or shippingTaxRate > 0
See Note1

  • itemDetails_ (Array)

productId

Mandatory

The client facing article number, SKU or similar.

productName

Mandatory

The merchant’s descriptive product name for the item line

productDescription

Optional

The merchant’s product description for the item line

productType

Optional

The type of product being sold for the item line. Supported values are “physical”, “digital”, “giftcard”, “surcharge”

productQuantity

Mandatory

Int32

The quantity for the item line. Allowed values are 1 – 9999.

unitAmount

Mandatory

String

The monetary value in minor units for the item line.
Must include tax if applicable, but exclude any discount
See Note1.

unitTaxAmount

Conditional

String

The monetary value of the tax amount in minor units for the item line.
See Note1.

taxRate

Conditional
Required if unitTaxAmount supplied

String

The tax rate that is being applied to the unitAmount for the line item. If no tax applies, then send 0 or don’t include this element.

totalAmount

Mandatory

String

The monetary value of the total amount in minor units for the item line. (unitAmount*productQuantity) – discountAmount. Must include tax and any discount if applicable.
See Note1.

totalTaxAmount

Conditional
Required if taxRate > 0

String

The monetary value of the total tax amount in minor units for the item line.
See Note1.

discountAmount

Optional

String

The non-negative monetary value of the discount amount in minor units for the item line.
See Note1

discountName

Optional

String

The name of the discount or promotion being used for the item line. Required if discountAmount > 0

discountTaxAmount

Optional

String

The tax amount of the discount or promotion being used for the item line. Required if taxRate > 0 and discountAmount > 0
See Note1

shippingDetails

shippingName

Conditional

String

The name of the Shipping service for the order. Required if shippingAmount > 0

shippingAmount

Conditional

String

The monetary value of the total shipping amount in minor units for the entire order.
See Note1.

shippingTaxAmount

Conditional

String

The monetary value of the total shipping amount in minor units for the item line.
See Note1.

shippingTaxRate

Conditional

String

The tax rate that is being applied to the shippingAmount for the entire order.

  • discountDetails_ (Array)

discountAmount

Optional

String

The non-negative monetary value of the discount amount in minor units or the entire order.
See Note1.

discountType

Conditional

String

The type of the discount or promotion being used for the entire order. Accepted values are “discount”, “storecredit” and “giftcard”. Required if discountDetails.discount.discountAmount is supplied.

discountName

Conditional

String

The name of the discount or promotion being used for the entire order. Required if discountDetails.discount.discountAmount is supplied.

Note1: The decimal separator/radix character used is the Period ('.') used to indicate decimal places. Other characters such as Comma (',') will not be recognised and may result in an unintended amount being processed.

Example:

{
    "merchantId": "PSH",
    "storeId": "PSH500000001",
    "userId": "PSH001",
    "type": "ecom.preAuthorization",
    "amount": "110.61",
    "currencyCode": "EUR",
    "clientSystemTransactionId": "290224_01",
    "providerDiscretionaryData": "290224_01",
    "details": {
        "providerMerchantId": "2100112262"
    },
    "checkoutDetails": {
        "PaymentMethod": "paypalv2",
        "SkinId": "111-111-111",
        "CardholderId": "",
        "Language": "EN",
        "CardHolderEmail": "[email protected]",
        "CardHolderHomePhone": "447975777666",
        "CardHolderMobilePhone": "447975777666",
        "CardHolderWorkPhone": "447975777666",
        "RedirectUrlTimeout": 900,
        "CardHolderFirstName": "Alessio",
        "CardHolderLastName": "Rodia",
        "CardholderNationalIdentificationNumber": "12345678912345678"
    },
    "addressDetails": {
        "billingAddress": {
            "houseNumber": "97",
            "street": "High Street",
            "city": "London",
            "zipPostalCode": "EN10 7BC",
            "state": "",
            "countryCode": "GBR"
        },
        "shippingAddress": {
            "houseNumber": "96",
            "firstName": "John",
            "lastName": "Wilson",
            "telephoneNumber": "447975777666",
            "email": "[email protected]",
            "street": "Too High Street",
            "city": "Tipton",
            "zipPostalCode": "EN11 8BC",
            "state": null,
            "countryCode": "GBR",
            "deliveryMethod": "ShipToAddress"
        }
    },
    "shoppingCartDetails": {
        "itemDetails": [
            {
                "productId": "ABC001",
                "productName": "Blue Jeans",
                "productDescription": "Stone Washed",
                "ProductType": "physical",
                "productQuantity": "1",
                "unitAmount": "45.00",
                "taxRate": "20",
                "unitTaxAmount": "7.50",
                "discountName": "10% Off Jeans",
                "discountAmount": "4.50",
                "discountTaxAmount": "0.75",
                "totalAmount": "40.50",
                "totalTaxAmount": "6.75"
            },
            {
                "productId": "ABC002",
                "productName": "Wooly Jumper",
                "productDescription": "Black Cashmere",
                "ProductType": "digital",
                "productQuantity": "2",
                "unitAmount": "34.00",
                "taxRate": "20.00",
                "unitTaxAmount": "5.67",
                "discountName": "15% off Jumpers",
                "discountAmount": "2.27",
                "discountTaxAmount": "0.38",
                "totalAmount": "65.73",
                "totalTaxAmount": "10.96"
            },
            {
                "productId": "ABC003",
                "productName": "Kids T Shirt",
                "productDescription": "White - Cartoon Print",
                "ProductType": "surcharge",
                "productQuantity": "1",
                "unitAmount": "15.00",
                "taxRate": "17.54",
                "unitTaxAmount": "2.24",
                "discountName": null,
                "discountAmount": "0",
                "discountTaxAmount": "0",
                "totalAmount": "15.00",
                "totalTaxAmount": "2.24"
            }
        ],
        "shippingDetails": {
            "shippingName": "DHL Next Day Express",
            "shippingAmount": "5.00",
            "shippingTaxAmount": "0.85",
            "shippingTaxRate": "20.55"
        },
        "discountDetails": [
            {
                "DiscountType": "discount",
                "discountName": "5% Loyalty Discount",
                "discountAmount": "12.62"
            },
            {
                "DiscountType": "giftcard",
                "discountName": "£1 Off Discount",
                "discountAmount": "1.00"
            },
            {
                "DiscountType": "storeCredit",
                "discountName": "£2 Off Discount",
                "discountAmount": "2.00"
            }
        ],
        "totaltaxAmount": "20.80"
    },
    "redirectDetails": {
        "returnUrl": "https://merchantweb.pxp-solutions.net/v4/Kalixa/KalixaReturn.asp?TSR=IntegratedKlarna_310802",
        "successUrl": "https://merchantweb.pxp-solutions.net/v4/Kalixa/Kalixasuccess.asp?TSR=IntegratedKlarna_310802",
        "pendingUrl": "https://merchantweb.pxp-solutions.net/v4/Kalixa/KalixaPending.asp?TSR=IntegratedKlarna_310802",
        "errorUrl": "https://merchantweb.pxp-solutions.net/v4/Kalixa/KalixaError.asp?TSR=IntegratedKlarna_310802",
        "cancelUrl": "https://merchantweb.pxp-solutions.net/v4/Kalixa/KalixaCancel.asp?TSR=IntegratedKlarna_310802",
        "refusedUrl": "https://merchantweb.pxp-solutions.net/v4/Kalixa/KalixaRefused.asp?TSR=IntegratedKlarna_310802"
    }
}

3.2 Get Redirect URL Response

Resource: POST /api/v5/checkout

Response Parameters

NameData TypeDescription
redirectUrlStringThe URL that merchant will redirect on browser.

Example:

{
    "redirectUrl": "https://Checkout-integration.pxp-solutions.net/iCheckout/PaymentMethods/395?requestData=qljsvkx4o1syk3ackwjs1i2x_3746932d-502e-4fb6-81ef-5060b96bdf3d"
}

3.3 Capture/Refund/ReversePreAuth request

This request is used for PayPal Capture/Refund/ReversePreAuth

Resource: POST /api/v5/apmTransactions

Request Parameters

Name

Required

Data Type

Description

merchantId

Mandatory

String

The customer code, a unique customer ID allocated to a customer when the service is set up.

storeId

Mandatory

String

The site identifier, a unique site ID allocated to a customer when the service is set up

userId

Mandatory

String

A username allocated to a service user when the service is set up.

Type

Mandatory

String

A combination of how the card was captured and transaction type of the transaction. Accepted values are “ecom.capture”, “ecom.refund” and “ecom.reversalPreauthorization”

Amount

Mandatory

String

The monetary value of the transaction in minor units.
See Note1.

currencyCode

Mandatory

String

The currency of the transaction. A three character code in accordance with ISO 4217.

clientSystemTransactionId

Mandatory

String

The merchant’s own unique reference for the transaction

clientSystemInvoiceId

Mandatory

String

This is the clientSystemTransactionId from the original transaction.

providerDiscretionaryData

Optional

String

The merchant’s external facing order number with the consumer, which if supported, will be passed to the Provider as an additional descriptor.

apmDetails

apmProvider

Mandatory

String

The alternative payment method provider name. There is value “PayPalV2”

Note1: The decimal separator/radix character used is the Period ('.') used to indicate decimal places. Other characters such as Comma (',') will not be recognised and may result in an unintended amount being processed.

Example:

{
  "merchantId": "PSH",
  "storeId": "PSH500000001",
  "userId": "PSH001",
  "type": "ecom.capture",
  "amount": 110.61,
  "currencyCode": "EUR",
  "clientSystemTransactionId": "290224_01C",
  "clientSystemInvoiceId": "290224_01",
  "providerDiscretionaryData": null,
  "apmdetails": {
    "apmProviderName": "PayPalV2"
  },
  "shoppingCartDetails": {
    "ItemDetails": [
      {
        "ProductId": "ABC123",
        "ProductName": "Blue Jeans",
        "ProductDescription": "Stone Washed",
        "ProductType": null,
        "ProductQuantity": 1,
        "UnitAmount": 50.0,
        "TaxRate": 5,
        "UnitTaxAmount": 69.0,
        "TotalAmount": 20.0,
        "TotalTaxAmount": 5.0,
        "DiscountName": "Jeans Promotion",
        "DiscountAmount": 10.0,
        "DiscountTaxAmount": 35.0
      }
    ],
    "DiscountDetails": null,
    "ShippingDetails": {
      "ShippingName": "Next Day",
      "ShippingAmount": 5.0,
      "ShippingTaxAmount": 1.0,
      "ShippingTaxRate": 20
    },
    "TotalTaxAmount": 5.0
  }

3.4 Capture/Refund/ReversePreAuth response

Resource: POST /api/v5/checkout

Response Parameters

NameData TypeDescription
IdStringPayment identifier
StateStringTransaction state
providerStateCodeStringThe state of service provider
currencyCodeStringThe currency of transaction.
clientSystemTransactionIdStringThe merchant’s own unique reference for the transaction.
apmDetails
apmProviderNameStringThe name of service provider.
apmPaymentMethodStringThe capture method of service provider.

Example:

{
    "id": "d3ea2230-7127-48fb-b2ef-46fabd951fca",
    "state": "Approved",
    "providerStateCode": "CapturedByProvider",
    "currencyCode": "EUR",
    "clientSystemTransactionId": "290224_01C",
    "apmdetails": {
        "apmPaymentMethod": "PayPal Capture",
        "apmProviderName": "PayPal"
    }
}

3.5 Get status and details of transaction request and response

After posting a transaction, the merchant can retrieve the status and details of a transaction.

Will return shipping information in the response for PayPal PreAuth transaction.

Resource: GET api/v5/apmTransactions?merchantId={merchantId}&storeId={storeId}&clientSystemTransactionId={clientSystemTransactionId}

Request Parameters

NameRequiredData TypeDescription
merchantIdMandatoryStringThe customer code, a unique customer ID allocated to a customer when the service is set up.
storeIdMandatoryStringThe site identifier, a unique site ID allocated to a customer when the service is set up
clientSystemTransactionIdMandatoryStringThe merchant’s own unique reference for the transaction

Response Parameters

NameData TypeDescription
IdStringPayment identifier
StateStringStatus of transaction
currencyCodeStringThe currency of transaction
transactionAmountDecimalThis is the monetary value of the transaction in minor units.
clientSystemTransactionIdStringThe merchant’s own unique reference for the transaction.
TypeStringThe capture method of transaction
transactionDateTimeStringThe time of transaction
apmDetails
apmNameStringThe name of service provider.
billingAddress
houseNumberStringThe house number of the cardholder’s billing address.
StreetStringThe street name of the card holder’s billing address
CityStringThe city of the card holder’s billing address
zipPostalCodeStringThe zip or postal code of the card holder’s billing address
StateStringThe region or state in ISO 3166-2 format.
countryCodeStringThe ISO 3166 alpha-3 country code of the card holder’s billing address
shippingAddress
firstNameStringThe shipping address first name
lastNameStringThe shipping address last name
telephoneNumberStringThe phone number of where the item is being shipped.
EmailStringThe email address of the person that the delivery is being shipped to
houseNumberStringThe house number of the shipping address
StreetStringThe street name of the shipping address
CityStringThe city of the shipping address
zipPostalCodeStringThe zip or postal code of the shipping address.
StateStringThe region or state in ISO 3166-2 format
countryCodeStringThe ISO 3166 alpha-3 country code of the cardholder’s shipping address

Example: {{V5_base_url}}/api/v5/apmtransactions?merchantId=PSH&storeId=PSH500000001&clientSystemTransactionId=290224_01

[
    {
        "id": "516c3c42-bed5-4bea-9d52-82e653bbd803",
        "state": "Approved",
        "currencyCode": "EUR",
        "transactionAmount": 110.61,
        "clientSystemTransactionId": "290224_01",
        "type": "ecom.preAuthorisation",
        "transactionDateTime": "2024-02-29T11:02:23.1030000",
        "apmdetails": {
            "apmName": "PayPal Redirect PreAuthorisation",
            "apmPayerAccountNumber": "XZCCGLLWG8SDW",
            "apmPayerEmailAddress": "[email protected]",
            "apmProviderTransactionId": "252015041Y455624N",
            "apmPayerShippingName": "John Wilson",
            "apmPayerShippingStreet1": "96 Too High Street ",
            "apmPayerShippingCityName": "Tipton",
            "apmPayerShippingPostalCode": "EN11 8BC",
            "apmPayerShippingCountry": "GB",
            "apmPayerShippingPhone": "447975777666",
            "apmPayerID": "XZCCGLLWG8SDW",
            "apmPayerFirstname": "John",
            "apmPayerLastname": "Wilson",
            "apmPayerBillingName": "John Wilson",
            "apmPayerBillingStreet1": "96 Too High Street",
            "apmPayerBillingCityName": "Tipton",
            "apmPayerBillingCountry": "VN",
            "apmPayerBillingPhone": "84385874345",
            "apmPayerBillingPostalCode": "700000",
            "apmPayerCountryCode": "VN",
            "apmPayerStateOrProvince": "HỒ CHÍ MINH"
        }
    },
    {
        "id": "02946835-5224-4148-94e4-18d9ba7ba723",
        "state": "Errored",
        "currencyCode": "EUR",
        "transactionAmount": 110.61,
        "clientSystemTransactionId": "290224_01",
        "type": "ecom.capture",
        "transactionDateTime": "2024-02-29T11:03:02.2330000",
        "apmdetails": {
            "apmName": "PayPal Capture",
            "apmPayerAccountNumber": null,
            "apmPayerEmailAddress": null,
            "apmProviderTransactionId": null
        }
    }
]