1. Create Marketplace & Seller Accounts

To simulate a marketplace scenario, let's configure both a marketplace operator as well as a seller on the marketplace. For that you will create two separate accounts on the developer sandbox.

Create a Marketplace Account

Go to the developer sandbox on my-sandbox.circle.com and signup for your marketplace account. If you use Gmail you can leverage the + trick for multiple aliases, for instance by signing up with email [email protected]. After you sign up, generate the API key for your marketplace and record it in a secure place.

Create a Seller Account

Log out of the developer sandbox and signup for a second account - your seller account. Once again, you can use Gmail's + trick, for instance by signing up with email [email protected]. After you sign up, generate the API key for your seller and record it in a secure place.

Convert Your Marketplace API Key

The API key you generated for your marketplace has to be converted into a proper Marketplaces API key. Right now we're processing those conversions manually, so please email [email protected] with the following content:

Please configure my sandbox marketplace.

Marketplace account email address: {marketplace email}
Seller account email address: {seller email}

We will configure your marketplace account and API key with the proper privileges, and associate your seller account to the marketplace in order to simulate a multi-sided scenario.

2. Retrieve the list of sellers on your marketplace

Once you received a response from us confirming the configuration of your marketplace API key, you can use the get merchants endpoint to retrieve the list of sellers on your marketplace. You will need this information for the payment step. Execute the command below to retrieve the list of sellers.

# Replace ${MARKETPLACE_API_KEY} with the Marketplace API key obtained on step 1
curl -H 'Accept: application/json' \
  -H "Authorization: Bearer ${MARKETPLACE_API_KEY}" \
  -X GET --url https://api-sandbox.circle.com/v1/marketplace/merchants

You will receive a response such as the following.

{
  "data":[
    {
      "id":"f8db971c-0b4d-46c4-81b9-93bee0a352a2",
      "marketplaceId":"87b62dac-9ba9-47dc-8776-505b8c2fbc94",
      "merchantId":"b29e4c1b-c999-4cf5-acdb-ab0c08fdba4b",
      "merchantWalletId":"1000002545",
      "createDate":"2020-03-05T20:54:16.650Z"
    }
  ]
}

The marketplaceId attribute uniquely identifies your marketplace. The merchantId attribute uniquely identifies a seller within your marketplace, and the merchantWalletId identifies a wallet for that seller.

You will need this data when processing a marketplace payment so you can instruct the Marketplaces API on how to process settlement (i.e. which seller should receive the proceeds from a payment). You will also use this data if you want to perform other transfers across the sellers on your marketplace.

3. Install the sample application

We have built a sample web application to demonstrate the use of various Circle APIs. You can clone the Github repository, configure the app and run it locally.

📘

If you don't already, make sure you have npm and yarn installed.

# Clone the sample app Github repository
git clone https://github.com/circlefin/payments-sample-app.git

# Change into sample app folder
cd payments-sample-app

# Create a .env file and configure the base url for api calls
echo BASE_URL=https://api-sandbox.circle.com > .env

# Install the dependencies
yarn install

# Run the sample app locally
yarn dev

📘

Take the marketplace API key you generated on step 1, and enter it on the settings tab on the top right corner of the sample application.

Switch on the I am using a Circle Marketplaces API key option.

4. Accept your first marketplace card payment

Marketplace payments work in a slightly different way from traditional payments. A marketplace card payment always involves (1) a buyer or an end user and (2) a seller. Card details on a marketplace are kept at the marketplace level, and thus shared across all sellers. This is so buyers don't need to input their payment details every time they use a different seller on your marketplace.

The marketplace card payment will then traverse across the buyer / end user wallet through to the seller wallet. That is why you will need to identify both the buyer / end user and the seller on a payment transaction.

On the sample application, click on the Charge Flow button under the Example UI implementation section.

You will see the fields Merchant Id, Merchant Wallet and End User Wallet at the top of the form. Fill out Merchant Id with the merchantId property you obtained on step 2. Fill out Merchant Wallet with the merchantWalletId property you obtained on step 2.

For the End User Wallet field, we'll create a brand new wallet that represents your buyer. You can create new wallets using the create wallet endpoint on the Digital Dollar Accounts API. Use the command below (you will have to create your own idempotency key).

# Replace ${MARKETPLACE_API_KEY} with the Marketplace API key obtained on step 1
curl -H 'Content-type: application/json' \
  -H "Authorization: Bearer ${MARKETPLACE_API_KEY}" \
  -X POST https://api-sandbox.circle.com/v1/wallets \
  --data '{"idempotencyKey": "4ddef365-f2fc-4a56-95f5-a214c84ba8f4"}'

You should receive a response like the one below.

{
  "data":{
    "walletId":"1000005062",
    "entityId":"7cbdedb1-d526-46b4-af12-4162a002eb9c",
    "type":"end_user_wallet"
  }
}

Use the walletId value obtained on the API call for the End User Wallet field.

Use one of the test card numbers available on the sandbox environment. For example, 4007400000000007.

Type in an amount, pick a value for CVV and expiry date, and add some billing information details.

Submit the marketplace payment creation request by clicking on the Make Payment button.

🎉 Congrats, you processed your first card payment that settles in USDC! You should see a payment identifier on the resulting screen, something like Payment id: 81855279-b53d-4119-9f1e-5d0af00f0c24.

5. Check the status of your card payment

Now make an API call to retrieve the status of your marketplace card payment. Use your API key from step 1 and the payment identifier you obtained on step 3.

# Replace ${MARKETPLACE_API_KEY} with the Marketplace API key obtained on step 1
# Replace ${PAYMENT_ID} with the payment id obtained on step 4
curl -H 'Accept: application/json' \
  -H "Authorization: Bearer ${MARKETPLACE_API_KEY}" \
  -X GET --url https://api-sandbox.circle.com/v1/marketplace/payments/${PAYMENT_ID}

You should receive a response such as:

{
  "data": {
    "id": "81855279-b53d-4119-9f1e-5d0af00f0c24",
    "type": "payment",
    "merchantId": "ff71551d-ae18-492d-baf1-d9205e20e0bf",
    "merchantWalletId": "1000002584",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "source": {
      "id": "1fa990d9-fd12-400c-bc7d-e54a428f7570",
      "type": "card"
    },
    "description": "Payment",
    "createDate": 1583830582515,
    "trackingRef": "20674453824672941243272",
    "status": "confirmed",
    "fees": {
      "amount": "0.10",
      "currency": "USD"
    }
  }
}

🎉 You are all done!

Your payment will eventually change its status from confirmed to paid - at that point you have funds in your account available for use.

6. Like what you see? Keep going!

By accepting a marketplace card payment that settles in USDC, you have just touched the tip of the iceberg of Circle APIs.

Check how to subscribe to notifications on changes in payments status. Also make sure you check the rest of the documentation - a few starting points are suggested below.

7. Ready for the next step?

If you are in advanced stages of experimenting with our APIs and want to plan moving to production, please start by applying for a Circle Account and subsequently reach out to sales. We'll be happy to walk you through to the next steps.

We can't wait to see what you are going to build!