{
    "componentChunkName": "component---src-templates-article-page-template-js",
    "path": "/how-to/how-to-integrate-3rd-party-payment-gateway/",
    "result": {"data":{"markdownRemark":{"frontmatter":{"title":"How to integrate a 3rd-party payment gateway with your marketplace","slug":"how-to-integrate-3rd-party-payment-gateway","updated":"2021-03-19T00:00:00.000Z","category":"how-to-payments","ingress":"This guide describes, on a high-level, how to integrate any 3rd-party payment gateway with your Flex-powered marketplace.","skills":null},"htmlAst":{"type":"root","children":[{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Sharetribe Flex provides out-of-the-box integration with Stripe. To\nreach markets not supported by Stripe, relying on another payment\ngateway can be crucial. This guide describes on a high-level, without\ngoing into the details of specific payment gateways, how to integrate\nany 3rd-party payment gateway (such as "},{"type":"element","tagName":"a","properties":{"href":"https://www.paypal.com/us/business/platforms-and-marketplaces","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"PayPal Commerce\nPlatform"}]},{"type":"text","value":", "},{"type":"element","tagName":"a","properties":{"href":"https://www.mangopay.com/marketplaces/","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"MANGOPAY"}]},{"type":"text","value":",\nor "},{"type":"element","tagName":"a","properties":{"href":"https://www.adyen.com/our-solution/marketplaces-and-platforms","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Adyen for Platforms"}]},{"type":"text","value":") with Sharetribe Flex."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"prerequisites","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#prerequisites","ariaLabel":"prerequisites permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Prerequisites"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Before reading this guide, you should be familiar with the following\nSharetribe Flex features:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/concepts/privileged-transitions/"},"children":[{"type":"text","value":"Privileged transitions"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/references/events/"},"children":[{"type":"text","value":"Events"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/how-to/reacting-to-events/"},"children":[{"type":"text","value":"Reacting to events"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/references/extended-data/"},"children":[{"type":"text","value":"Extended data"}]}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"marketplace-payment-flow","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#marketplace-payment-flow","ariaLabel":"marketplace payment flow permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Marketplace payment flow"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In this section we illustrate a marketplace payment flow in high-level\nand briefly discuss each stage. Later in this article, we'll go through\nhow to integrate each state with your Flex-powered marketplace."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In a nutshell, a payment flow in a marketplace contains five significant\nsteps. The following diagram illustrates a timeline of these steps:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-wrapper"],"style":"position: relative; display: block; margin-left: auto; margin-right: auto; max-width: 635px; "},"children":[{"type":"text","value":"\n      "},{"type":"element","tagName":"a","properties":{"className":["gatsby-resp-image-link"],"href":"/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/7cb9f/payment-flow.png","style":"display: block","target":"_blank","rel":["noopener"]},"children":[{"type":"text","value":"\n    "},{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-background-image"],"style":"padding-bottom: 86.79245283018868%; position: relative; bottom: 0; left: 0; background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAARCAYAAADdRIy+AAAACXBIWXMAAAsTAAALEwEAmpwYAAACTElEQVQ4y31UXW/aQBD0//8jfQ4vUaVUihJRKY2apoQGCUhjQgP+uk/7zodJmWrPPgMN7cPK6znf7M3sniPT7HB/c4Uf376AcqENZGkhqxqitCdjv2ZQut+Yz0YY3V1C1VtE9g34MBjg7OITKOfaQHQblKlhXQO72QdhPak20M0Oq+EtlmfnULZBlHGFwTjBx0mKQuq+Oi8tjGvgnAMXEowLOLfxGK0FFbmu8OvuGcvrKZJCIkq5QpamSNMMudBHUlVVo7QO2tQ+KD9c94RcY5EXiBnDKueIlHEQlYM0Dj7XBsptoVzjc9rItPFxSCR7W6iggypraLtBJCsLptqPSYbZAdPLK8yuP/tcHTThkOiwOeR74IgIZKqCl841MlniaTLD02SOxGPKe0MbAgFJV2bTk/JOBeU9YcIUMqGRFAJrrnysMoaUa6wL2W+2botRvMbL6xqGrOlOfUzYvZAf0tQwdutDBV9L60mDisf4FU/xAilrsZQpFKp6T0hh7Bse8xkm+dznQSbJJjJ6pkwgYRKrXHiMSI8JlfFVaIEJg9v4O74uHlDw1tsg2SuoalT2DVW980MeMH7soWnlkIcko9DIita7gAUPTb3DeD3GeDn0xETaEtrTHrbD3EB1HwcPk05BLgwe4hEepxdIWekxKpjL8pSH1p/g5mWI8fM5jIPHiDDtpoAakbESGbd+IlpMIZd/ebjvYonpco6f8T2SgxMED/dR9/lpD6mKKLsxIN+qVkqHBRXvfmXdj+RoDnln+P9OIP5xBffXr23KH3rtC9aYAmfXAAAAAElFTkSuQmCC'); background-size: cover; display: block;"},"children":[]},{"type":"text","value":"\n  "},{"type":"element","tagName":"picture","properties":{},"children":[{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/82e29/payment-flow.webp 159w","/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/ef33f/payment-flow.webp 318w","/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/f1837/payment-flow.webp 635w","/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/29549/payment-flow.webp 953w","/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/6a68d/payment-flow.webp 968w"],"sizes":"(max-width: 635px) 100vw, 635px","type":"image/webp"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/8b9b5/payment-flow.png 159w","/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/fa108/payment-flow.png 318w","/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/53fb6/payment-flow.png 635w","/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/5a426/payment-flow.png 953w","/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/7cb9f/payment-flow.png 968w"],"sizes":"(max-width: 635px) 100vw, 635px","type":"image/png"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"img","properties":{"className":["gatsby-resp-image-image"],"src":"/docs/legacy/static/746eb0b0a7de156abe410bca116882b1/53fb6/payment-flow.png","alt":"Marketplace payment flow","title":"Marketplace payment flow","loading":"lazy","decoding":"async","style":"width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0;"},"children":[]},{"type":"text","value":"\n        "}]},{"type":"text","value":"\n  "}]},{"type":"text","value":"\n    "}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"[comment]:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h1","properties":{"id":"","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#","ariaLabel":" permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"'Diagram source: "},{"type":"element","tagName":"a","properties":{"href":"https://whimsical.com/how-to-integrate-a-3rd-party-payment-gateway-PBY6qRjauyb7v5pEdXY4pS","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"https://whimsical.com/how-to-integrate-a-3rd-party-payment-gateway-PBY6qRjauyb7v5pEdXY4pS"}]},{"type":"text","value":"'"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"step-1-provider-onboarding","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#step-1-provider-onboarding","ariaLabel":"step 1 provider onboarding permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Step 1: Provider onboarding"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In this step, the provider connects their Flex account with the payment\ngateway. This is the step when they provide the bank details where the\nmoney from the customers will be transferred to. In addition, in this\nstep, they provide the necessary information and documents for the\nidentity verification and "},{"type":"element","tagName":"em","properties":{},"children":[{"type":"text","value":"Know Your Customer (KYC)"}]},{"type":"text","value":" requirements."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"step-2-customer-checkout","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#step-2-customer-checkout","ariaLabel":"step 2 customer checkout permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Step 2: Customer checkout"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Customer checkout happens when the customer initiates a transaction. At\nthis stage, they also provide the payment information, such as their\ncredit card number. Also, the payment will be made at this point. The\npayment gateway will preauthorize the money, i.e. reserve the money on\ncustomer's credit card."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"step-3-provider-accept","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#step-3-provider-accept","ariaLabel":"step 3 provider accept permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Step 3: Provider accept"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"After the customer has checked out, the provider has ability to either\naccept or reject the request. If the request is accepted, the payment\nwill be captured, and the reserved money will be transferred from\ncustomer's credit card to the payment gateway."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Provider accept is a step that you can combine with the customer\ncheckout. The flow where provider accept happens instantly after\ncustomer checkout is called \"instant booking\" flow."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"step-4-customer-refund","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#step-4-customer-refund","ariaLabel":"step 4 customer refund permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Step 4: Customer refund"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Typically, the marketplace payment flow contains a delayed payment\nperiod. This is the time between the money is captured from customer's\ncredit card and transferred to the provider's bank account. The payout\nin marketplaces usually happen after the provider has successfully\nprovided the agreed service."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Customer refund usually happens during the delayed payment period. There\nare many reasons why a refund may be necessary, for example, the\nprovider or customer may not be able to make it or the provided service\nwas not what was agreed."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"step-5-provider-payout","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#step-5-provider-payout","ariaLabel":"step 5 provider payout permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Step 5: Provider payout"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"If everything in the transaction went right and the customer received\nthe agreed service, the money from the payment gateway will be\neventually paid out to the provider."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"can-i-just-accept-all-payments-to-my-own-bank-account-and-pay-my-providers-manually","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#can-i-just-accept-all-payments-to-my-own-bank-account-and-pay-my-providers-manually","ariaLabel":"can i just accept all payments to my own bank account and pay my providers manually permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Can I just accept all payments to my own bank account and pay my providers manually?"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"You might be wondering if it would be easier for you to just accept the\nentire payment to your own bank account, and handle refunds to customers\npayouts to providers separately, outside the main platform\nfunctionality."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In terms of development work required to build the integration, this is\nindeed a lot easier. Any online payment service provider in the world\nsupports such a simple checkout flow."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"However, this can lead to a myriad of issues in terms of regulation,\naccounting, and liability. You could be considered as holding other\npeople's money, which is a heavily regulated area. In many countries,\nyou need to acquire an expensive license for this purpose, and holding\nmoney without such a license is considered a crime. You might also be\nconsidered to be responsible for providing the goods or services your\nproviders are selling, which is not always desirable. Finally, handling\nthe payouts to the providers correctly can be quite a lot of manual,\nerror-prone labor. You also still need to ensure the Know Your Customer\nprocess has been done correctly for them."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Because of these challenges, we recommend you to only consider building\na flow where the entire payment goes to your account only if you're\nabsolutely sure that you're aware of all the consequences, and have\ngotten your approach greenlighted by your accountant and a lawyer\nfamiliar with the matter."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"From now on, this article focuses on integrating with a\nmarketplace-specific payment solution, which handles the issues\ndescribed above for you. "},{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/academy/marketplace-payments/","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Learn more about choosing the right payment\nservice provider"}]},{"type":"text","value":"."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"before-you-start-the-integration","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#before-you-start-the-integration","ariaLabel":"before you start the integration permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Before you start the integration"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Before you start coding the integration, we strongly advise you to\ncontact the payment provider's customer support team."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Keep in mind that while many payment providers give you access to their\nsandbox environment, access to the live environment usually needs\ncontacting customer support and possibly signing a contract with them."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Contact the support and make sure that:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"They are available in the country where you operate your business"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"They support a marketplace-specific payment flow, handling Know Your\nCustomer process for your providers and splitting payments"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"They can process the currencies of your marketplace"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"They can do payouts to your providers' country/countries"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"You are eligible to get access to the live environment"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"You know the process of how to get access to the live environment"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"You are familiar with the fees involved."}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"white-label-or-hosted-onboarding-and-payments","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#white-label-or-hosted-onboarding-and-payments","ariaLabel":"white label or hosted onboarding and payments permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"White-label or hosted onboarding and payments"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Before integrating a 3rd-party payment gateway with Flex, a few words on\nthe different onboarding and payment experiences the payment gateways\noffer. The different experiences have implications for the integration,\nbranding, and also the level of PCI-compliance required."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"There are two main types of onboarding and payment experiences the\npayment gateways offer: white-label and hosted. However, most providers\noffer a mix of both."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"white-label-onboarding-and-payments","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#white-label-onboarding-and-payments","ariaLabel":"white label onboarding and payments permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"White-label onboarding and payments"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Payment gateways such as "},{"type":"element","tagName":"a","properties":{"href":"https://www.mangopay.com/marketplaces/","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"MANGOPAY"}]},{"type":"text","value":" and\n"},{"type":"element","tagName":"a","properties":{"href":"https://www.adyen.com/our-solution/marketplaces-and-platforms","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Adyen"}]},{"type":"text","value":" offer a so-called white-label experience.\nThis experience is closest to the default "},{"type":"element","tagName":"a","properties":{"href":"https://stripe.com/connect","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Stripe\nConnect"}]},{"type":"text","value":" integration in Flex."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"A white-label experience means that you build the payment flow inside\nyour marketplace application. This way, you have control over the\nuser-interface and branding. The downside is that the integration\nrequires more coding to build, most likely requires more maintenance,\ntoo. The regulations concerning online payments may change, which means\nyou'll need to update your integration accordingly."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"When using white-label experience, you may also need to do some work\nregarding PCI-compliance, but more on that later."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"hosted-onboarding-and-payments","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#hosted-onboarding-and-payments","ariaLabel":"hosted onboarding and payments permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Hosted onboarding and payments"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Some payment gateways, such as PayPal, offer a hosted experience. In\nthis case, the seller onboarding and customer payments happen by\nredirecting your user to the payment provider's website. After the\ncustomer completes the payment, the payment gateway redirects them to\nyour application to the return URL you provided. This is also the case\nwith seller onboarding: they'll interact with the branded user interface\nof the payment gateway."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"With this model, you have limited control over the user-interface on the\npayment provider's website. However, there is also less coding required\nfrom you: The payment provider has already implemented the required\nforms and hosts them for you. In the case of a well-known payment\ngateway, their branded payment experience can also increase the\nperceived security of the payment experience."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In case of regulatory changes, the payment provider updates their\nuser-interface to comply with the new regulation. Most likely, you also\ndon't need to do any work regarding PCI-compliance when using a hosted\nexperience."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"hosted-onboarding-and-white-label-payments","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#hosted-onboarding-and-white-label-payments","ariaLabel":"hosted onboarding and white label payments permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Hosted onboarding and white-label payments"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"White-label payment gateways usually offer an option to use hosted pages\nin some stages of the payment flow. We offer this approach by default\nwith the Stripe integration in Flex, where we use "},{"type":"element","tagName":"a","properties":{"href":"https://stripe.com/connect/onboarding","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"hosted pages for\nprovider onboarding"}]},{"type":"text","value":" and a white-label\nexperience for customer checkout."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Using hosted pages for some parts of the payment flow and white-label\nexperience for other parts provides a good balance between the work\nrequired from you and the ability to customize the user experience. For\nexample, we've chosen to use Stripe-hosted pages for Flex's provider\nonboarding because in this step, compliance with the "},{"type":"element","tagName":"em","properties":{},"children":[{"type":"text","value":"Know Your\nCustomer"}]},{"type":"text","value":" (KYC) guidelines is critical and may include uploading\nidentity documents or utility bills. Implementing all that in a\nwhite-label fashion would require an undesirable amount of work."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"do-you-need-to-be-pci-dss-compliant-to-integrate-with-a-3rd-party-payment-gateway","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#do-you-need-to-be-pci-dss-compliant-to-integrate-with-a-3rd-party-payment-gateway","ariaLabel":"do you need to be pci dss compliant to integrate with a 3rd party payment gateway permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Do you need to be PCI DSS compliant to integrate with a 3rd-party payment gateway?"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"PCI DSS stands for Payment Card Industry Data Security Standards. It is\na set of security standards to ensure that companies that accept credit\ncard payments process, store, and transfer the credit card information\nsecurely."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Since you are operating a marketplace business that accepts payment by\ncredit card, you have to be PCI DSS compliant. However, there are\ndifferent levels to PCI DSS compliance. You can reduce your required\nlevel of compliance significantly by using a payment gateway that offers\ntools like hosted pages and components or client-side encryption of the\ncredit card information."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"All of the payment gateways listed in this article\n("},{"type":"element","tagName":"a","properties":{"href":"https://www.adyen.com/our-solution/marketplaces-and-platforms","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Adyen"}]},{"type":"text","value":", "},{"type":"element","tagName":"a","properties":{"href":"https://www.paypal.com/us/business/platforms-and-marketplaces","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"PayPal"}]},{"type":"text","value":",\n"},{"type":"element","tagName":"a","properties":{"href":"https://www.mangopay.com/marketplaces/","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"MANGOPAY"}]},{"type":"text","value":", and "},{"type":"element","tagName":"a","properties":{"href":"https://stripe.com/connect","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Stripe"}]},{"type":"text","value":") offer\nsuch tools."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"pci-dss-compliance-levels","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#pci-dss-compliance-levels","ariaLabel":"pci dss compliance levels permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"PCI DSS compliance levels"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"There are four PCI DSS compliance levels, where Level 1 is the\nstrictest."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Level 4 is for small-to-medium-sized businesses that process less than\n20,000 transactions per year. Most early-stage marketplace entrepreneurs\nstart at this level."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The only requirement for becoming Level 4 PCI DSS compliant is to\nperform a Self-Assessment Questionnaire (SAQ)."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"self-assessment-questionnaire-saq","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#self-assessment-questionnaire-saq","ariaLabel":"self assessment questionnaire saq permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Self-Assessment Questionnaire (SAQ)"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The PCI Security Standards Council offers several SAQ questionnaire\ndocuments. The one you should choose depends on your payment\nintegration."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"If you outsource credit card information processing to a PCI-compliant\n3rd-party payment gateway, the required questionnaire is\n"},{"type":"element","tagName":"a","properties":{"href":"https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Self-Assessment Questionnaire A (SAQ A)"}]},{"type":"text","value":". The SAQ A is\nrelatively short (24 yes/no questions)."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Some payment gateways prefill the questionnaire for you. "},{"type":"element","tagName":"a","properties":{"href":"https://stripe.com/en-fi/guides/pci-compliance#how-stripe-helps-organizations-achieve-and-maintain-pci-compliance","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"This is, for\nexample, what Stripe does."}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"when-and-where-do-i-submit-the-self-assessment-questionnaire","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#when-and-where-do-i-submit-the-self-assessment-questionnaire","ariaLabel":"when and where do i submit the self assessment questionnaire permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"When and where do I submit the Self-Assessment Questionnaire?"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Most likely, your payment gateway will contact you and ask you to upload\nthe Self-Assessment Questionnaire and additional documents, if\nnecessary."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h4","properties":{"id":"example-stripe","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#example-stripe","ariaLabel":"example stripe permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Example: Stripe"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"If you use "},{"type":"element","tagName":"a","properties":{"href":"https://stripe.com/docs/security/guide#validating-pci-compliance","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Stripe Checkout/Elements, Mobile SDK, or\nConnect"}]},{"type":"text","value":", Stripe pre-fills the SAQ A for\nyou."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Stripe monitors your transaction volume and notifies if a "},{"type":"element","tagName":"a","properties":{"href":"https://stripe.com/en-fi/guides/pci-compliance#how-stripe-helps-organizations-achieve-and-maintain-pci-compliance","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"growing\ntransaction volume will require a change in how you validate\ncompliance"}]},{"type":"text","value":"."}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h4","properties":{"id":"example-adyen","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#example-adyen","ariaLabel":"example adyen permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Example: Adyen"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"If you use "},{"type":"element","tagName":"a","properties":{"href":"https://docs.adyen.com/development-resources/pci-dss-compliance-guide?tab=pay_by_link_1#online-payments","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Pay by Link"}]},{"type":"text","value":" (hosted experience), Adyen\ndoesn't require you to submit SAQ A."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"If you use "},{"type":"element","tagName":"a","properties":{"href":"https://docs.adyen.com/development-resources/pci-dss-compliance-guide?tab=drop_in_or_components_2#online-payments","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Drop-in or Components"}]},{"type":"text","value":"\n(white-label), Adyen requires you to assess your compliance with SAQ A\nand submit the filled questionnaire."}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"conclusion-about-marketplace-pci-dss-compliance","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#conclusion-about-marketplace-pci-dss-compliance","ariaLabel":"conclusion about marketplace pci dss compliance permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Conclusion about marketplace PCI DSS compliance"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"On some level, you need to be PCI DSS compliant."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"However, if you are on Level 4, depending on the type of your payment\nintegration, becoming PCI DSS compliant requires little to no work from\nyou."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"communication-between-the-marketplace-app-and-payment-gateway","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#communication-between-the-marketplace-app-and-payment-gateway","ariaLabel":"communication between the marketplace app and payment gateway permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Communication between the marketplace app and payment gateway"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Before integrating a 3rd-party payment gateway into your marketplace,\nit's good to be aware of the different methods apps can use to\ncommunicate with a payment gateway."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The most common communication methods are:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"API calls"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Redirect URLs and Return URLs"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Webhooks."}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The communication method to use depends on the onboarding and payment\nexperience, and the payment flow stage. For example, Redirect URLs are\nonly used for hosted onboarding and payment pages. API calls instead are\nheavily used for white-label onboarding and payments, but they are also\nneeded even when using hosted payments to request the hosted page URL\nwhere the user should be redirected."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Next, we'll go through all the different communication methods."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"api-calls","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#api-calls","ariaLabel":"api calls permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"API calls"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The marketplace can communicate with the payment gateway by calling\ntheir API. The marketplace needs to do this for example to request URL\nfor the hosted page or make a payment in a white-label fashion. Even\nwhen using hosted experience payments, you still need to make API calls\nto the payment gateway for some payment actions, such as capturing the\npayment or refunding a payment."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"To call the API, the payment gateways require you to use a secret key\nwhich you should never expose to the public. Thus, the API calls to the\npayment gateway need to happen from your marketplace backend, never from\nthe user's browser."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"redirect-urls-and-return-urls","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#redirect-urls-and-return-urls","ariaLabel":"redirect urls and return urls permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Redirect URLs and Return URLs"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"When using hosted pages (i.e. your onboarding or payment experience is\nfully hosted or combines hosted and white-label stages), your app\ncommunicates with the payment gateway through data added in the URL."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Before redirecting your user to the hosted page, your marketplace makes\nan API call to the payment gateway to request the URL to the hosted\npage. At this point, your marketplace provides the payment gateway two\ndifferent return URLs: one for when a payment is completed by the user,\nand one for failed or canceled payment. After receiving the hosted page\nURL from the payment gateway, you redirect the user to that URL."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"When the user returns from the hosted page, the payment gateway\nredirects them to one of the return URLs depending on the payment\nstatus."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-wrapper"],"style":"position: relative; display: block; margin-left: auto; margin-right: auto; max-width: 635px; "},"children":[{"type":"text","value":"\n      "},{"type":"element","tagName":"a","properties":{"className":["gatsby-resp-image-link"],"href":"/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/761b7/redirect-url-sequence.png","style":"display: block","target":"_blank","rel":["noopener"]},"children":[{"type":"text","value":"\n    "},{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-background-image"],"style":"padding-bottom: 39.62264150943396%; position: relative; bottom: 0; left: 0; background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAICAYAAAD5nd/tAAAACXBIWXMAAAsTAAALEwEAmpwYAAABLUlEQVQoz12QyXLEIAxE/f//mFTKHq8gNrHYvnRKgDNTObwSzdISPcRccGhCKidcLEjlgiILFxghtz1OGYEjODVdrhscE8p5Vy0evp4XDDGfOLRBiBkUEhwn7IpgPYPLjZCv+lAacj5huSB3nc4Ltg8hPrGcGGTD+IhNW6yCsjjI4aUM5oMw74TxICgf6zSWMwy35rJ2nGt99CCXjIiQWuUM7SMm1cwEMZcHPpVq+hi32puEpquhIod5U5g6m0xkwx+HCVCO31iGdgwfnwb/DHfDWLTHSqEya49xI4yrxrQqjKvCoiQSh408ZiU1gEKGfvDpw9BGzBSxmIasq6aAcTnwPa34Ghf8vDbMymIxqZ6vNlVE764b2p6HjC8ZfeYkX3nysfym3nnedJ5MfwEuK2JJF6pBtwAAAABJRU5ErkJggg=='); background-size: cover; display: block;"},"children":[]},{"type":"text","value":"\n  "},{"type":"element","tagName":"picture","properties":{},"children":[{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/82e29/redirect-url-sequence.webp 159w","/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/ef33f/redirect-url-sequence.webp 318w","/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/f1837/redirect-url-sequence.webp 635w","/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/29549/redirect-url-sequence.webp 953w","/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/c5420/redirect-url-sequence.webp 1270w","/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/bda03/redirect-url-sequence.webp 1641w"],"sizes":"(max-width: 635px) 100vw, 635px","type":"image/webp"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/8b9b5/redirect-url-sequence.png 159w","/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/fa108/redirect-url-sequence.png 318w","/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/53fb6/redirect-url-sequence.png 635w","/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/5a426/redirect-url-sequence.png 953w","/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/91155/redirect-url-sequence.png 1270w","/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/761b7/redirect-url-sequence.png 1641w"],"sizes":"(max-width: 635px) 100vw, 635px","type":"image/png"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"img","properties":{"className":["gatsby-resp-image-image"],"src":"/docs/legacy/static/8b7d5196fdec2d8f49f621131edd916e/53fb6/redirect-url-sequence.png","alt":"Redirect and return URL call sequence","title":"Redirect and return URL call sequence","loading":"lazy","decoding":"async","style":"width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0;"},"children":[]},{"type":"text","value":"\n        "}]},{"type":"text","value":"\n  "}]},{"type":"text","value":"\n    "}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"[comment]:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h1","properties":{"id":"-1","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#-1","ariaLabel":" 1 permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"'Diagram source: "},{"type":"element","tagName":"a","properties":{"href":"https://whimsical.com/how-to-integrate-a-3rd-party-payment-gateway-PBY6qRjauyb7v5pEdXY4pS","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"https://whimsical.com/how-to-integrate-a-3rd-party-payment-gateway-PBY6qRjauyb7v5pEdXY4pS"}]},{"type":"text","value":"'"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The payment gateway appends data about the onboarding or payment result\nto the return URL query parameters. When it redirects the user to your\napplication, you can read this data from the URL and store it for later\nuse. You can use "},{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/marketplace.html#update-user-profile","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"the Marketplace API's update current user\nendpoint"}]},{"type":"text","value":" to store seller's\nonboarding status to current user's private data or the "},{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/integration.html#update-transaction-metadata","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Integration API\nto store payment status to transaction's\nmetadata"}]},{"type":"text","value":"."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h4","properties":{"id":"example-paypal-redirect-after-seller-onboarding","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#example-paypal-redirect-after-seller-onboarding","ariaLabel":"example paypal redirect after seller onboarding permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Example: PayPal redirect after seller onboarding"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"After successful seller onboarding, PayPal redirects the seller to the\nreturn URL and "},{"type":"element","tagName":"a","properties":{"href":"https://developer.paypal.com/docs/platforms/seller-onboarding/before-payment/#4-redirect-seller","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"loads the URL with the following query\nparameters"}]},{"type":"text","value":":"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"merchantId"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"merchantIdInPayPal"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"permissionsGranted"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"accountStatus"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"consentStatus"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"productIntentId"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"isEmailConfirmed"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"returnMessage"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"riskStatus"}]}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The marketplace should store at least the "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"merchantId"}]},{"type":"text","value":" to current user's\nprivate data. Later on, when a customer makes a payment to the seller,\nthe "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"merchantId"}]},{"type":"text","value":" is needed in order to pay for the correct seller."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"webhooks","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#webhooks","ariaLabel":"webhooks permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Webhooks"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Payment gateways send webhook notifications that you can listen to."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"You may want to listen to these notifications in a case where customer\nonboarding on a hosted page contains multiple steps or when a particular\npayment action such as payout is happening without user involvement, and\nyou want to know the status of that action."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h4","properties":{"id":"example-paypal-onboarding","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#example-paypal-onboarding","ariaLabel":"example paypal onboarding permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Example: PayPal onboarding"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://developer.paypal.com/docs/platforms/seller-onboarding/before-payment/#5-track-seller-onboarding-status","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"PayPal seller onboarding"}]},{"type":"text","value":" is complete\nwhen the following requirements are met:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ol","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Seller creates a PayPal account."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Seller grants you permission for the\n"},{"type":"element","tagName":"a","properties":{"href":"https://developer.paypal.com/docs/api/partner-referrals/v2/#definition-rest_endpoint_feature","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"features"}]},{"type":"text","value":" you set."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Seller confirms the email address of the account."}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The marketplace can track the onboarding status by listening to the\nwebhook notifications. When the marketplace knows the onboarding status,\nit can be used to provide the seller a useful message in the marketplace\nuser-interface, should as \"PayPal account created, but the email address\nis not yet confirmed. Please confirm the email address in order to\ncomplete the onboarding\"."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h4","properties":{"id":"backend-endpoint-to-listen-to-webhook-notifications","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#backend-endpoint-to-listen-to-webhook-notifications","ariaLabel":"backend endpoint to listen to webhook notifications permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Backend endpoint to listen to webhook notifications"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"To listen to webhooks, you'll need to implement a new endpoint to your\nbackend and configure the payment gateway to send the notifications to\nthat URL. The endpoint should read the notifications and decide what to\ndo with them and where to store the information. If a notification is,\nfor example, about the user's onboarding status, you can use "},{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/integration.html#update-user-profile","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"the\nIntegration API to store the information in the user's private\ndata"}]},{"type":"text","value":". On the other hand, if the\nnotification is about a payment related to a transaction, you may want\nto store the information in the "},{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/integration.html#update-transaction-metadata","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"transaction's\nmetadata"}]},{"type":"text","value":" or "},{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/integration.html#transition-transaction","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"transition\nthe transaction"}]},{"type":"text","value":"."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"If you use Flex Template for Web, you can add a new endpoint by adding\nit to the "},{"type":"element","tagName":"a","properties":{"href":"https://github.com/sharetribe/ftw-daily/blob/master/server/apiRouter.js","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"API router"}]},{"type":"text","value":"."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"We recommend securing the endpoint with Basic Authentication if the\npayment gateway supports that."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"integrating-your-flex-marketplace-with-a-3rd-party-payment-gateway","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#integrating-your-flex-marketplace-with-a-3rd-party-payment-gateway","ariaLabel":"integrating your flex marketplace with a 3rd party payment gateway permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Integrating your Flex marketplace with a 3rd-party payment gateway"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"There are two main options for integrating Flex with a 3rd-party payment\ngateway:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/concepts/privileged-transitions/"},"children":[{"type":"text","value":"Privileged transitions"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/references/events/"},"children":[{"type":"text","value":"Events"}]},{"type":"text","value":"."}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"For some payment flow stages you can use either method to build the\nintegration, but for some stages using exactly one of the two is\nrequired. In the next chapter, we'll give our recommendations on which\noption to use in each step. First, a quick introduction to how each\nmethod works in practice."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"using-privileged-transitions","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#using-privileged-transitions","ariaLabel":"using privileged transitions permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Using privileged transitions"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"To use privileged transitions, you need to make a new endpoint to your\nbackend server. Your marketplace front-end should call this new backend\nendpoint and not the Flex API directly."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"If you use Flex Template for Web, you can add a new endpoint by adding\nit to the "},{"type":"element","tagName":"a","properties":{"href":"https://github.com/sharetribe/ftw-daily/blob/master/server/apiRouter.js","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"API router"}]},{"type":"text","value":"."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The new server endpoint should call the payment gateway API to do the\npayment action and the Flex Marketplace API to transition the\ntransaction."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The following diagram shows the call sequence between the marketplace\nand the APIs. First, a user makes a transaction request using the\nmarketplace front end, after which the backend calls the Flex\nMarketplace API to initiate the transaction. Next, the marketplace\nbackend calls the payment gateway's API, and finally the Flex\nMarketplace API is called again after the payment action is completed."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-wrapper"],"style":"position: relative; display: block; margin-left: auto; margin-right: auto; max-width: 635px; "},"children":[{"type":"text","value":"\n      "},{"type":"element","tagName":"a","properties":{"className":["gatsby-resp-image-link"],"href":"/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/d29d1/privileged-transitions-sequence.png","style":"display: block","target":"_blank","rel":["noopener"]},"children":[{"type":"text","value":"\n    "},{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-background-image"],"style":"padding-bottom: 61.0062893081761%; position: relative; bottom: 0; left: 0; background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAMCAYAAABiDJ37AAAACXBIWXMAAAsTAAALEwEAmpwYAAABf0lEQVQoz42S647cIAyF5/2fseom2dwAg7mTTFc6FcxkNmnVUX8cYcD+sI1vebtDkoEkjWobnxHLDusCxkUglQ0ubbCxIG87Ui7IZUPIGzhkpLK3fWracdvuXzDsQMZi+/UFDgVpu8OFiM9pRcwFLpUGjKmAXUCI6QksCPU+RDgfm32rr9hQQNqBtMVKFpIYRAx2ETY9MqzyeW/gQy22rqez23FB7GFcgGL/sK2H5IhJMfpJNA2LhODY/A/VeOPTy34BzfPgUC1z1BH9QujGFR9PjRRe2b0H+nR1DBnSJgyLOgEXCOOvD/8B/yewOo5k0ClCr3RbB9Kt7G6R+JAKP4Vq649VQD/jr8BTbypwUIxOKPSC0EvCsCp0M2FWBrO2mM1Dk+ZXy049LK/fPDTqhGE1reRuWhvsk2J77H3JPkERQ2qLhRiLYmhtIUyAtBH9LFoPBQcol//vl8m4Ni6SfRsd08bokc131tX3O/gtkOO15DrQJlyzefQ6/w08lfwbF/yTu6l0Xo0AAAAASUVORK5CYII='); background-size: cover; display: block;"},"children":[]},{"type":"text","value":"\n  "},{"type":"element","tagName":"picture","properties":{},"children":[{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/82e29/privileged-transitions-sequence.webp 159w","/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/ef33f/privileged-transitions-sequence.webp 318w","/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/f1837/privileged-transitions-sequence.webp 635w","/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/29549/privileged-transitions-sequence.webp 953w","/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/c5420/privileged-transitions-sequence.webp 1270w","/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/a309e/privileged-transitions-sequence.webp 1315w"],"sizes":"(max-width: 635px) 100vw, 635px","type":"image/webp"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/8b9b5/privileged-transitions-sequence.png 159w","/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/fa108/privileged-transitions-sequence.png 318w","/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/53fb6/privileged-transitions-sequence.png 635w","/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/5a426/privileged-transitions-sequence.png 953w","/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/91155/privileged-transitions-sequence.png 1270w","/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/d29d1/privileged-transitions-sequence.png 1315w"],"sizes":"(max-width: 635px) 100vw, 635px","type":"image/png"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"img","properties":{"className":["gatsby-resp-image-image"],"src":"/docs/legacy/static/4c9e2695f29d1a5825752b39f07e6d26/53fb6/privileged-transitions-sequence.png","alt":"Privileged transitions call sequence","title":"Privileged transitions call sequence","loading":"lazy","decoding":"async","style":"width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0;"},"children":[]},{"type":"text","value":"\n        "}]},{"type":"text","value":"\n  "}]},{"type":"text","value":"\n    "}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"[comment]:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h1","properties":{"id":"-2","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#-2","ariaLabel":" 2 permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"'Diagram source: "},{"type":"element","tagName":"a","properties":{"href":"https://whimsical.com/how-to-integrate-a-3rd-party-payment-gateway-PBY6qRjauyb7v5pEdXY4pS","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"https://whimsical.com/how-to-integrate-a-3rd-party-payment-gateway-PBY6qRjauyb7v5pEdXY4pS"}]},{"type":"text","value":"'"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Error handling in this model is simple. Because all the calls to the\nFlex Marketplace API and the payment gateway's API are triggered by the\nrequest of the end-user, your marketplace front-end can immediately\nreturn a failure response and show an error message to the user when\nthings go wrong."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"using-events","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#using-events","ariaLabel":"using events permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Using Events"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"You can also use Events for your payment gateway integration."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In this model, the transaction transition is done as usual. Your backend\npolls the events and reacts to transaction transition events by calling\nthe payment gateway API."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-wrapper"],"style":"position: relative; display: block; margin-left: auto; margin-right: auto; max-width: 635px; "},"children":[{"type":"text","value":"\n      "},{"type":"element","tagName":"a","properties":{"className":["gatsby-resp-image-link"],"href":"/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/e4ee6/events-sequence.png","style":"display: block","target":"_blank","rel":["noopener"]},"children":[{"type":"text","value":"\n    "},{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-background-image"],"style":"padding-bottom: 37.106918238993714%; position: relative; bottom: 0; left: 0; background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAHCAYAAAAIy204AAAACXBIWXMAAAsTAAALEwEAmpwYAAABIElEQVQoz1WQ3VIDIQyF+/5PqLaOHe0uvwsECNDeHIfsWvXim0lOwknCqfU7bqtCoow6HuB+R2VG5QbijjYesH6D2wJ4PESb9VwqShtItYNbB+UCbgOnzB0uZthY4ALBp4JQ+rM580AqLEhcO+oc2sZv3oYw35ymsOUGS/w0NokRSpPmScgNxkcsNmB1AavdZHCsHbE0qW+ZJX4azoYf3NwyM3wswpYqlA1Y7IbF7ARiEA/5AjqMp9dpJioQXheF86rwtqg9Vhqvt1U4r1ryizIHGhdtcDUO19XgXVuokED1ONlRxflL4eXjU7hqD5sKLBU4KtAxw6S8a6lIrCPBTj2Q1D3VfcNUm/yX9oTFeMHGvUgHqfT/+aHNjeTsPyd/A1IXFDvdc4WGAAAAAElFTkSuQmCC'); background-size: cover; display: block;"},"children":[]},{"type":"text","value":"\n  "},{"type":"element","tagName":"picture","properties":{},"children":[{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/82e29/events-sequence.webp 159w","/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/ef33f/events-sequence.webp 318w","/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/f1837/events-sequence.webp 635w","/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/29549/events-sequence.webp 953w","/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/c5420/events-sequence.webp 1270w","/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/7de62/events-sequence.webp 1568w"],"sizes":"(max-width: 635px) 100vw, 635px","type":"image/webp"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/8b9b5/events-sequence.png 159w","/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/fa108/events-sequence.png 318w","/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/53fb6/events-sequence.png 635w","/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/5a426/events-sequence.png 953w","/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/91155/events-sequence.png 1270w","/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/e4ee6/events-sequence.png 1568w"],"sizes":"(max-width: 635px) 100vw, 635px","type":"image/png"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"img","properties":{"className":["gatsby-resp-image-image"],"src":"/docs/legacy/static/162c3ec1b7fe97041a3dd7a611a6a59a/53fb6/events-sequence.png","alt":"Events call sequence","title":"Events call sequence","loading":"lazy","decoding":"async","style":"width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0;"},"children":[]},{"type":"text","value":"\n        "}]},{"type":"text","value":"\n  "}]},{"type":"text","value":"\n    "}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"[comment]:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h1","properties":{"id":"-3","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#-3","ariaLabel":" 3 permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"'Diagram source: "},{"type":"element","tagName":"a","properties":{"href":"https://whimsical.com/how-to-integrate-a-3rd-party-payment-gateway-PBY6qRjauyb7v5pEdXY4pS","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"https://whimsical.com/how-to-integrate-a-3rd-party-payment-gateway-PBY6qRjauyb7v5pEdXY4pS"}]},{"type":"text","value":"'"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Error handling in this model needs more attention than in the privileged\ntransition model. If the payment action fails, the transaction is in a\nstate where the transaction and payment are out of sync."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"Example:"}]},{"type":"text","value":" Let's imagine the customer made a transition \"cancel,\"\nwhich moved the transaction to the \"canceled\" state, but the \"refund\"\npayment action failed. If you don't handle this error state, the\ncustomer gets charged without receiving the service."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"There are a couple of ways you can set up Events to handle the error\ncase:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Retry the payment action immediately, in case of a network error or\nerror 5xx from the payment gateway."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Send a notification to the marketplace operator. The operator can then\nmanually resolve the issue (e.g., by manually refunding from the\npayment gateway's dashboard)"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Transition the transaction to an error state, e.g.,\n\"canceled-but-refund-failed.\" The operator then needs to manually\nresolve the issue with a refund."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Write the error in the transaction's metadata and show it to the user.\nThe user can then contact the operator to resolve the situation."}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"integrating-payment-steps-with-your-marketplace","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#integrating-payment-steps-with-your-marketplace","ariaLabel":"integrating payment steps with your marketplace permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Integrating payment steps with your marketplace"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In the beginning of this document we illustrated a high-level picture of\nthe different payment steps in a marketplace payment flow. In this\nchapter we'll go through each step and how to integrate them with your\nmarketplace."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"step-1-provider-onboarding-1","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#step-1-provider-onboarding-1","ariaLabel":"step 1 provider onboarding 1 permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Step 1: Provider onboarding"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The provider onboarding step usually needs to happen before the customer\nstarts the transaction. Onboarding can occur during or right after\nlisting creation."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"If you choose white-label onboarding, you need to build the necessary\nforms in your marketplace to ask for the required customer details.\nAlso, to comply with the "},{"type":"element","tagName":"em","properties":{},"children":[{"type":"text","value":"Know Your Customer"}]},{"type":"text","value":" (KYC) requirements, the\ncustomer may need to upload certain documents such as an identity\ndocument or a utility bill to prove their identity."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"If you're using a payment gateway that provides hosted onboarding, you\nneed to redirect the user to the onboarding page hosted by the payment\nprovider. When the user returns from the hosted page, you receive\ninformation about the newly created merchant account (e.g., a merchant\nID) in the return URL. You should store this information in the user's\nprivate data. You can use "},{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/marketplace.html#update-user-profile","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"the Marketplace API's update current user\nendpoint for this"}]},{"type":"text","value":"."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"Recommendation:"}]},{"type":"text","value":" Use hosted pages for onboarding if they are\navailable. Building the necessary forms, including the file upload\nforms, can be avoided using hosted pages. Besides, the KYC requirements\ntend to change over time. By using hosted pages, you avoid the need to\nchange your application when the requirements change. The payment\nprovider will keep the hosted pages up to date with the regulatory\nrequirements."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"step-2-customer-checkout-1","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#step-2-customer-checkout-1","ariaLabel":"step 2 customer checkout 1 permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Step 2: Customer checkout"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Customer checkout happens during transaction initialization, and it's an\nessential part of your marketplace payment flow. It's also the step that\nrequires the most integration work."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Before you start implementation, consider what payment methods you are\nabout to integrate and where your customers are located. Does the\npayment method have separate authorization and capture actions, or are\nthe funds immediately captured during the payment? Are your customers\nlocated in countries that require 3D Security?"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In this step, your marketplace collects the customer's credit card\ninformation. Keep in mind that you should never pass unencrypted credit\ncard information via your server. Use either the JavaScript\nlibrary/elements provided by the payment gateway, client-side\nencryption, or hosted pages when collecting credit card information."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"Recommendation:"}]},{"type":"text","value":" Use "},{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"privileged transitions"}]},{"type":"text","value":" for this step."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"Recommendation:"}]},{"type":"text","value":" Initiate the Flex transition before payment."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"If using 3D Security is required, the checkout process may contain\nmultiple steps where the customer may have to leave your marketplace app\nand go to their bank's website to confirm the payment. This process may\ntake some time for the user to complete. Because of that, we recommend\nthat you initiate the Flex transition first, before initiating the\npayment. During the initialization of the transaction, you can already\nmake a booking and ensure availability. It would be a bad experience for\nthe user to pay first but then realize that the transaction\ninitialization failed because someone else managed to book the selected\ntimeslot a moment before they did."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The transaction should be in a \"pending-payment\" state at this point.\nAfter the payment is successfully made, transition the transaction\nforward to a \"paid\" state. The \"pending-payment\" state should have an\nautomatic expiration, e.g., after 15 minutes. The user may not finalize\nthe payment, and thus we need to expire the transaction."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The transaction process should look something like this:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-wrapper"],"style":"position: relative; display: block; margin-left: auto; margin-right: auto; max-width: 480px; "},"children":[{"type":"text","value":"\n      "},{"type":"element","tagName":"a","properties":{"className":["gatsby-resp-image-link"],"href":"/docs/legacy/static/014b66b76c10195ef607d8c5a27a7898/532ad/checkout-transaction-process.png","style":"display: block","target":"_blank","rel":["noopener"]},"children":[{"type":"text","value":"\n    "},{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-background-image"],"style":"padding-bottom: 105.0314465408805%; position: relative; bottom: 0; left: 0; background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAVCAYAAABG1c6oAAAACXBIWXMAAAsTAAALEwEAmpwYAAACJUlEQVQ4y5VUa4+bQAzk//+z9ktPOkXXXJuQ8Ajv97IssGQqO0AJIacckrXG6x2MZ9ZGLhosLavkvE5+1bRs6/i0Ls1YB5aH+l7jer0iTjMkacZ+r/W4/3juOeAI2vUawzAgjBMEYcw+xRhQfANwqrKoFWrVIc4FkqJmn2Jbv/oUcNkj249hOj4O1gX7ow3T8WB70es9nMCmRALb/THx8feMX7tPfJo2Tm6wmfv1L49JterRDUCYloiyCq0Gx5Y5L/0yrXoYkBUl/DBCmuVIshxRnLBP5LwsmymJJEPsul4A1/NhORf2CVDr4akmjS1BT2JOS4nTJYRoOn4/X26ElFIx26VsHyo1ls2dNpJCwIsyfBwshFk5xmpYXoT3/RF+kiNIClyiFHFe3VX7wLJQHTP5822Ho+1xJbRHIMT4jfUTfrzt8P77ACeIUS60yRWmZOUt4IYp9qbDQJVs5y8X3IZuNjfMcHQCPjthzBVK1bGpTsOPMxRComn7uzu7bEvdtGh7DS9KkeQl59bj8DBIT/S0bYuz7cByXCilOJavhMuE1ApSSli2i7PlwA9CmGcLQtRMlpELydXVjeLKyOhrFKO9NSCtQiqUQiItKuRVzb5o1KKH5dgDPtTMPd2ajVM+9dgJEthBwv6U/3TarKu69yUTRjIiq1iPcluHW7pcr8Nw5R7TsCWjh2JfzsOvqqW7TNNba81G/nS/je+C8TpXL/8TN+rwH0KBSiEx6kn5AAAAAElFTkSuQmCC'); background-size: cover; display: block;"},"children":[]},{"type":"text","value":"\n  "},{"type":"element","tagName":"picture","properties":{},"children":[{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/014b66b76c10195ef607d8c5a27a7898/82e29/checkout-transaction-process.webp 159w","/docs/legacy/static/014b66b76c10195ef607d8c5a27a7898/ef33f/checkout-transaction-process.webp 318w","/docs/legacy/static/014b66b76c10195ef607d8c5a27a7898/5bde3/checkout-transaction-process.webp 480w"],"sizes":"(max-width: 480px) 100vw, 480px","type":"image/webp"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/014b66b76c10195ef607d8c5a27a7898/8b9b5/checkout-transaction-process.png 159w","/docs/legacy/static/014b66b76c10195ef607d8c5a27a7898/fa108/checkout-transaction-process.png 318w","/docs/legacy/static/014b66b76c10195ef607d8c5a27a7898/532ad/checkout-transaction-process.png 480w"],"sizes":"(max-width: 480px) 100vw, 480px","type":"image/png"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"img","properties":{"className":["gatsby-resp-image-image"],"src":"/docs/legacy/static/014b66b76c10195ef607d8c5a27a7898/532ad/checkout-transaction-process.png","alt":"Customer checkout transaction process","title":"Customer checkout transaction process","loading":"lazy","decoding":"async","style":"width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0;"},"children":[]},{"type":"text","value":"\n        "}]},{"type":"text","value":"\n  "}]},{"type":"text","value":"\n    "}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"[comment]:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h1","properties":{"id":"-4","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#-4","ariaLabel":" 4 permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"'Diagram source: "},{"type":"element","tagName":"a","properties":{"href":"https://whimsical.com/how-to-integrate-a-3rd-party-payment-gateway-PBY6qRjauyb7v5pEdXY4pS","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"https://whimsical.com/how-to-integrate-a-3rd-party-payment-gateway-PBY6qRjauyb7v5pEdXY4pS"}]},{"type":"text","value":"'"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The steps to implement this stage are:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ol","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Add ("},{"type":"element","tagName":"a","properties":{"href":"https://github.com/sharetribe/ftw-daily/blob/master/server/api/initiate-privileged.js","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"or modify existing"}]},{"type":"text","value":") server\nendpoint for initiating a transaction."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Initiate the transaction."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Make the payment after the transaction is initiated."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Ensure that the payment went through."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Transition the transaction forward."}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"step-3-provider-accept-1","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#step-3-provider-accept-1","ariaLabel":"step 3 provider accept 1 permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Step 3: Provider accept"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Depending on the payment method, the payment may happen in one or two\nsteps. The two steps are:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Authorization (payment gateway reserves the money from the buyer's\ncredit card)"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Capture (payment gateway transfers the money from the buyer)"}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Credit card payments use these two steps, whereas some payment methods\nlike "},{"type":"element","tagName":"a","properties":{"href":"https://www.giropay.de/","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"giropay"}]},{"type":"text","value":" or "},{"type":"element","tagName":"a","properties":{"href":"https://www.ideal.nl/en/","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"iDEAL"}]},{"type":"text","value":" have only one step where the\npayment is authorized and captured in one go."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"If you're using a payment method where authorization and capturing\nhappens in one step, you should skip the provider accept stage, and\nimplement a so-called \"instant booking\" flow. In this flow, the provider\nis expected to be able to provide the service to the customer, thus, no\nseparate accept stage is needed. For this to happen, the providers must\nkeep their availability calendar up-to-date."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Even if you're using payment method with separate authorization and\ncapture steps, it's worth considering whether you could streamline the\ntransaction process by implementing an instant book flow."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In case you decide to have the provider accept state to your transaction\nprocess, you should do the payment authorization on customer checkout\nand capture the payment on provider accept. After the money is captured,\nyou most likely need to pay the payment gateway's processing fees, even\nif the provider ends up declining the customer's request."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"If the provider declines the request, or if it expires due to a lack of\nanswer from the provider, the payment should be voided."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"Recommendation:"}]},{"type":"text","value":" Use "},{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"events"}]},{"type":"text","value":" for this step. Poll the\ntransaction/transition events and react on accept/decline/expire\ntransitions. Call the payment gateway API to either capture or void the\npayment."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"step-4-customer-refund-1","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#step-4-customer-refund-1","ariaLabel":"step 4 customer refund 1 permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Step 4: Customer refund"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In most marketplaces, it makes sense to have a delayed payment period.\nDuring this period, the customer has paid, but the money is not yet paid\nout to the provider. The provider is expected to provide the service\nfirst, and payout happens after the service was successfully provided."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Customer refund usually happens during this period."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"Recommendation:"}]},{"type":"text","value":" Use "},{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"events"}]},{"type":"text","value":" for this step. Poll the\ntransaction/transition events and react on transitions where a refund is\nneeded by calling the payment gateway API."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h3","properties":{"id":"step-5-provider-payout-1","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#step-5-provider-payout-1","ariaLabel":"step 5 provider payout 1 permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Step 5: Provider payout"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"At some point, it's time to release the money to the provider and do the\npayout."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Depending on the provider's bank, there's usually a delay between when\nthe payout is issued and when the money reaches the provider's bank\naccount. The delay is on a scale of days, but not weeks."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"Recommendation:"}]},{"type":"text","value":" Use "},{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"events"}]},{"type":"text","value":" for this step. Poll the\ntransaction/transition events and react on transitions where the payout\nis needed by calling the payment gateway API."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"summary","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#summary","ariaLabel":"summary permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Summary"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"In this document, we first illustrated on a high-level a typical\nmarketplace payment flow. After that, we went through the different\npayment gateway integration experiences, white-label and hosted, and\ntheir implications to the integration, branding, and PCI DSS compliance\nrequirements. We then discussed PCI DSS compliance in more detail."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"We discussed the integration and what are the options to communicate\nwith payment gateways. After that, we laid out the two different options\nto hook your payment integration code with Flex: privileged transitions\nand events. Finally, we went through each stage of the marketplace\npayment flow and gave recommendations on how to integrate a 3rd-party\npayment gateway to each step."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"further-reading","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#further-reading","ariaLabel":"further reading permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Further reading"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://docs.adyen.com/platforms/quick-start","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Platforms quick start by Adyen"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://developer.paypal.com/docs/platforms/","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"PayPal Commerce Platform for Marketplaces and Platforms developer\ndocumentation"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://docs.mangopay.com/","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"MANGOPAY API Documentation"}]}]},{"type":"text","value":"\n"}]}],"data":{"quirksMode":false}},"headings":[{"value":"Prerequisites","depth":2},{"value":"Marketplace payment flow","depth":2},{"value":"","depth":1},{"value":"Step 1: Provider onboarding","depth":3},{"value":"Step 2: Customer checkout","depth":3},{"value":"Step 3: Provider accept","depth":3},{"value":"Step 4: Customer refund","depth":3},{"value":"Step 5: Provider payout","depth":3},{"value":"Can I just accept all payments to my own bank account and pay my providers manually?","depth":2},{"value":"Before you start the integration","depth":2},{"value":"White-label or hosted onboarding and payments","depth":2},{"value":"White-label onboarding and payments","depth":3},{"value":"Hosted onboarding and payments","depth":3},{"value":"Hosted onboarding and white-label payments","depth":3},{"value":"Do you need to be PCI DSS compliant to integrate with a 3rd-party payment gateway?","depth":2},{"value":"PCI DSS compliance levels","depth":3},{"value":"Self-Assessment Questionnaire (SAQ)","depth":3},{"value":"When and where do I submit the Self-Assessment Questionnaire?","depth":3},{"value":"Example: Stripe","depth":4},{"value":"Example: Adyen","depth":4},{"value":"Conclusion about marketplace PCI DSS compliance","depth":3},{"value":"Communication between the marketplace app and payment gateway","depth":2},{"value":"API calls","depth":3},{"value":"Redirect URLs and Return URLs","depth":3},{"value":"","depth":1},{"value":"Example: PayPal redirect after seller onboarding","depth":4},{"value":"Webhooks","depth":3},{"value":"Example: PayPal onboarding","depth":4},{"value":"Backend endpoint to listen to webhook notifications","depth":4},{"value":"Integrating your Flex marketplace with a 3rd-party payment gateway","depth":2},{"value":"Using privileged transitions","depth":3},{"value":"","depth":1},{"value":"Using Events","depth":3},{"value":"","depth":1},{"value":"Integrating payment steps with your marketplace","depth":2},{"value":"Step 1: Provider onboarding","depth":3},{"value":"Step 2: Customer checkout","depth":3},{"value":"","depth":1},{"value":"Step 3: Provider accept","depth":3},{"value":"Step 4: Customer refund","depth":3},{"value":"Step 5: Provider payout","depth":3},{"value":"Summary","depth":2},{"value":"Further reading","depth":2}]}},"pageContext":{"slug":"how-to-integrate-3rd-party-payment-gateway","category":"how-to-payments"}},
    "staticQueryHashes": ["3794076007","439097193","717698143"]}