marketplaces

Marketplaces Progressive Onboarding

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager.

Overview

With Progressive onboarding, you ask your sellers to connect with PayPal after buyers make PayPal payments through your marketplace.

Progressive onboarding allows you to onboard both business sellers with PayPal business accounts and casual sellers with their personal PayPal accounts.

How it works

The process begins with a customer making a PayPal purchase from a seller. You send the transaction to PayPal and PayPal does the rest. When a transaction comes in from a buyer who paid with PayPal, sellers without PayPal accounts are prompted through account set up to receive their funds.

Important: You must notify your existing sellers 30 days prior to activating PayPal that you are enabling PayPal as a payment option and allow them to opt out. For those sellers who opt out, you must provide them the ability to cancel pending PayPal transactions.

Integration steps

As PayPal transactions come in from your seller's customers, pass the seller's email address in an orders call and let your seller know to complete the account set up process per the emailed instructions.

  1. Make an Orders API call with the seller's email address.
  2. Your seller completes setup.

Make an Orders API call

When a transaction comes into your marketplace from a buyer who paid with PayPal, send the seller's email address in the body of an Orders API call with the transaction information to trigger account onboarding.

Request

curl -v -X POST https://api.sandbox.paypal.com/v1/checkout/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Partner-Attribution-Id: EXAMPLE_MP" \
  -d '{
  "purchase_units": [
  {
    "reference_id": "5decd4b7-3779-4b2e-9d86-6d79e49b1dc8",
    "description": "Default Level 1 Order",
    "items": [
    {
      "name": "Salad",
      "sku": "SKU-d3538cf2-e46b-4257-bcc6-6ad4b80957ee",
      "price": "27.80",
      "currency": "USD",
      "quantity": 2,
      "category": "PHYSICAL"
    },
    {
      "name": "Car",
      "sku": "SKU-7fb2e78f-f6ed-40b2-b928-915f4b0c2f42",
      "price": "6.66",
      "currency": "USD",
      "quantity": 2,
      "category": "PHYSICAL"
    }],
    "payee":
    {
      "email": "seller@example.com",
      "payee_display_metadata":
      {
        "brand_name": "Test Store",
        "phone":
        {
          "country_code": "1",
          "number": "6025550128"
        }
      }
    },
    "shipping_address":
    {
      "recipient_name": "Rylee Lueilwitz",
      "line1": "965 Hilma Rapid",
      "line2": "Apartment Number 91392",
      "city": "Gilbert",
      "country_code": "US",
      "postal_code": "85298",
      "state": "AZ",
      "phone": "0018882211161"
    },
    "shipping_method": "United Postal Service",
    "payment_linked_group": 1,
    "custom": "MyCustomVar",
    "invoice_number": "INV-d5719503-5efc-4426-a7b3-09a345d10da2",
    "payment_descriptor": "Payment Nate Shop",
    "amount":
    {
      "currency": "USD",
      "details":
      {
        "subtotal": "68.92",
        "shipping": "16.59",
        "tax": "7.18"
      },
      "total": "92.69"
    },
    "partner_fee_details":
    {
      "amount":
      {
        "currency": "USD",
        "value": "6.89"
      },
      "receiver":
      {
        "email": "facilitator@example.com",
        "merchant_id": "6HHS8L6HG2APC",
        "payee_display_metadata":
        {
          "email": "facilitator@example.com",
          "display_phone":
          {
            "country_code": "001",
            "number": "8882211161"
          },
          "brand_name": "APEX"
        }
      }
    }
  }],
  "application_context":
  {
    "brand_name": "Test Store",
    "locale": "en-US",
    "landing_page": "Login",
    "shipping_preferences": "NO_SHIPPING",
    "user_action": "continue"
  },
  "metadata":
  {
    "postback_data": [
    {
      "name": "metaOneName",
      "value": "metaOneValue"
    }],
    "supplementary_data": [
    {
      "name": "supplementaryOneName",
      "value": "supplementaryOneValue"
    }]
  },
  "redirect_urls":
  {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  }
}'

