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!
Updated 2 months ago
See Also
✨ Marketplace Payouts Quickstart |
Verifying Card Details |
Test Card Numbers |
Post-Payments Processing |
✨ Send Funds Externally |
✨ Receive External Funds |
Wallets, Addresses and Transfers |