PayPal Admin API Guide
Implement PayPal on custom checkouts via the API
PayPal is a fully integrated payment app that is supported both in the storefront checkout, and via the Admin API. PayPal transactions send the customer through a PayPal redirect flow, with the resulting order information provided back to your application. Below are the steps needed to get PayPal set up and working on the Admin API.
Important - PayPal custom checkouts require the use of the PayPal NVP/SOAP (Legacy) APIs. Please ensure that your valid NVP/SOAP credentials are configured in the Paypal Extension prior to attempting custom checkouts with PayPal over the Admin API.
For custom PayPal checkouts, there are two checkout flows available -- the standard method where a user enters their shipping address, chooses products, and then checks out via PayPal; and the "One-Click" method, where the user is not required to enter shipping information before being redirected to PayPal checkout.
When creating a new order using PayPal using the
orders_create API method, you must specify the payment_method=paypal as well as provide a payment_return_url. The payment_return_url is your endpoint that will receive a POST request containing the final order data (in Step 3).{
"payment_method": "paypal",
"payment_details": {
"payment_return_url": "<YOUR APPLICATION ENDPOINT>"
}
The response from Step 1 will provide a
payment_complete_url. Your application should redirect the customer to this URL for completing the payment on PayPal.{
"reference_transaction_id": "<Unique Transactions ID>",
"payment_complete_url": "https://www.paypal.com/checkoutnow?token=PAYPALTOKEN"
}
After the customer has completed their purchase on PayPal, they will be redirected to your application with a POST request containing data in the
response key of all the order information as a string. See examples below.
Example parsing the data""""
Order json data is stored in a variable called response.
If the order data is an empty dictionary {}, it means
payment collection was unsuccessful and order was not created.
"""
import json
def my_view(request):
data = json.loads(request.POST.get("response"))
...
return HttpResponse(status=201)
Example Order data
{
"number": "109405",
"status": "Confirmed",
"lines": [
{
"product": {
"id": 22,
"categories": [
],
"product_class": null,
"images": [
{
"id": 27,
"original": "https://mystore.net/media/images/products/2020/02/product_image.png",
"caption": "",
"display_order": 0,
"date_created": "2019-05-14T12:56:24.991823+07:00"
}
],
"title": "Skin Care Cream",
"upc": ""
},
"stockrecord": {
"id": 23,
"partner_sku": "TESTSKU23",
"price_currency": "USD",
"points_price": null,
"price_excl_tax": "56.00",
"price_retail": "89.00",
"cost_price": "10.00",
"num_in_stock": 1000,
"low_stock_threshold": 100
},
"quantity": 1,
"price_currency": "USD",
"price_excl_tax": "19.99",
"price_incl_tax": "19.99",
"price_incl_tax_excl_discounts": "19.99",
"price_excl_tax_excl_discounts": "19.99"
}
],
"shipping_incl_tax": "5.00",
"shipping_method": "Default shipping",
"shipping_code": "default-shipping",
"total_incl_tax": "69.99",
"currency": "USD",
"total_excl_tax": "69.99",
"shipping_excl_tax": "5.00",
"user": {
"id": 577,
"email": "[email protected]",
"first_name": "John",
"last_name": "Smith",
"phone_number": null
},
"shipping_address": {
"id": 9658,
"country": "US",
"title": "",
"first_name": "John",
"last_name": "Smith",
"line1": "2200 Testing Lane",
"line2": "PO Box 404",
"line3": "",
"line4": "Hoptown",
"postcode": "33635",
"phone_number": "+1937567889",
"notes": "",
"state": "FL"
},
"billing_address": null,
"date_placed": "2020-10-01T16:00:25.238490+07:00",
"payment_sources": [
{
"source_type": {
"name": "Paypal",
"code": "paypal"
}
}
],
"offer_discounts": [
],
"voucher_discounts": [
],
"attribution": null,
"tags": [
],
"subscriptions": [
],
"metadata": {
},
"transactions": [
{
"partner_transaction_id": "<Unique Transaction ID>",
"txn_type": "Debit",
"currency": "USD",
"amount": "69.99"
}
]
}
Important - To use the
add-line-items API to add additional items to an order after the initial purchase (one-click upsells), you must have Reference Transactions enabled in your PayPal account and PayPal extension settingsReference Transactions must be enabled by a request to your PayPal account manager. They cannot be enabled without PayPal's direct approval.
The One Click PayPal flow sends customers from your custom checkout directly to PayPal, without having to collect shipping address or other customer details first.
When creating a One Click PayPal checkout over the Admin API with the
orders_create method, you do not need to specify the user (customer), the billing or shipping addresses, the shipping method, or other details -- these will be posted back from PayPal upon the completion of the checkout.You are required to specify the product, price, and set the
payment_method=paypal as well as provide a payment_return_url. The payment_return_url is your endpoint that will receive a POST request containing the final order data.Below is an example of the minimum required data to initiate a PayPal One Click checkout.
{
"lines": [
{
"sku": "TESTSKU23",
"quantity": 1,
"currency": "USD",
"price": "22.55"
}
],
"payment_method": "paypal",
"payment_details": {
"payment_return_url": "<YOUR APPLICATION ENDPOINT>"
}
}
The response from Step 1 will provide a
payment_complete_url. Your application should redirect the customer to this URL for completing their payment on PayPal.{
"reference_transaction_id": "<Unique Transactions ID>",
"payment_complete_url": "https://www.paypal.com/checkoutnow?token=PAYPALTOKEN"
}
Once redirected to PayPal, the Customer will be prompted to select from their existing billing methods, specify shipping address, and preferred shipping method according to your store's available options. The selected values will be returned in Step 3 order data upon completion of the purchase.
Sales Tax Calculation
The PayPal One Click checkout does not require the customer to specify a shipping address before being redirected. Therefore, when they select their preferred shipping address from their PayPal account (usually used for sales tax calculation), PayPal will automatically callback to 29 Next to calculate applicable taxes in real-time.
After the customer has completed their purchase on PayPal, they will be redirected to your application with a POST request containing data in the
response key of all the order information as a string. See examples below.
Example parsing the data""""
Order json data is stored in a variable called response.
If the order data is an empty dictionary {}, it means
payment collection was unsuccessful and order was not created.
"""
import json
def my_view(request):
data = json.loads(request.POST.get("response"))
...
return HttpResponse(status=201)
Important - To use the
add-line-items API to add additional items to an order after the initial purchase (one-click upsells), you must have Reference Transactions enabled in your PayPal account and PayPal extension settings.Reference Transactions must be enabled by a request to your PayPal account manager. They cannot be enabled without PayPal's direct approval.
Last modified 1yr ago