Response

A successful response returns an HTTP status code of 200 Created and a response body that includes the PayPal-generated order ID an array of purchase unit objects, payment details, customer information, metadata, and order status.

{
  "id": "4L821617AA117154M",
  "gross_total_amount": {
    "value": "92.69",
    "currency": "USD"
  },
  "application_context": {
    "brand_name": "Test Store",
    "locale": "en-US",
    "landing_page": "Login",
    "user_action": "continue"
  },
  "purchase_units": [
    {
      "reference_id": "5decd4b7-3779-4b2e-9d86-6d79e49b1dc8",
      "description": "Default Level 1 Order",
      "amount": {
        "currency": "USD",
        "details": {
          "subtotal": "68.92",
          "shipping": "16.59",
          "tax": "7.18"
        },
        "total": "92.69"
      },
      "payee": {
        "email": "seller@example.com",
        "payee_display_metadata": {
          "brand_name": "Test Store"
        }
      },
      "items": [
        {
          "name": "Salad",
          "sku": "SKU-d3538cf2-e46b-4257-bcc6-6ad4b80957ee",
          "price": "27.80",
          "currency": "USD",
          "quantity": 2,
          "category": "PHYSICAL"
        },
        {
          "name": "Car",
          "sku": "SKU-7fb2e78f-f6ed-40b2-b928-915f4b0c2f42",
          "price": "6.66",
          "currency": "USD",
          "quantity": 2,
          "category": "PHYSICAL"
        }
      ],
      "shipping_address": {
        "recipient_name": "Rylee Lueilwitz",
        "line1": "965 Hilma Rapid",
        "line2": "Apartment Number 91392",
        "city": "Gilbert",
        "country_code": "US",
        "postal_code": "85298",
        "state": "AZ",
        "phone": "0018882211161"
      },
      "shipping_method": "United Postal Service",
      "partner_fee_details": {
        "receiver": {
          "email": "facilitator@example.com",
          "merchant_id": "6HHS8L6HG2APC",
          "payee_display_metadata": {
            "brand_name": "APEX",
            "email": "facilitator@example.com",
            "display_phone": {
              "country_code": "001",
              "number": "8882211161"
            }
          }
        },
        "amount": {
          "value": "6.89",
          "currency": "USD"
        }
      },
      "payment_linked_group": 1,
      "custom": "MyCustomVar",
      "invoice_number": "INV-d5719503-5efc-4426-a7b3-09a345d10da2",
      "payment_descriptor": "Payment Nate Shop",
      "status": "NOT_PROCESSED"
    }
  ],
  "metadata": {
    "supplementary_data": [
      {
        "name": "supplementaryOneName",
        "value": "supplementaryOneValue"
      }
    ],
    "postback_data": [
      {
        "name": "metaOneName",
        "value": "metaOneValue"
      }
    ]
  },
  "redirect_urls": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  },
  "create_time": "2018-05-21T18:23:04Z",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/checkout/orders/4L821617AA117154M",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://www.sandbox.paypal.com/webapps/hermes?token=4L821617AA117154M",
      "rel": "approval_url",
      "method": "REDIRECT"
    }
  ],
  "status": "CREATED"
}

Complete setup

After a seller receives a pending transaction, they are notified by PayPal to complete onboarding within 30 days.

The seller must complete onboarding with the same email address within 30 days of receiving the payment or the payment will be reversed. If the seller wishes to change the email address, they still need to complete onboarding using the email address where payments were received. They can create a new account or use a different email for future payments.

PayPal sends several reminders to sellers to complete setup. Existing PayPal account holders who have not completed linking their PayPal account with you (by granting third party permissions) are also reminded once they login to claim the funds by completing setup.

Note: Several countries might have additional regulations related to receiving payments. Tell the seller to check their accounts after logging in for any pending tasks.

Next

Feedback

Have feedback?

Let us know.