Integration checklist

DocsCurrentChecklistLast updated: July 6th 2023, @ 11:39:49 am

We've made changes to this page and its layout to improve the developer experience

Let us know what you think of the updated documentation by selecting the feedback tab below.

Complete this checklist to ensure you're prepared for the live integration. Have the completed checklist ready before contacting a PayPal representative to go live.

This checklist includes:

  1. API calls
  2. Transaction and debug ID
  3. Sandbox account
  4. Video recordings
  5. Integration questionnaire
  6. Contact your PayPal representative

Important: Make a separate .txt file for API calls. The remaining checklist items can be in another .txt file. You'll need to send these files to your PayPal representative when all checklist items are done.

1st .txt file

Make a .txt file named "API_Calls" and copy-and-paste the following text. Write an entry for each API call in your solution that contains:

API calls

Title of Call:
(The title with the name of the API call such as "Create Partner Referral Link" or "Get MerchantID from TrackingID".)

HTTP Request:
(The HTTP request that includes headers and parameters in this call.)

HTTP Response:
(The HTTP response received from the call.)

2nd .txt file

Make a .txt file named "Integration_Checklist" and copy-and-paste the following text. Record your responses.

Transaction IDs and debug IDs

Record the test transaction IDs and debug IDs from the PayPal sandbox for:

  • 2 completed sales. Include all the API calls, order IDs, and debug IDs for your flow.
  • order IDs:
    debug IDs

    order IDs:
    debug IDs

  • 1 refund. This is mandatory if you're using delayed disbursement.
  • order IDs:
    debug IDs

  • 1 completed sale using a billing agreement ID. This is mandatory if you are using billing agreements.
  • order IDs:
    debug IDs

Sandbox account

Record the following sandbox information:

email address (sandbox REST App):
client ID (sandbox REST App):
Webhooks (subscribed to):

Video recordings

  • The steps a new seller would take to link their PayPal account to your platform and begin accepting payments.
  • Links:

  • The process a buyer would then take to purchase items from that seller (multiple items if applicable).
  • Links:

  • An example of each checkout method that your integration uses such as the PayPal button, guest checkout, unbranded checkout, or billing agreements if applicable.
  • Links:

  • A declined payment scenario. See Simulate negative responses with request headers.
  • Links:

  • Any tools or dashboards available to your sellers such as refunds, transaction dashboards, and unlinking accounts.
  • Links:

Integration Questionnaire

Answer the questions below and include screenshots when available.

Seller onboarding

  1. Are you using the Partner Referral API to onboard sellers?
  2. Answer:

  3. If you are not using the Partner Referral API, then what method are you using to connect the sellers to your platform?
  4. Answer:

  5. What are you submitting as the product_name when generating a new onboarding referral link?
  6. Answer:

  7. Are you passing the following features when generating a new onboarding referral link?
    • REFUND
    • PARTNER_FEE. This is required if you're using partner fees.
    • DELAY_FUNDS_DISBURSEMENT. This is required if you're using delayed disbursement.
    • READ_SELLER_DISPUTE. This is required if you're using the Dispute API.
    • UPDATE_SELLER_DISPUTE. This is required if you're using the Dispute API.
    • ACCESS_MERCHANT_INFORMATION. This is required to access the seller's email, currency code, and country code.
  8. Before enabling payments for a seller, are you performing a GET call to /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id} to ensure that the:
    • payments_receivable flag is true.
    • primary_email_confirmed flag is true.
    • oauth_third_party is not blank and has the set of third-party permissions that correspond with the required features above.
  9. If product_name above was set to PPCP, are you confirming vetting_status is SUBSCRIBED, and enabling advanced card processing based on CUSTOM_CARD_PROCESSING capabilities? In the sandbox environment, vetting_status is subscribed by default, but you should confirm this flag.
  10. Answer:

Buyer checkout

  1. Are you using PayPal's JavaScript SDK library for the following:

    • Render a PayPal-branded button
    • Handle the buyer checkout experience
    • For payment buttons on the seller's product pages, set the layout to horizontal, size to responsive, and label to buynow in the button's style attributes
    • For payment buttons on seller's cart or checkout page, set the layout to vertical and size to responsive in the button's style attributes
  2. Are you waiting to call the Create Order API until after the buyer has clicked on the PayPal checkout button?


  3. Are you passing individual line-item details as part of the Create Order call?


  4. Are you able to process a successful payment?


  5. If you are using delayed disbursement, are you able to issue a refund?


  6. Are you passing your BN code, which is the PayPal-Partner-Attribution-ID, to PayPal with each payment?


  7. Have you capitalized the two letter P's when PayPal is mentioned?


  8. Does your checkout button or payment selection take buyers directly to PayPal without any steps in between?


  9. If an order does not require any shipping information, such as digital products or services:

    • Use NO_SHIPPING during the Create Order call to hide the shipping information on the PayPal review page. This is required when you charge the customer immediately when returning to your platform.
    • Set application_context > user_action> to PAY_NOW and commit to true. This is required when the final amount of an order will change after shipping information is selected at PayPal.
    • Set application_context > user_action> to CONTINUE. In the same scenario, display PayPal as the payment method. Display the shipping address information on post-PayPal pages.
  10. When a capture attempt returns an INSTRUMENT_DECLINED error, are you restarting the payment so the buyer can select another funding source?


  11. Does your checkout work across major browsers on desktop and mobile?


  12. Are PayPal checkout buttons included with equal prominence as other options on any platform page that starts checkout?


  13. If you are subscribed to webhooks, are you following any changes to the transaction status?


  14. If you are using standard checkout with the PayPal button, does your checkout flow allow buyers to checkout in only two steps?



If you are using the partner features, are you able to connect to your SFTP folder and receive your partner reports?



Are you storing the Paypal-Debug-Id header returned in the API Response?


Additional comments

List any comments or observations that you have in this walkthrough that was not included in the questions above.


Contact your PayPal representative

You must be an approved partner to go live. You'll be assigned a PayPal representative after you are approved. Contact your PayPal representative to go through the checklist and go live.