Merchant onboarding

Onboard each merchant with PayPal before you make PayPal Complete Payments available to them. Start onboarding by activating the PayPal PPCP payment provider method using Activate Payment Provider Method.

Activating payment method

Use provider: paypal and method: ppcp in the activate merchant payment method request.

Parameters

Provider method parameters

Onboarding flow

• Activate the paypal.ppcp payment provider method to start onboarding. The provider method response includes an action_url.
• Redirect the merchant to the action_url.
• The merchant steps through the PayPal onboarding process.
• Include status_callback_url in the activation request to receive the onboarding status callback.
• After the merchant completes onboarding, PayPal redirects the merchant to the redirect_url. Ping Payments sends a status callback to the status_callback_url.

  Callback example

  JSON

  {
    "id": "<Id returned when initiating the onboarding flow>",
  	"status": "COMPLETED",
  	"details": null
  }

• The merchant can now accept PayPal PPCP payments.

📘

If the merchant organization already has completed onboarding with the provided email, Ping Payments activates the payment method directly for the merchant. In this case, the response status is COMPLETED.

Testing onboarding in sandbox

Create a PayPal sandbox business account to test the onboarding flow. Log in to The PayPal Developer Portal with an existing account. Go to Testing Tools > Sandbox Accounts, select Create account, and choose Business as the account type. After PayPal creates the account, select the account email to view the account details. Use the sandbox account email and password when onboarding the merchant.

Designated Merchant

Every PayPal PPCP payment requires a designated_merchant_id in the provider_method_parameters. This is the Ping Payments Merchant ID (UUID) of the merchant whose PayPal account processes the payment.

Key points:

• The designated merchant must have a COMPLETED PayPal onboarding.
• The designated merchant must appear in at least one of the payment's order_items (i.e. the merchant_id of at least one order item must match the designated_merchant_id).
• For payments involving multiple merchants, designate one merchant by setting the designated_merchant_id to one of the merchant's merchant_id. The payment session uses that merchant's PayPal account.

Initiating a Payment

Use provider: paypal and method: ppcp in the initiate payment request.

Required parameters

Shipping

shipping is required but if there are no physical products in the order then set the preference field to NO_SHIPPING and none of the shipping information is needed.

Address

Phone number

Supported currencies

NOK, SEK, DKK, GBP, EUR

Payment Flow

1. Initiate a payment — the response contains a url.
2. Redirect the customer to the url to complete payment in PayPal's checkout.

   🚧

   NOTE: It is recommended to always redirect the customer to the PayPal checkout and not try rendering it in an iframe as this can cause unpredictable behavior

3. After the customer completes the payment, PayPal redirects them to the redirect_url provided in the request.
4. Ping Payments delivers the payment status through the standard Ping Payments callback.

Example Request

{
  "currency": "SEK",
  "method": "ppcp",
  "order_items": [
    {
      "amount": 10000,
      "merchant_id": "{{merchantId}}",
      "name": "Product A",
      "vat_rate": 25.0
    }
  ],
  "provider": "paypal",
  "total_amount": 10000,
  "provider_method_parameters": {
    "designated_merchant_id": "{{merchantId}}",
		"locale": "sv-SE",
		"redirect_url": "https://example.com",
		"description": "description",
		"shipping": {
			"preference": "NO_SHIPPING"
		},
		"item_category": "DIGITAL_GOODS"
  }
}

Example Response

{
  "id": "15c44587-7ebb-43a3-b437-8d00e5f8df7a",
  "provider_method_response": {
    "url": "https://www.sandbox.paypal.com/checkoutnow?token=abc123"
  }
}

Testing payments in sandbox

To test PayPal PPCP payments a sandbox personal account is needed. Create the account by, first, logging in to your PayPal developer account, then, going to Testing Tools > Sandbox Accounts, select Create account, make sure to choose Personal as the account type. After the PayPal account is created, select the account email to view the account details. Use the sandbox account email and password when making the payment.

Refunds

PayPal PPCP payments support refunds through the standard Ping Payments refund flow. PayPal supports partial refunds. Check the create refund guide for more information on how to perform a refund.