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

  🚧 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 from the marketplace dashboard.

Resources

• Demo of marketplaces
• Read about how 3DS works.
• Read about how to override chargeback protection decisions.
• Read about how credit card payments work .
• Read about credit card authorization, capture, and void.
• Read about what countries Coinflow supports withdrawing directly to banks to.
  • Sellers who reside in countries that are not supported by Coinflow’s direct bank offramps, can offramp in USDC. Read more about what countries can offramp in USDC and learn how you can direct sellers to withdraw their USDC.

Getting Started

1. Create a seller registration 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
}
'

3. Get a 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"}
}
'

4. Get a purchase 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/marketplace/link/purchase \
     --header 'Authorization: YOUR_API-KEY_HERE' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "subtotal": {
    "cents": 100
  },
  "feePercentage": 5, // marketplace fee you will take from each purchase
  "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"
    },
  ],
  "sellerId": "seller1",
  "email": "testCustomer@test.com",
  "deviceId": "12345ABCD" // Get this after adding chargeback script across site. For reference: https://docs.coinflow.cash/docs/implementing-chargeback-protection#how-to-add-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 => {
            if (typeof event.data === 'string' ) {
              const data = JSON.parse(event.data);
            
            if (data.data === 'success') {
              console.log('payment id', data.info.paymentId)
            }
          }
          });
        }}
 />

5. Share payer events with Coinflow
   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

   1
   curl --request POST \
   2
        --url https://api-sandbox.coinflow.cash/api/events \
   3
        --header 'Authorization: YOUR_API_KEY' \
   4
        --header 'content-type: application/json' \
   5
        --data '
   6
   {
   7
     "eventType": "SignUp",
   8
     "customerId": "user-123-abc",
   9
     "country": "US",
   10
     "username": "therock72",
   11
     "email": "dwaynejohnson@gmail.com",
   12
     "firstName": "Dwayne",
   13
     "lastName": "Johnson"
   14
   }
   15
   '

   SignInEvent

   1
   curl --request POST \
   2
        --url https://api-sandbox.coinflow.cash/api/events \
   3
        --header 'Authorization: YOU_API_KEY' \
   4
        --header 'content-type: application/json' \
   5
        --data '
   6
   {
   7
     "eventType": "SignIn",
   8
     "customerId": "user-123-abc",
   9
     "country": "US",
   10
     "email": "dwaynejohnson@gmail.com"
   11
   }
   12
   '

   SignInFailureEvent

   1
   curl --request POST \
   2
        --url https://api-sandbox.coinflow.cash/api/events \
   3
        --header 'Authorization: YOUR_API_KEY' \
   4
        --header 'content-type: application/json' \
   5
        --data '
   6
   {
   7
     "eventType": "SignInFailure",
   8
     "customerId": "user-123-abc",
   9
     "country": "US",
   10
     "email": "dwaynejohnson@gmail.com",
   11
     "failureReason": "Password Failed"
   12
   }
   13
   '

   BuyerChallengeEvent

   1
   curl --request POST \
   2
        --url https://api-sandbox.coinflow.cash/api/events \
   3
        --header 'Authorization: YOUR_API_KEY' \
   4
        --header 'content-type: application/json' \
   5
        --data '
   6
   {
   7
     "eventType": "BuyerChallenge",
   8
     "type": "thirdPartyKyc",
   9
     "status": "successfullyFulfilled",
   10
     "customerId": "user-123-abc",
   11
     "country": "US",
   12
     "email": "dwaynejohnson@gmail.com"
   13
   }
   14
   '

   
   

How to add subscriptions

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

1. Create the subscription plan
   Request

   1
   curl --request POST \
   2
        --url https://api-sandbox.coinflow.cash/api/merchant/subscription/plans \
   3
        --header 'Authorization: YOUR_API_KEY' \
   4
        --header 'accept: application/json' \
   5
        --header 'content-type: application/json' \
   6
        --data '
   7
   {
   8
     "interval": "Monthly",
   9
     "amount": {
   10
       "currency": "USD",
   11
       "cents": 500
   12
     },
   13
     "name": "seller_plan_1",
   14
     "code": "seller-plan-code-1",
   15
     "duration": 12,
   16
     "description": "access to my sellers subscription",
   17
     "settlementType": "USDC",
   18
     "active": true
   19
   }
   20
   '

   1
   {
   2
     "merchant": "66314a51a26b3cb28fab9bd0",
   3
     "name": "seller_plan_1",
   4
     "code": "seller-plan-code-1",
   5
     "interval": "Monthly",
   6
     "duration": 12,
   7
     "amount": {
   8
       "cents": 500,
   9
       "currency": "USD"
   10
     },
   11
     "description": "access to my sellers subscription",
   12
     "settlementType": "USDC",
   13
     "active": true,
   14
     "_id": "67ca09789fd576de1356c32c",
   15
     "__v": 0,
   16
     "id": "67ca09789fd576de1356c32c"
   17
   }
2. Get a subscription purchase link

1
curl --request POST \
2
     --url https://api-sandbox.coinflow.cash/api/marketplace/link/subscription \
3
     --header 'Authorization: YOUR_API_KEY' \
4
     --header 'accept: application/json' \
5
     --header 'content-type: application/json' \
6
     --data '
7
{
8
  "webhookInfo": {
9
    "example": "{\"subscriptionId\":\"12345\"}"
10
  },
11
  "chargebackProtectionData": [
12
    {
13
      "productType": "subscription",
14
      "rawProductData": {
15
        "example": "{\"description\": \"free form json to pass descriptive data about what the subscirption is\"}"
16
      },
17
      "productName": "basic subscription",
18
      "quantity": 1
19
    }
20
  ],
21
  "feePercentage": 5,
22
  "sellerId": "tylee99",
23
  "email": "buyer@gmail.com",
24
  "deviceId": "123456789",
25
  "supportEmail": "support@marketplace.com",
26
  "planCode": "seller-plan-code-1"
27
}
28
'

1
{
2
  "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
}

3. Listen to webhook events for:
   • seller registration related webhook events
   • checkout related webhook events
   • subscription related webhooks events
4. Add 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.