Powered by Coinflow
Payments · Documentation
⌘K
Operational

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

Resources

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
}
'
  1. 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"}
}
'
  1. 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 => {
            if (typeof event.data === 'string' ) {
              const data = JSON.parse(event.data);

            if (data.data === 'success') {
              console.log('payment id', data.info.paymentId)
            }
          }
          });
        }}
 />
  1. 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. 
    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"
}
'
    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"
}
'
    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"
}
'
    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 
    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
}
'
    {
  "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
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"
}
'
{
  "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"
}
  1. Listen to webhook events for:
  2. 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.