This guide will step you through creating a basic workflow for a marketplace using Assembly’s escrow workflow.
Tools for testing the API
We recommend the following application to test our services with. The following guide will use these tools as an example, though you can use any other tools you are familiar with.
For testing API calls:
For testing callbacks:
The Assembly lingo
Before you create your first transaction with Assembly, there are a few terms that you should be familiar with:
- Buyers are users who pay for things on your platform.
- Sellers are users who receive money from your platform.
- Platform refers to you as a customer, or your marketplace.
- Items are records of a transaction between a buyer, a seller and the platform. These represent what the buyer is paying for, such as your product or service.
- Fees are applied to Items, and this is how you charge your buyers or sellers for using your platform.
Now that you’re familiar with the basics, let’s do some setup to make things easier later on.
- Create a prelive account if you haven’t already and then sign in.
- Locate your API key.
- Update your platform details.
Setting up your first transaction
- Add a bank account to the seller
- Set seller disbursement account
- Create a fee and set it to the seller
Creating your first transaction
Now that your platform is setup and you have all the pieces you need to create a transaction with Assembly, let’s get started.
To create a transaction between your Buyer and Seller, you will need to create an Item. To do this run the following:
- List users to find the ID of your buyer and seller. Note the user IDs.
- List fees to find the fee to assign to the transaction. Note the fee ID.
- Create an item and associate it with the user IDs and fee ID you just noted. For this example, set
payment_typeto "1" (escrow).
Now that you’ve got an Item created, you will want to take payment from the Buyer:
- Make payment. In the API response, the item assumes a payment_deposited state.
To check that payment was made on the Item from your Buyer:
- Show Item. In the API response, the item assumes a payment_deposited state.
When funds are sitting in an Item, they will remain here until you tell the funds where to go next.
This is where setting the Item’s
payment_type to escrow above comes in. There are a number of Item payment types which do different things, which we will explore in later guides, but for now we’ll stick with the Escrow payment type.
To move funds from the Item to the Seller, you have a couple of options:
- Release the funds to the Seller. You might want to do this in a marketplace where the platform is the only seller, or where products or services have been provided to buyers before the transaction is done.
- Get the Buyer to confirm that funds can be released to the Seller. You would want to do this in a marketplace where something of value is exchanging hands and you want the Buyer to verify that the goods or services have been provided before releasing payment to the Seller.
Once funds have been moved to the Seller, they will be released to the Seller’s bank account. To be notified when this has occurred, you can create a callback form the Item.
You’ve now completed your first transaction with Assembly, well done!
For further information on building out specific workflows with Assembly, our payment workflows page is a great starting point.