Skip to Content
GuidesMarketplacePayments

Marketplace Payments

In this guide, you’ll learn how to facilitate payments between marketplace users. Checkbook’s marketplace is an embedded product, which allows customers to facilitate transactions to, or on behalf of users and customers.

Before diving into the details of how the marketplace works, we want to cover a few key terms that we’ll refer to in the rest of this guide:

Marketplace owner: The primary Checkbook customer who sets up and manages the Marketplace (the one that logs in to the Checkbook dashboard)

Marketplace user: Entities (businesses or individuals) transacting within the Marketplace. Marketplace users do not login to the Checkbook dashboard, and typically correspond to users within your application.

Prerequisites

Grab an API key

For the next steps of this guide, you’ll need access to Checkbook API keys. More details on grabbing a set of API keys can be found in our quickstart guide.

Enable marketplace

The marketplace functionality is available to all users in the sandbox environment. If you don’t yet have a marketplace in production, please contact your account representative or support to have it enabled.

Account Setup

We will use the create user endpoint to create a marketplace user. This will create a marketplace user and provide us with a set of API credentials that we can use to interact on behalf of this user. A marketplace user can represent either an individual or a business.

Begin by creating the user, using the API credentials associated with the marketplace owner. The user_id parameter is a unique identifier for the user in your system:

curl --request POST \
  --url https://sandbox.checkbook.io/v3/user \
  --header 'Authorization: OWNER-PUBLISHABLE-KEY:OWNER-SECRET-KEY' \
  --header 'Content-Type: application/json' \
  --data '{
        "name": "Dunder Mifflin",
        "user_id": "dunder-mifflin@checkbook.io"
    }'

The response will give us the api credentials to access this user (our user on the marketplace)

{
	"id": "a40243e25fc749289edb196606d27327",
	"key": "USER-PUBLISHABLE-KEY",
	"secret": "USER-SECRET-KEY",
	"user_id": "dunder-mifflin@checkbook.io"
}

Creating a wallet for our marketplace user

We then switch to the newly created marketplace user’s keys and send a request to add a wallet. We’re going to use this wallet to hold funds on behalf of the marketplace user. Because wallets are native to the Checkbook system (unlike bank accounts which are external to the Checkbook system), transfers between wallets are instantaneous.

curl --request POST \
  --url https://sandbox.checkbook.io/v3/account/wallet \
  --header 'Authorization: DUNDERMIFFLIN-PUBLISHABLE-KEY:DUNDERMIFFLIN-SECRET-KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Dunder Mifflin Wallet" }'

This wallet will have it’s own account and routing number that we will use to fund it

Response:

{
  "date": "2024-03-15 22:21:18",
  "id": "efdbaaaa17b244abba084e6c2ccfc990",
  "name": "Dunder Mifflin Wallet",
  "numbers": {
    "ACH": {
      "account": "555230000",
      "routing": "021000021"
    },
    "RTP": {
      "account": "555230000",
      "routing": "021000021"
    },
    "WIRE": {
      "account": "555230000",
      "routing": "021000021"
    }
  }
}

Funding the wallet

Now that we’ve created the wallet, we need to add funds to the wallet so we can begin sending payments. To do this, you can send funds directly to the wallet via ACH, RTP or wire transfer. The routing/account numbers for each method may be different, so make sure to pay close attention to the numbers returned in the previous step.

Once funds are sent to the wallet, the balance will be automatically applied and the marketplace owner will receive email confirmation. The balance of the wallet can be queried using the GET /v3/account/wallet endpoint.

At this point, we have our marketplace user and have funded its wallet. We’re now ready to start facilitating payments to other users.

Create additional users

To facilitate payments within users on an app, it’s likely that we’ll need to create more users. Let’s assume we have a payroll app, and a customer (Dunder Mifflin) will be paying its employees and contractors. Checkbook will be used to facilitate the payments.

Start by creating additional users on the marketplace

curl --request POST \
  --url https://sandbox.checkbook.io/v3/user \
  --header 'Authorization: OWNER-PUBLISHABLE-KEY:OWNER-SECRET-KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"name": "Dwight Schrute",
	"user_id": "dmoney"
}'

In response, we will now get the credentials for this user

{
	"id": "780bac8394434b3b8277b9b041d1e77f",
	"key": "DWIGHT-PUBLISHABLE-KEY",
	"secret": "DWIGHT-SECRET-KEY",
	"user_id": "dmoney"
}

Add KYC information

curl --request PUT \
  --url https://sandbox.checkbook.io/v3/user \
  --header 'Authorization: DWIGHT-PUBLISHABLE-KEY:DWIGHT-SECRET-KEY' \
  --header 'Content-Type: application/json' \
  --data '{
        "user": {
            "dob": "1970-01-20"
        }
    }'

Send a payment

There are two different ways to send a payment within a marketplace.

Sending a payment between marketplace users is a white-labeled experience, and Checkbook does not send any notification messages to the recipient of the payment. In this example, a payroll payment between Dunder Mifflin and Dwight Schrute would fit this use case, as they are both onboarded as marketplace users.

