For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
RegisterLoginSandbox Login
GuidesRecipesAPI Reference
GuidesRecipesAPI Reference
  • Getting Started
    • Getting Started with Checkout
    • ACH Checkout
    • Card Checkout with Credits
    • Card Checkout
    • Direct USDC Settlement
    • Fiat/Crypto Pay-ins
    • Secure Marketplace Checkout
    • EVM Checkout
    • How to Enable Checkout with Credit Cards
    • Quick Start Marketplace Implementation
    • Payouts
    • Common FAQs
  • Checkout
    • Settlement Locations
    • Checkout Webhooks
  • Payouts
    • Payout Overview
    • What is a Payout
  • Subscriptions
    • Subscriptions Overview
  • Marketplaces
    • Marketplace Overview
    • How Marketplaces Work
    • How to Withdraw USDC
    • Countries Eligible for USDC Withdraw
    • Marketplaces Webhooks
    • Marketplaces Implementation
  • Developer Resources
    • Custom Branding
    • Checkout Implementation
    • Webhooks
  • Merchant Dashboard
    • Login & Account Access
    • Users and Roles
    • Rate Limits
    • Developer Contact
LogoLogo
RegisterLoginSandbox Login
On this page
  • Summary
  • Setup
  • Resources
  • Getting Started
  • How to add subscriptions
Getting Started

Marketplace Implementation

Was this page helpful?
Previous

Payouts Templates

Next
Built with

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
}
'
  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 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: /guides/checkout/payment-security-risk-management/fraud-protection/implement-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)
}
}
});
}}
/>
  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.
    SignUpEvent
    1curl --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
    1curl --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
    1curl --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
    1curl --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
    1curl --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
Request
1curl --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'
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}
  1. Listen to webhook events for:
    • seller registration related webhook events
    • checkout related webhook events
    • subscription related webhooks events
  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.