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
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
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
unitTaxAmount	Conditional	String	The monetary value of the tax amount in minor units for the item line.
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.
totalTaxAmount	Conditional Required if taxRate > 0	String	The monetary value of the total tax amount in minor units for the item line.
discountAmount	Optional	String	The non-negative monetary value of the discount amount in minor units for the item line
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
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.
shippingTaxAmount	Conditional	String	The monetary value of the total shipping amount in minor units for the item line.
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.
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.

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

Name	Data Type	Description
redirectUrl	String	The 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.
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”

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

Name	Data Type	Description
Id	String	Payment identifier
State	String	Transaction state
providerStateCode	String	The state of service provider
currencyCode	String	The currency of transaction.
clientSystemTransactionId	String	The merchant’s own unique reference for the transaction.
apmDetails
apmProviderName	String	The name of service provider.
apmPaymentMethod	String	The 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

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
clientSystemTransactionId	Mandatory	String	The merchant’s own unique reference for the transaction

Response Parameters

Name	Data Type	Description
Id	String	Payment identifier
State	String	Status of transaction
currencyCode	String	The currency of transaction
transactionAmount	Decimal	The monetary value of transaction in minor units
clientSystemTransactionId	String	The merchant’s own unique reference for the transaction.
Type	String	The capture method of transaction
transactionDateTime	String	The time of transaction
apmDetails
apmName	String	The name of service provider.
billingAddress
houseNumber	String	The house number of the cardholder’s billing address.
Street	String	The street name of the card holder’s billing address
City	String	The city of the card holder’s billing address
zipPostalCode	String	The zip or postal code of the card holder’s billing address
State	String	The region or state in ISO 3166-2 format.
countryCode	String	The ISO 3166 alpha-3 country code of the card holder’s billing address
shippingAddress
firstName	String	The shipping address first name
lastName	String	The shipping address last name
telephoneNumber	String	The phone number of where the item is being shipped.
Email	String	The email address of the person that the delivery is being shipped to
houseNumber	String	The house number of the shipping address
Street	String	The street name of the shipping address
City	String	The city of the shipping address
zipPostalCode	String	The zip or postal code of the shipping address.
State	String	The region or state in ISO 3166-2 format
countryCode	String	The 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
        }
    }
]