> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# How To: Implement Marketplaces (UI)

## Summary

Merchants can follow this guide to learn how to implement Coinflow's Marketplace so that end-users can make purchases from sellers, allow sellers to withdraw their earnings from profits, and the marketplace can view all activity happening on their own marketplace!

## Setup

* [**Register a marketplace account** on sandbox](https://sandbox-merchant.coinflow.cash/marketplace/register)
  > 🚧 Please reach out to the Coinflow team with your merchant id once you've completed this so we can configure your account for marketplaces!
* [Generate your API Keys](https://sandbox-merchant.coinflow.cash/marketplace/api-keys) from the marketplace dashboard.

## Resources

* [Demo of marketplaces](/guides/marketplaces/marketplace-overview#marketplaces-demo)
* Read about [how 3DS works.](/guides/checkout/payment-security-risk-management/fraud-protection/about-chargeback-protection)
* Read about [how to override chargeback protection decisions.](/guides/checkout/payment-security-risk-management/fraud-protection/overriding-chargeback-protection)
* Read about [how credit card payments work](/guides/checkout/payment-scenarios/authorize-capture) .
* Read about [credit card authorization, capture, and void.](https://blog.coinflow.cash/understanding-authorization-capture-and-void-9e582c265bb8)
* Read about [what countries Coinflow supports withdrawing directly to banks to.](/guides/payouts/payout-methods/available-countries)
  * Sellers in countries Coinflow doesn't yet support for direct-to-bank payouts can receive their earnings in USDC, a stablecoin pegged 1:1 to the US dollar. Contact the Coinflow team for details on the USDC withdrawal flow.

## Getting Started

1. [Create a seller registration link](/api-reference/api-reference/marketplace/get-seller-register-link)

* This will generate a link which sellers can use to register themselves as a seller under the marketplace.

```
curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/marketplace/link/seller/registration \
     --header 'Authorization: YOUR_API-KEY_HERE' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "sellerEmailAddress@email.com", // the seller email address
  "sellerId": "seller1", // the seller id on your platform
  "country": "us", // the seller's location
  "redirectUrl": "https://www.mywebsite.com/" // url to redirect the seller to upon registration completion
}
'
```

2. [Get a seller login link](/api-reference/api-reference/marketplace/get-seller-login-link)

* This will generate a link which sellers can use to login to their seller dashboard to view purchases, customers, withdraw their funds, view withdraw history.

```
curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/marketplace/link/seller/login \
     --header 'Authorization: YOUR_API-KEY_HERE' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "sellerEmailAddress@gmail.com" //you can optionally pass the seller id instead of email eg: {"sellerId": "seller1"}
}
'
```

3. [Get Checkout Link](/api-reference/api-reference/checkout/get-checkout-link)

* This will generate a link which end-users can interface with to make a one-time purchase from a seller.

```
curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/checkout/link \
     --header 'Authorization: YOUR_API_KEY_HERE' \
     --header 'x-coinflow-auth-user-id: customer123' \
     --header 'x-coinflow-submerchant-id: seller1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "subtotal": {
    "currency": "USD",
    "cents": 100
  },
  "webhookInfo": "{productId: 123abc, code: ABC123}", // Pass whatever webhook data here
  "chargebackProtectionData": [
    {
      "productType": "<GET_FROM_COINFLOW>", // Get this value from coinflow after filling out chargeback protection docs
      "productName": "cash gift",
      "quantity": 1,
      "rawProductData": { // Adjust based on what data you have available on the product being purchased. The more info you pass, the better chargeback decision outcome will be.
        "productDescription": "A cash gift that can be used at the seller discretion",
        "productCategory": "tipping services",
        "gift id": "123abc"
    },
  ],
  "email": "testCustomer@test.com",
  "deviceId": "12345ABCD" // Get this after adding chargeback script across site. For reference: /guides/checkout/payment-security-risk-management/fraud-protection/implement-chargeback-protection
}
'
```

> 👍 Want to trigger your own on success events?
>
> You can listen to success event messages and get the payment id or pass your own function
>
> ```
> <iframe
>         allow="payment"
>         src="COINFLOW_CHECKOUT_URL"
>         onLoad={() => {
>           window.addEventListener('message', event => {
>             // Use 'https://coinflow.cash' in production.
>             if (event.origin !== 'https://sandbox.coinflow.cash') return;
>             if (typeof event.data === 'string' ) {
>               const data = JSON.parse(event.data);
>
>             if (data.data === 'success') {
>               console.log('payment id', data.info.paymentId)
>             }
>           }
>           });
>         }}
>  />
> ```

4. [Share payer events with Coinflow](/guides/checkout/payment-security-risk-management/fraud-protection/sending-payer-events)\
   Sharing major events that a payer makes throughout their lifecycle on your website prior to them making a purchase will allow us to collect more information about them and improve your approval rates.

   **`SignUpEvent`**

   ```curl SignUpEvent
   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/events \
        --header 'Authorization: YOUR_API_KEY' \
        --header 'content-type: application/json' \
        --data '
   {
     "eventType": "SignUp",
     "customerId": "user-123-abc",
     "country": "US",
     "username": "therock72",
     "email": "dwaynejohnson@gmail.com",
     "firstName": "Dwayne",
     "lastName": "Johnson"
   }
   '
   ```

   **`SignInEvent`**

   ```curl SignInEvent
   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/events \
        --header 'Authorization: YOU_API_KEY' \
        --header 'content-type: application/json' \
        --data '
   {
     "eventType": "SignIn",
     "customerId": "user-123-abc",
     "country": "US",
     "email": "dwaynejohnson@gmail.com"
   }
   '
   ```

   **`SignInFailureEvent`**

   ```curl SignInFailureEvent
   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/events \
        --header 'Authorization: YOUR_API_KEY' \
        --header 'content-type: application/json' \
        --data '
   {
     "eventType": "SignInFailure",
     "customerId": "user-123-abc",
     "country": "US",
     "email": "dwaynejohnson@gmail.com",
     "failureReason": "Password Failed"
   }
   '
   ```

   **`BuyerChallengeEvent`**

   ```curl BuyerChallengeEvent
   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/events \
        --header 'Authorization: YOUR_API_KEY' \
        --header 'content-type: application/json' \
        --data '
   {
     "eventType": "BuyerChallenge",
     "type": "thirdPartyKyc",
     "status": "successfullyFulfilled",
     "customerId": "user-123-abc",
     "country": "US",
     "email": "dwaynejohnson@gmail.com"
   }
   '
   ```
   \


## How to add subscriptions

Note: Only reference this section if you are supporting subscription payments on your platform.

1. [Create the subscription plan](/api-reference/api-reference/merchant-subscription/create-plan)

   **`Request`**

   ```curl Request
   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/merchant/subscription/plans \
        --header 'Authorization: YOUR_API_KEY' \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --data '
   {
     "interval": "Monthly",
     "amount": {
       "currency": "USD",
       "cents": 500
     },
     "name": "seller_plan_1",
     "code": "seller-plan-code-1",
     "duration": 12,
     "description": "access to my sellers subscription",
     "settlementType": "USDC",
     "active": true
   }
   '
   ```
   ```json
   {
     "merchant": "66314a51a26b3cb28fab9bd0",
     "name": "seller_plan_1",
     "code": "seller-plan-code-1",
     "interval": "Monthly",
     "duration": 12,
     "amount": {
       "cents": 500,
       "currency": "USD"
     },
     "description": "access to my sellers subscription",
     "settlementType": "USDC",
     "active": true,
     "_id": "67ca09789fd576de1356c32c",
     "__v": 0,
     "id": "67ca09789fd576de1356c32c"
   }
   ```
2. [Get a subscription purchase link](/api-reference/api-reference/marketplace/get-subscribe-link)

**`Request`**

```curl Request
curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/marketplace/link/subscription \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "webhookInfo": {
    "example": "{\"subscriptionId\":\"12345\"}"
  },
  "chargebackProtectionData": [
    {
      "productType": "subscription",
      "rawProductData": {
        "example": "{\"description\": \"free form json to pass descriptive data about what the subscirption is\"}"
      },
      "productName": "basic subscription",
      "quantity": 1
    }
  ],
  "feePercentage": 5,
  "sellerId": "tylee99",
  "email": "buyer@gmail.com",
  "deviceId": "123456789",
  "supportEmail": "support@marketplace.com",
  "planCode": "seller-plan-code-1"
}
'
```

**`Response`**

```json Response
{
  "link": "https://sandbox-marketplace.coinflow.cash/checkout-wallet?sellerId=tylee99&appId=25631a24-e467-4500-aecb-197ffe9d7b04&email=buyer%40gmail.com&jwtToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoi456C4oKW26LXguCzgOOYguuAk-iCpsmg44aA4aK16ZGw4KOI6IGM0aPknIDjorPouJzMteq4gVx1ZDg3M-iAlueJgNqE45CA7rKwybDgp6DHgOCumuWIgOSQguGliOWMhOKdtuWXieKUreSMhuGRmumDp-KrlOiouOqRseKDiuWZtuyZheqqsuSdjuGIheK8ieqTpOikkeSTpOKgiuG7pOeDlOmzlOSirOmxqOS7pOCjpO6QseGgiuSThOmyjOiypu2SjuGjlOOQuOCgiO6GiFx1ZDgwOOiwmOOgiuagie2RieqzlOahqe6SruiynOGhjemRqOa3lNmY4KiI4ZCI5JOY5aOU6LGI7ZKR76q46pKI7o--6rKs64iY7K-e6JSI4Kqk5JOL76WE5qCK76iK7pKk6LOk7oej7Zm14KKs54KM5aC37Jek5JCn5rWh75CE4ryo6rCI6bKF7ZS654ix7JSF6ISy45WY7pCc44aR6KmB64qx7LGN4oi15IyL75CI4oOQ5KGI5Iqa6Ka16Kag6Ieb47qi5YuC55Sh4rGh4LykzIzpibTujrXkoLfltL7ijovgqqDoiIzpg5DpsIvGi96p57C65KKawonlgYHmhKzkkZ_ouI3gq4bgrqnpgIrjmL7snJjlnaHtlLhcdWRjZjboqZHoobHuloTjgbDmvLPgupThmpfkqrLloIbqpIngo4jkoaXmsp3kmJrhjIDolZnvtK3jvZ7oqIrmi5bhno3hqLjnmJjsv6HhgLTqgLDijYzOm-qSjO6FoOijoemqrumDmuyTiuWgmeeNkuO4ieGFpuiume-CnOKIkuGOiumYuO6FrOGCjuiWhO6cgeGmnVx1ZGFjYuSYl9qB5ZGW5JCe452A6qeP4oeT5Kei64GR2a_oqq3mqoXmhIvvo5nPnuORolx1ZDllMeypqeCwpuWYr-SZteKwsOmjkuObluu8jeeXqeKhpOWlvdyA5pm22ZDrmITjn4rhtYPogqPorJ7jh5LhhoDogrHmm4bioInoqJzjkpbrlYTkh5HinI3vg4rlpILol7nigrLjp4njoKjjoITmr6Dskbfqm4HcvuSCjOGJuu6gtOOniu6roMyN6reI7YG56LGK4YqY7IyO6K-i4qqB6bmJ4K6o47yi5I2x44GG4q-k2LjrgpDkrKrjkqfjj4HphZjjqpjhpoPui4_jqIjlirjhorHmnJlcdWRlY2LjharriIzqmKziibPqkKnhs6fkgrTgtLDqp4BcdWRjZjDpqIbsjYTCl8qD5aKT44SE4Yeo6LCB6Jmj75GZ4paO4qOo6rqU5LOi6pqn4oiL66Wq6b6V5paA5oG_46SG54-u6JSd4omA4YCgXHUwMDBi7pCAIiwibWVyY2hhbnRJZCI6InR5bGVlOTkiLCJpZGVtcG90ZW5jeUtleSI6IklLZGY5ODI2ZGQtZGQ3ZC00ZDg2LTg4MjMtMmFlMzI2N2VhY2U0IiwiaWF0IjoxNzQxMjkzNjU0LCJleHAiOjE3NDEzODAwNTR9.pQ3o6vnZN7nDyx9iIKc1m_xDpvYtJ5H9D0avyUijdrg&theme=N4IgDgTglgtghhAniAXCAxHAnADgKb4gA0IARnAMYDWA5hAPYCuAdgCaoYBsAzACwCsA4mUq0GLVgEEKFPMwAuHdADNlWPOuHlqdJm2myFAJiU4jvOBeHy8AD3kBhegBt6EJas-Lrdxy7cGcopoKqqspDg%2B9k6uENLyUPTMHl7eJADO8ojOeBzibHjsAL5AA&supportEmail=support%40marketplace.com&planCode=seller99_plan_1"
}
```

3. Listen to webhook events for:
   * [seller registration related webhook events](/guides/marketplaces/marketplaces-webhooks)
   * [checkout related webhook events](/guides/developer-resources/webhooks/checkout-webhooks#v3-event-types)
   * [subscription related webhooks events](/guides/developer-resources/webhooks/checkout-webhooks)
4. [Add Chargeback protection](/guides/checkout/payment-security-risk-management/fraud-protection/implement-chargeback-protection) on every page of your site!!
   * Note: It is a **requirement** to add this script to the head of **every page**, and not just where the payment occurs. After filling in the chargeback protection questionnaire, Coinflow will provider a partner id.