End-to-End API Example
Overview
In order to better understand how the Checkbook API works, and the various types of API requests you can make to the server, this page outlines a specific payment workflow from the user perspective using a tool such as Postman.
Note: This is by no maeans a complete example; however, this example should provide you with enough basic information so you can understand the Checkbook APIs simplicity and ease of use.
Send a payment using the Checkbook API
One of the most common use cases for customers who want to use the Checkbook API is to send a payment to a recipient. Although some users may prefer to use the dashboard UI to send a payment, many others may prefer to use the API to send payments, as this will enable you to create batch scripts and automate the check sending process without significant user interaction.
To send a payment using the Checkbook API, you will need to perform the following tasks:
- Add a bank account
- Send a payment using the Checkbook API
Add a bank account
Before you can send a payment to a recipient using the Checkbook API, you must first create an account with Checkbook and add your bank account details so Checkbook can facilitate the payment bwteen you and your recipient. To add a bank account:
-
Verify you have access to the Checkbook API. If you are unsure whether you can make API calls, contact Checkbook support, or your account representative.
-
Once you have verified you can make API calls to the server, using your preferred API tool (e.g. Postman), use the following URL syntax to create your request (note that this is a
POST
API request).
https://api.checkbook.io/v3/account/bank
In this request, note the following:
https://api.checkbook.io
is the base URL for your API requestv3
is the API versionaccount
is the service you are callingbank
is the resource you are calling
- In the body of your
POST
request, enter the following information:
account number
is your bank account numbername (optional)
is a short description of the accountrouting number
is the ABA routing number for your banktype of account
is the type of account you are using (checking, savings, business)
Sample Request
--url https://api.checkbook.io/v3/account/bank \
--header 'Authorization: 161496fa27ba66d8xy0619ac6f421bd9:b659b37771f1035c76c0b804c9082f47' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"type": "BUSINESS",
"account": "464009751",
"routing": "809733117"
}
'
Where:
type
is the type of accountaccount
is the account numberrouting
is the bank routing number
- Execute the request by sending the request to the Checkbook server.
Sample Response
{
"account": "0117",
"billing": false,
"date": "2023-12-18 20:04:07",
"default": false,
"id": "e012334fe21f430c9941fc9ab747a36c",
"name": null,
"routing": "322271724",
"status": "DEPOSIT_ONLY",
"type": "BUSINESS"
}
Where:
account
is the Checkbook account IDbilling
is the billing accountdate
is the date that the account was createddefault
is the default accountid
is the unique identifiername
is the name of the bank accountrouting
is the bank routing numberstatus
is the type of allowable transactionstype
is the type of account
Send a payment
Now that you have added a bank account that Checkbook can use to facilitate a payment, you can use the Checkbook API to send a payment to a recipient. Because there are several different types of payments you can send with Checkbook, you need to determine how you would like to disburse the payment to recipient. In this example, you will send a payment to a recipient via a physical check.
To send a physical check to a recipient, perform the steps listed below.
- Use the following URL syntax to create your request (note that this is a
POST
API request).
https://api.checkbook.io/v3/check/physical
Where:
https://api.checkbook.io
is the base URL for your API requestv3
is the API versioncheck
is the resource you are callingphysical
is the service you are calling
- In the body of your
POST
request, enter the following required information:
amount
is the amount of the paymentname
is the nama of the recipientrecipient details
is an object that contains detailed information about your recipient, including:city
is the city where the recipient residesaddress
is the physical address where the check should be sentstate
is the state where the recipient resideszip
is the 5-digit ZIP code for the city where the recipient resides
- Execute the request by sending the request to the Checkbook server.
Sample Request
--url https://sandbox.checkbook.io/v3/check/physical \
--header 'Authorization: 62bfe4e5551d487aa5fe6x448865a508:VBKyl17KbXDsaFiYUBmIzeiaIWwJl0' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"recipient": {
"city": "St. Louis",
"line_1": "155 Main Street",
"state": "MO",
"zip": "63101"
},
"amount": 225,
"name": "ABC Construction"
}
Sample Response
"amount": 225,
"date": "2023-12-20 07:16:55",
"description": null,
"id": "47813bed6240491abb30d8d22a094500",
"image_uri": "https://checkbook-checks-sandbox.s3.amazonaws.com/b1a7d6cb-b6f8-40c9-adbc-2989ce0b8837.png",
"name": "ABC Construction",
"number": 5003,
"recipient": {
"city": "St. Louis",
"country": "US",
"line_1": "155 Main Street",
"line_2": "",
"state": "MO",
"zip": "63101"
},
"remittance_advice": [],
"status": "IN_PROCESS"
}
Updated 9 months ago