Confirm that PayPal is supported by the payment integration included in the deployed release. Use sandbox credentials for development and staging.
Configuration
Keep client secrets and webhook identifiers in protected server-side configuration. Use the correct sandbox/live environment and ensure the registered return, cancel, and webhook URLs match the deployment.
Lifecycle
The backend should create the provider order using server-calculated totals, allow the customer to approve it through the provider flow, and capture/verify payment server-side. Persist provider IDs and final capture details according to the adapter’s data model.
Security and reconciliation
Verify webhook authenticity, correlate every event with the expected local order, validate amount and currency, and process duplicate notifications idempotently. Do not mark an order paid based only on a client redirect or query parameter.
Verify
Read the actual provider service, route registration, environment loader, and tests in the target release before publishing concrete endpoints or variable names.
Was this page helpful?
{"docsConfig":{"theme":"aspen","$schema":"https://mintlify.com/docs.json","name":"SpurtCommerce","colors":{"primary":"#166E3F","light":"#26BD6C","dark":"#166E3F"},"logo":{"light":"https://mintcdn.com/community-b29da77f/OyooSJITv9dVZ5aV/images/light.svg?fit=max\u0026auto=format\u0026n=OyooSJITv9dVZ5aV\u0026q=85\u0026s=5133f6070951b37b293d703a3fadc605","dark":"https://mintcdn.com/community-b29da77f/OyooSJITv9dVZ5aV/images/image.avif?fit=max\u0026auto=format\u0026n=OyooSJITv9dVZ5aV\u0026q=85\u0026s=ff715e941aef8f28b628c1e916c71221","href":"https://www.spurtcommerce.com/"},"favicon":{"light":"https://mintcdn.com/community-b29da77f/dWiXU5OySaP7apAG/images/favicon.png?fit=max\u0026auto=format\u0026n=dWiXU5OySaP7apAG\u0026q=85\u0026s=0eacd7297666eb7740fad94a28de43c8","dark":"https://mintcdn.com/community-b29da77f/dWiXU5OySaP7apAG/images/favicon.png?fit=max\u0026auto=format\u0026n=dWiXU5OySaP7apAG\u0026q=85\u0026s=0eacd7297666eb7740fad94a28de43c8"},"api":{"openapi":["VendorAPI.json","StoreAPI.json"]},"appearance":{"default":"dark"},"background":{"decoration":"grid"},"footer":{"socials":{"github":"https://github.com/spurtcommerce/spurtcommerce","discord":"https://discord.com/invite/hyW4MXXn8n"}},"search":{"prompt":"Search SpurtCommerce documentation..."},"fonts":{"heading":{"family":"Roboto"},"body":{"family":"Roboto"}},"icons":{"library":"fontawesome"},"contextual":{"options":["claude","chatgpt","mcp","add-mcp","cursor","vscode"],"display":"header"},"interaction":{"drilldown":false},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"community-b29da77f","hasAudioNarration":false,"actualSubdomain":"community-b29da77f","customDomains":["docs.spurtcommerce.com"],"gitSource":{"type":"artifacts","owner":"prod","repo":"6ae980de593efc77a2c0fccd","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":"","_id":"6ae981ef49ed4faacd7da35c"},"feedback":{"thumbs":true,"agentFeedback":false},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6af8461fd5445d1ec6148f84","clientVersion":"0.0.4143","searchFilterCounts":[{"language":"default","tag":"API Reference","count":268},{"language":"default","tag":"Vendor API","count":207},{"language":"default","tag":"Store API","count":61},{"language":"default","tag":"Documentation","count":35},{"language":"default","tag":"Products","count":33},{"language":"default","tag":"Core concepts","count":18},{"language":"default","tag":"Product imports and exports","count":14},{"language":"default","tag":"Localization and master data","count":12},{"language":"default","tag":"Developers","count":11},{"language":"default","tag":"Categories","count":11}],"searchSettings":{"fullPageSearch":true,"maxResults":10}},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":true,"toggles":[],"googleFontsInlined":true},"customCss":[],"page":{"pagePath":"documentation/core-concepts/payments/pay-pal","slug":"/documentation/core-concepts/payments/pay-pal","pageMetadata":{"title":"PayPal","icon":{"name":"paypal","style":"regular","library":"fontawesome"},"description":null,"href":"/documentation/core-concepts/payments/pay-pal"},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={p:`p`,..._provideComponents(),...props.components},{Heading}=_components;if(!Heading)_missingMdxReference(`Heading`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Confirm that PayPal is supported by the payment integration included in the deployed release. Use sandbox credentials for development and staging.`}),`\n`,_jsx(Heading,{level:`2`,id:`configuration`,children:`Configuration`}),`\n`,_jsx(_components.p,{children:`Keep client secrets and webhook identifiers in protected server-side configuration. Use the correct sandbox/live environment and ensure the registered return, cancel, and webhook URLs match the deployment.`}),`\n`,_jsx(Heading,{level:`2`,id:`lifecycle`,children:`Lifecycle`}),`\n`,_jsx(_components.p,{children:`The backend should create the provider order using server-calculated totals, allow the customer to approve it through the provider flow, and capture/verify payment server-side. Persist provider IDs and final capture details according to the adapter’s data model.`}),`\n`,_jsx(Heading,{level:`2`,id:`security-and-reconciliation`,children:`Security and reconciliation`}),`\n`,_jsx(_components.p,{children:`Verify webhook authenticity, correlate every event with the expected local order, validate amount and currency, and process duplicate notifications idempotently. Do not mark an order paid based only on a client redirect or query parameter.`}),`\n`,_jsx(Heading,{level:`2`,id:`verify`,children:`Verify`}),`\n`,_jsx(_components.p,{children:`Read the actual provider service, route registration, environment loader, and tests in the target release before publishing concrete endpoints or variable names.`})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"PayPal","icon":{"name":"paypal","style":"regular","library":"fontawesome"},"description":null,"href":"/documentation/core-concepts/payments/pay-pal"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Configuration","slug":"configuration","depth":2,"children":[]},{"title":"Lifecycle","slug":"lifecycle","depth":2,"children":[]},{"title":"Security and reconciliation","slug":"security-and-reconciliation","depth":2,"children":[]},{"title":"Verify","slug":"verify","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"community-b29da77f","siteName":"SpurtCommerce","title":"PayPal - SpurtCommerce","relatedPagesConfig":{"enabled":false,"limit":5,"mode":"automatic"},"navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-14T10:14:21.333Z","originalFileLocation":"documentation/core-concepts/payments/pay-pal.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"application-name\" content=\"SpurtCommerce\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/community-b29da77f/YeaVIy4GFP7zqw3S/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/community-b29da77f/YeaVIy4GFP7zqw3S/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/community-b29da77f/YeaVIy4GFP7zqw3S/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/community-b29da77f/YeaVIy4GFP7zqw3S/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/community-b29da77f/YeaVIy4GFP7zqw3S/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/community-b29da77f/YeaVIy4GFP7zqw3S/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/community-b29da77f/YeaVIy4GFP7zqw3S/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/community-b29da77f/YeaVIy4GFP7zqw3S/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/community-b29da77f/YeaVIy4GFP7zqw3S/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"PayPal - SpurtCommerce\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"SpurtCommerce\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.spurtcommerce.com/documentation/core-concepts/payments/pay-pal\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://community-b29da77f.mintlify.site/_mintlify/api/og/v2?division=Payments\u0026amp;title=PayPal\u0026amp;theme=f197bbaca4c627661f87bd63\u0026amp;signature=6cd66e7c83db7a750cfff589fd6de64562a48c11c4dcb392d049e8b606d1c982\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"PayPal - SpurtCommerce\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://community-b29da77f.mintlify.site/_mintlify/api/og/v2?division=Payments\u0026amp;title=PayPal\u0026amp;theme=f197bbaca4c627661f87bd63\u0026amp;signature=6cd66e7c83db7a750cfff589fd6de64562a48c11c4dcb392d049e8b606d1c982\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/community-b29da77f/YeaVIy4GFP7zqw3S/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"SpurtCommerce\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#166E3F\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.spurtcommerce.com/documentation/core-concepts/payments/pay-pal\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/documentation/core-concepts/payments/pay-pal.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.spurtcommerce.com/#organization\",\"name\":\"SpurtCommerce\",\"url\":\"https://docs.spurtcommerce.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/community-b29da77f/OyooSJITv9dVZ5aV/images/light.svg?fit=max\u0026auto=format\u0026n=OyooSJITv9dVZ5aV\u0026q=85\u0026s=5133f6070951b37b293d703a3fadc605\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.spurtcommerce.com#website\",\"name\":\"SpurtCommerce\",\"url\":\"https://docs.spurtcommerce.com\",\"publisher\":{\"@id\":\"https://docs.spurtcommerce.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.spurtcommerce.com/documentation/core-concepts/payments/pay-pal#webpage\",\"url\":\"https://docs.spurtcommerce.com/documentation/core-concepts/payments/pay-pal\",\"name\":\"PayPal\",\"dateModified\":\"2026-11-14T10:14:21.333Z\",\"isPartOf\":{\"@id\":\"https://docs.spurtcommerce.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.spurtcommerce.com/documentation/core-concepts/payments/pay-pal#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.spurtcommerce.com/documentation/core-concepts/payments/pay-pal#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"SpurtCommerce\",\"item\":\"https://docs.spurtcommerce.com\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"PayPal\",\"item\":\"https://docs.spurtcommerce.com/documentation/core-concepts/payments/pay-pal\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.spurtcommerce.com/documentation/core-concepts/payments/pay-pal#article\",\"headline\":\"PayPal\",\"name\":\"PayPal\",\"url\":\"https://docs.spurtcommerce.com/documentation/core-concepts/payments/pay-pal\",\"mainEntityOfPage\":{\"@id\":\"https://docs.spurtcommerce.com/documentation/core-concepts/payments/pay-pal#webpage\"},\"dateModified\":\"2026-11-14T10:14:21.333Z\",\"publisher\":{\"@id\":\"https://docs.spurtcommerce.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.spurtcommerce.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"SpurtCommerce\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"SpurtCommerce\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/documentation/core-concepts/payments/pay-pal.md","siteName":"SpurtCommerce","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Introduction","href":"/documentation/references/introduction"},{"group":"Getting Started","pages":[{"title":"Installation","icon":{"name":"download","style":"regular","library":"fontawesome"},"href":"/Getting Started/installation"},{"title":"Payload setup","icon":{"name":"brackets-curly","style":"regular","library":"fontawesome"},"href":"/Getting Started/payload-setup"},{"title":"Trial API","icon":{"name":"play-circle","style":"regular","library":"fontawesome"},"description":null,"href":"/Getting Started/trial-api"}]},{"group":"Core concepts","pages":[{"group":"Payments","pages":[{"title":"PayPal","icon":{"name":"paypal","style":"regular","library":"fontawesome"},"href":"/documentation/core-concepts/payments/pay-pal"},{"title":"Razorpay","icon":{"name":"r","style":"regular","library":"fontawesome"},"description":null,"href":"/documentation/core-concepts/payments/razorpay"},{"title":"Stripe","icon":{"name":"stripe","style":"regular","library":"fontawesome"},"href":"/documentation/core-concepts/payments/stripe"}]},{"title":"Authorization","icon":{"name":"check-circle","style":"regular","library":"fontawesome"},"href":"/Core concepts/authorization"},{"title":"Cart","icon":{"name":"cart-shopping-fast","style":"regular","library":"fontawesome"},"href":"/documentation/cart"},{"title":"Category","icon":{"name":"layer-group","style":"regular","library":"fontawesome"},"href":"/documentation/category"},{"title":"Collections","icon":{"name":"album-collection","style":"regular","library":"fontawesome"},"href":"/documentation/collections"},{"title":"Currency","icon":{"name":"squareapore-dollar","style":"regular","library":"fontawesome"},"href":"/documentation/currency"},{"title":"Customer Management","icon":{"name":"user","style":"regular","library":"fontawesome"},"href":"/documentation/customer-management"},{"title":"Inventory","icon":{"name":"inventory","style":"regular","library":"fontawesome"},"href":"/documentation/inventory"},{"title":"Languages","icon":{"name":"hands-american-sign-language-interpreting","style":"regular","library":"fontawesome"},"href":"/documentation/languages"},{"title":"Mail Service","icon":{"name":"mail-bulk","style":"regular","library":"fontawesome"},"href":"/documentation/mail-service"},{"title":"Orders","icon":{"name":"reorder","style":"regular","library":"fontawesome"},"href":"/documentation/orders"},{"title":"Permission","icon":{"name":"portal-enter","style":"regular","library":"fontawesome"},"href":"/documentation/permission"},{"title":"Products","icon":{"name":"bags-shopping","style":"regular","library":"fontawesome"},"href":"/documentation/products"},{"title":"Shipping","icon":{"name":"truck-container","style":"regular","library":"fontawesome"},"href":"/documentation/shipping"},{"title":"Zones","icon":{"name":"globe-europe","style":"regular","library":"fontawesome"},"href":"/documentation/zones"},{"title":"Tax","icon":{"name":"money-bills-simple","style":"regular","library":"fontawesome"},"href":"/documentation/tax"}]},{"group":"Developers","pages":[{"title":"Database","icon":{"name":"database","style":"regular","library":"fontawesome"},"href":"/documentation/developers/database"},{"title":"Environment setup","icon":{"name":"sunset","style":"regular","library":"fontawesome"},"href":"/documentation/developers/env-setup"},{"title":"Error Handling","icon":{"name":"warning","style":"regular","library":"fontawesome"},"href":"/documentation/developers/error-handling"},{"title":"Events","icon":{"name":"clock-eleven","style":"regular","library":"fontawesome"},"href":"/documentation/developers/events"},{"title":"File uploading","icon":{"name":"file-upload","style":"regular","library":"fontawesome"},"href":"/documentation/developers/file-uploading"},{"title":"Importing data","icon":{"name":"file-import","style":"regular","library":"fontawesome"},"href":"/documentation/developers/imports-data"},{"title":"Database migrations","icon":{"name":"money-bill-transfer","style":"regular","library":"fontawesome"},"href":"/documentation/developers/migrations"},{"title":"Plugins","icon":{"name":"plug","style":"regular","library":"fontawesome"},"href":"/documentation/developers/plugins"},{"title":"REST APIs","icon":{"name":"gear-complex-api","style":"regular","library":"fontawesome"},"href":"/documentation/developers/rest-apis"},{"title":"Security","icon":{"name":"camera-security","style":"regular","library":"fontawesome"},"href":"/documentation/developers/security"},{"title":"Translatable content","icon":{"name":"language","style":"regular","library":"fontawesome"},"href":"/documentation/developers/translatable"}]},{"title":"Deployment","icon":{"name":"✈️","style":"regular","library":"fontawesome"},"href":"/documentation/deployment/deployment"},{"title":"References","icon":{"name":"📚","style":"regular","library":"fontawesome"},"href":"/documentation/references/references"}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/store-api-reference/cart-items/get-the-current-customer-cart"}]},{"tab":"Add-ons","pages":[{"title":"Add-ons","href":"/documentation/addons/shopping-list"}]}]},"basePath":"","title":"PayPal - SpurtCommerce","buildId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","deploymentId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","dynamics":[],"chunks":[]}