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 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

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
}
'

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"}
}
'

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)
            }
          }
          });
        }}
 />

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

$ 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 --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 --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 --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.

Create the subscription plan

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
> }
> '

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 }

Get a subscription purchase link

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

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 }

Listen to webhook events for:
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.