We can also send payments to users outside of the marketplace. This might be useful if Dunder Mifflin is paying a contractor, and doesn’t have the banking information needed to onboard them into their payroll app. When sending a payment to an external user, the user’s email or phone number is used so that Checkbook can send a notification message to the recipient.

Marketplace user

For this payment between marketplace users, we will be sending a payroll payment between Dunder Mifflin and Dwight Schrute.

Sending the payment

In this step, we’ll be using Dunder Mifflin’s wallet as the source of funds for the transfer. This is a completely intra-marketplace money movement so no email notifications will go to the recipient.

curl --request POST \
  --url https://sandbox.checkbook.io/v3/check/digital \
  --header 'Authorization: DUNDERMIFFLIN-PUBLISHABLE-KEY:DUNDERMIFFLIN-SECRET-KEY' \
  --header 'Content-Type: application/json' \
  --data '{
        "name": "Dwight Schrute",
        "amount": 2000,
        "account": "efdbaaaa17b244abba084e6c2ccfc990",
        "recipient": "dmoney"
    }'

Now that the check is created we get the following response

{
	"amount": 20.0,
	"date": "2023-12-20 23:31:17",
	"description": null,
	"id": "c9d2dfa9c79143e8989a1f03a12dfdbc",
	"image_uri": "https://checkbook-checks-sandbox.s3.amazonaws.com/abcdefghi-dd8f-abcd-b15d-abcdefghi.png",
	"name": "Dwight Schrute",
	"number": 5001,
	"recipient": "dmoney",
	"remittance_advice": [],
	"status": "UNPAID"
}

Depositing the payment

In order for Dwight to receive the money, he needs a place for the funds to go. This could be a wallet, if the funds need to stay within the Checkbook platform, or it could be Dwight’s personal bank account. In this example, we’ll deposit the funds to Dwight’s bank account.

Add a bank account

We’ll need to pass in the routing and account number associated with Dwight’s bank account

curl --request POST \\
	--url https://sandbox.checkbook.io/v3/account/bank \\
	--header 'Authorization: DWIGHT-PUBLISHABLE-KEY:DWIGHT-SECRET-KEY' \\
	--header 'accept: application/json' \\
	--header 'content-type: application/json' \\
	--data '{
	  "account": "12345678",
	  "routing": "322271627",
	  "type": "SAVINGS"
	}'

Response:

{
  "account": "5678",
  "date": "string",
  "id": "efdbaaaa17b244abba084e6c2ccfc990",
  "routing": "322271627",
  "status": "DEPOSIT_ONLY",
  "type": "SAVINGS"
}
Deposit the payment

Next, we’ll use the ID returned in the previous step to deposit the payment

curl --request POST \
  --url https://sandbox.checkbook.io/v3/check/deposit/c9d2dfa9c79143e8989a1f03a12dfdbc \
  --header 'Authorization: DWIGHT-PUBLISHABLE-KEY:DWIGHT-SECRET-KEY' \
  --header 'Content-Type: application/json' \
  --data '{
        "account": "efdbaaaa17b244abba084e6c2ccfc990"
    }'

We will get a response about the payment

{
	"amount": 20.0,
	"date": "2023-12-20 23:31:17",
	"description": null,
	"id": "c9d2dfa9c79143e8989a1f03a12dfdbc",
	"image_uri": "https://checkbook-checks-sandbox.s3.amazonaws.com/abcdefghi-dd8f-abcd-b15d-abcdefghi.png",
	"name": "Dwight Schrute",
	"number": 5001,
	"recipient": "dmoney",
	"remittance_advice": [],
	"status": "PAID"
}

At this point, we now have moved money from Dunder Mifflin to Dwight Schrute.

External user

For this payment between a marketplace user and an external, we will be sending a contractor payment between Dunder Mifflin and Vance Refrigeration.

Sending the payment

We don’t have any information on this contractor, other than their name and contact info, so they will receive an email and be directed to the Checkbook recipient experience to complete the payment on their own.

curl --request POST \
  --url https://sandbox.checkbook.io/v3/check/digital \
  --header 'Authorization: DUNDERMIFFLIN-PUBLISHABLE-KEY:DUNDERMIFFLIN-SECRET-KEY' \
  --header 'Content-Type: application/json' \
  --data '{
        "name": "Vance Refrigeration",
        "amount": 2500,
        "account": "efdbaaaa17b244abba084e6c2ccfc990",
        "recipient": "vance@example.com"
    }'

As always, we get a response with information about the check

{
	"amount": 2500.0,
	"date": "2023-12-20 23:13:32",
	"description": null,
	"id": "10cb9c98d4ae479fb8aaed8073522dd4",
	"image_uri": "https://checkbook-checks-sandbox.s3.amazonaws.com/abcdefghi-e7ce-4e49-9af9-abcdefghji.png",
	"name": "Vance Refrigeration",
	"number": 5001,
	"recipient": "vance@example.com",
	"remittance_advice": [],
	"status": "UNPAID"
}

There’s no additional steps needed by the marketplace to process this payment. Vance Refrigeration will receive an email, and be instructed on how to receive the funds.

Last updated on