Bento for Business API

Learn the basics of the Bento for Business API, from authentication to available resources.

Base API URLs

Every Bento API call starts with the base API URL
- For production, the base URL is https://api.bentoforbusiness.com.
- For sandbox, the base URL is https://api.sandbox.bentoforbusiness.com.

Authentication

API Key (Bearer)
- Parameter Name: Authorization, in: header.

How to use

Every API call must have the proper HTTP authorization header token in order to be authenticated. You will be provided with an API access key and secret key that you can use to retrieve an authorization token. The authorization token is timed and will expire, so we recommend retrieving an authorization token prior to each session.

To retrieve an authorization token, perform the following request:

Retrieve Authorization Token

POST https://{Base API URL}/sessions
{
    "accessKey":"<your access key>",
    "secretKey":"<your secret key>"
}

In the API response to this request, there will be an "authorization" HTTP header with a value. This value is your authorization token that you should use to make subsequent authenticated API requests.

To make an authenticated API call, specify an HTTP "authorization" header with the value you retrieved from the POST to /sessions. This should be specified as a part of every authenticated API request.

Guides

Getting Started

Three simple steps to start using our api.

Get setup
- Signup for a free Bento for Business account.
- Contact api-support@bentoforbusiness.com to enable API Access and be provided with an Access Key and Secret Key.
Explore
- Use our API documentation to see what each endpoint does and try out a few requests.
Integrate
- Use our guides to learn how our system works and how to get started quickly.

Creating a Virtual Card

Creating virtual cards is easy with the Bento API. This guide provides an overview of the essential parts on how to get started with creating and using Bento virtual cards. For more information on this and other capabilities that the Bento API offers, please refer to the full API docs.

Types of Cards

There are two types of virtual cards you can create with Bento. Similar to physical cards, you can create a virtual "employee card" or a virtual "utility card". An employee card is designed for an individual employee, who will have the ability to login to the Bento mobile app. As such, creating an employee card will require more information such as date of birth and an unique email address. On the other hand, an utility card is not associated with any login, and thus will only require a name to create. The name on the card (alias) can be anything you want, such as “Tom Perry” or “Gas Card”.

Please note that you can customize the card billing address for any Bento card, whether it is physical or virtual, and for both employee as well as utility cards.

To create a virtual card, perform the following:

1. Create a virtual card

Make an API call to:

Create Card

POST https://{Base API URL}/cards

Sample request payload for creating a virtual utility card (without any custom spend limit restrictions):

{
   "type":"CategoryCard",
   "spendingLimit":{
      "period":"Month"
   },
   "allowedCategories":[],
   "allowedDays":[
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY",
      "THURSDAY",
      "FRIDAY",
      "SATURDAY",
      "SUNDAY"
   ],
   "allowedCategoriesActive":false,
   "alias":"Test Card",
   "virtualCard":true
}

Sample response:

The API response will be the created Card Object. Please note the "cardId" field. This is the Bento card ID that you will need this to retrieve its card number as well as to activate and customize its billing address.

2. Poll the card status until it is processed

Once a card is created, Bento will process the card creation within minutes asynchronously. Simply make the following API call (“Get Card By ID”) and wait till the lifecycleStatus attribute changes from NOT_ISSUED_YET to ACTIVATED. Your card will be activated and is ready to be used immediately.

Get Card By ID

GET https://{Base API URL}/cards/{cardId}

3. Retrieve the card number, cvv, and expiration date

Once the card has been created and processed (lifecycleStatus changes to ACTIVATED), you can retrieve its card number, cvv, and expiration date.

To retrieve a card’s expiration date, make an API call to Get Card By ID as outlined in the prior step. Please note the “expiration” field in the API response in MMYY format.

To retrieve a card’s full card number and cvv, make an API call to Get Card Number:

Get Card Number

Once the card is activated, the card can be used to make a purchase.

GET https://{Base API URL}/cards/{cardId}/pan

4. Change the card billing address (Optional)

You can optionally change the billing address that is associated with each card. If you do not change a card’s billing address, the card will use the mailing address associated with your Bento account as its billing address. This is the address that will be used for address verification when you make a purchase with this card. The address must be a US-based address.

Please note: it may take up to 5 minutes for the card billing address to take effect once you change it in the API. Please give it sufficient time after it is set before attempting to make purchases with the billing address you have set. Otherwise, your purchase may decline due to address mismatch.

To change the billing address for a card, perform the following:

Create Card Billing Address

POST https://{Base API URL}/cards/{cardId}/billingaddress

{
    "street":"123 Market Street",
    "addressAdditionals":"Suite 123",
    "city":"San Francisco",
    "state":"CA",
    "zipCode":"12345"
}

After the billing address is set, you can also modify it by making a PUT request to https://{Base API URL}/cards/{cardId}/billingaddress using the same payload structure as described above.

Change Spending Limits

The Spending Limit Object provides users the ability to set spending controls in real-time; including but not limited to:

Daily
Weekly
Monthly
Custom

Daily, Weekly, Monthly

You can add a card that has a daily, weekly, or monthly spending limit. The card's available balance will be reset to the spending limit amount when the current spending limit period expires.

For example, to set a Weekly spending limit, use the following values to set the Spending Limit Object:

{
  "active": true,
  "amount": 123.45,
  "period": "Day"
}

Custom

Custom period provides the ability to control the start and end date, for up to two years into the future. The card will automatically be turned off once it reaches its customEndDate.

customStartDate must start at a present or future date.
customEndDate is limited for up to two years into the future.

The date must be formatted in milliseconds since UNIX epoch (milliseconds since Jan 1, 1970).

For example, to set a Custom spending limit type, use the following values to set the Spending Limit Object:

{
  "active": true,
  "amount": 123.45,
  "period": "Custom",
  "customStartDate": 1495759408000,
  "customEndDate": 1495759408000
}

Using Webhooks

Bento sends webhook events to notify your application any time an event happens on your account, such as when a Card Transaction has completed or declined. Unlike the API, webhook events are initiated by Bento and pushed to your server. This mechanism is useful for services that need to know the most current state of their transactions.

You can use webhooks to handle any business logic, like:

Creating an accounting entry when a transaction has settled.
Updating a record in your database regarding recent activity in the account.
Notifying an employee when a transaction declined.
Integrating an employee to your HR Software to automatically create, delete, and pull expenses.

This functionality is currently in-development. If you wish to register your interest to our webhook beta, please contact our api support at api-support@bentoforbusiness.com.

Webhook Payload

Every webhook event will be wrapped with metadata about the subscription. When events are retried, it will reuse the same webhookEventId. All webhooks will follow this WebhookEvent Schema.

{
    "webhookEventId": "b1372d6c-917b-4993-b768-96283c7e4ca1",
    "webhookSubscriptionId": "c0536d89-b700-4f11-bd3a-c5e5a895a2b4",
    "topic": "", -- topic name (e.g. transaction)
    "data": {
        -- topic data
    }

Topics

transaction

data object contains Card Transaction Schema

Any element, including the deleted flag, has potential to be updated. Once a transaction's status is COMPLETE, it has completely posted to the account. When the transaction is in PENDING, the payee information and amount can be subject to change.

{
    "webhookEventId": "b1372d6c-917b-4993-b768-96283c7e4ca1",
    "webhookSubscriptionId": "c0536d89-b700-4f11-bd3a-c5e5a895a2b4",
    "topic": "transaction",
    "data": {
        "cardTransactionId": 123456,
        "business": {
            "businessId": 123456
        },
        "card": {
            "cardId": 123456,
            "alias": "Office 12345"
        },
        "amount": -123.45,
        "originalAmount": -123.45,
        "transactionDate": 1234567890123,
        "settlementDate": 1234567890123,
        "availableBalance": 123456.57,
        "ledgerBalance": 0.0,
        "fees": 0.0,
        "payee": {
            "name": "Internet Bill",
            "address": " ",
            "city": "Amzn.com/bill",
            "state": "WA",
            "country": "USA",
            "zip": ""
        },
        "tags": [
            {
                "cardTransactionTagId": 123456,
                "name": "hosting-tags",
                "bentoType": "com.bentoforbusiness.entity.card.CardTransactionTag"
            }
        ],
        "receipts": [
            {
                "cardTransactionReceiptId": 123456,
                "business": {
                    "businessId": 123456
                },
                "name": "123456-016e-4bd8-a4c5-123456123456.pdf",
                "url": "/api/transactions/receipts/123456/download",
                "urlExpiresOn": 1234567890123,
                "bentoType": "com.bentoforbusiness.entity.card.CardTransactionReceipt"
            }
        ],
        "note": "",
        "category": {
            "transactionCategoryId": 11,
            "name": "Retail and Miscellaneous Stores",
            "type": "SPENDING",
            "group": "Retail & Goods",
            "description": "Clothing, Variety, Sporting Goods, etc.",
            "mccs": [],
            "bentoType": "com.bentoforbusiness.entity.card.TransactionCategory"
        },
        "type": "CREDIT",
        "status": "COMPLETE",
        "deleted": false,
        "currency": "USD",
        "originalCurrency": "USD",
        "bentoType": "com.bentoforbusiness.entity.card.CardTransaction"
    }
}

Getting Started

Your registered endpoint must be an HTTPS address with a valid SSL certificate. Please refer to Node.js TLS/SSL documentation for accepted security settings.
Webhook will attempt to HTTP POST at the registered URL and the server is expecting a 200 response code with no content. All other response codes, including 3XX HTTP redirection codes, will be considered an error response and result in the system attempting to retry.
Events will be retried for up to four times in 10 second intervals. Webhooks with consecutive failures may result in the endpoint being deleted.

Create a webhook subscription

Request: curl --request POST \ --url https://OUR_API_DOMAIN/webhooks \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ \ "url":"YOUR_HTTPS_WEBHOOK_URL", \ "topic": "transaction" \ }'

Response: { "webhookSubscriptionId": "1a8552b6-dcec-48bb-aa45-584a50c6fc48", "business": { "businessId": 123 }, "url": "YOUR_HTTPS_WEBHOOK_URL", "topic": "TRANSACTIONS" }

Best Practices

Call our API directly to check time sensitive information, like card balances.
The ordering of webhook messages is not guaranteed.

Connecting your API Key to Multiple Bento Businesses

If you need access to multiple different businesses, please contact our api support at api-support@bentoforbusiness.com. We are able to set it up so that a single accessKey and secretKey can give you access to multiple businesses.

Once your keys are set up in this way, there is an important change to be aware of that applies to all authenticated API calls other than /businesses/me. For such calls (for example, let's consider cards), the result sets of a given call will only ever be for one business at a time. In order to differentiate between the two or more businesses you have access to, we recommend that you prepend these requests with /businesses/{businessId}. So, for example, if you have access to two businesses with ids 123 and 456 and would like to list the cards under these accounts, your requests would look be the following two urls:

https://{Base API URL}/businesses/123/cards/
https://{Base API URL}/businesses/456/cards/

Note that if you do not send the /businesses/{businessId} portion of the request, we will still give back a response, however, we will have to assume one of your businessIds. There is no supported way at this time to get a single response that co-mingles the data from two or more businesses.

If you are unsure of your businessIds, you can see the Businesses section below. In summary, the response from /businesses/me includes the ids, names, and other information of all businesses that you have access to.

Resources

Session

Creates a session

# You can also use wget
curl -X POST https://api.bentoforbusiness.com/sessions \
  -H 'Content-Type: application/json'

POST /sessions

Generates a Bearer token that must be passed through any authenticated routes. This is valid for one hour and must be renewed to prevent 401 - Unauthorized errors.

{
  "accessKey": "string",
  "secretKey": "string"
}

Parameter	In	Type	Required	Description
body	body	object	true	No description
accessKey	body	string	false	No description
secretKey	body	string	false	No description

Status	Meaning	Description	Schema
200	OK	OK	ApiApplication

Business

Current business registered to API Application

Get current business

# You can also use wget
curl -X GET https://api.bentoforbusiness.com/businesses/me \
  -H 'Authorization: Bearer {access_token}'

GET /businesses/me

Retrieves the details of the current business.

Responses

Status	Meaning	Description	Schema
200	OK	OK	BusinessesResponse

Cards

Cards attached to the current business

List all cards

# You can also use wget
curl -X GET https://api.bentoforbusiness.com/cards?index=0&limit=0 \
  -H 'Authorization: Bearer {access_token}'

GET /cards

Returns a server-side page of cards from the current business.

Parameters

Parameter	In	Type	Required	Description
index	query	integer	true	Offset of the cards from which to begin the query
limit	query	integer	true	Total number of cards to return in the current "page".
cardName	query	string	false	Name of card (alias) to search for.
orderBy	query	string	false	Card attribute by which query should be ordered (defaults to cardId)
order	query	string	false	Ascending or descending order (defaults to asc)

Enumerated Values

Parameter	Value
orderBy	cardId
orderBy	alias
orderBy	updatedOn
orderBy	createdOn
orderBy	availableAmount
orderBy	status
orderBy	type
orderBy	lifecycleStatus
order	asc
order	desc

Responses

Status	Meaning	Description	Schema
200	OK	OK	CardPage

Create a new card

# You can also use wget
curl -X POST https://api.bentoforbusiness.com/cards \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'

POST /cards

Creates a new card object

{
  "cardId": 12345,
  "type": "CategoryCard",
  "lifecycleStatus": "ACTIVATED",
  "status": "TURNED_ON",
  "expiration": "1221",
  "lastFour": "1234",
  "virtualCard": false,
  "alias": "My Card",
  "availableAmount": 123.45,
  "allowedDays": [
    "MONDAY"
  ],
  "allowedDaysActive": true,
  "allowedCategoriesActive": true,
  "allowedCategories": [
    {
      "transactionCategoryId": 10
    }
  ],
  "createdOn": 1491751408000,
  "updatedOn": 1491751408000,
  "spendingLimit": {
    "active": true,
    "amount": 123.45,
    "period": "Day",
    "customStartDate": 1491751408000,
    "customEndDate": 1491751408000
  },
  "user": {
    "firstName": "John",
    "lastName": "Smith",
    "birthDate": 1491751408000,
    "email": "me@myemail.com",
    "phone": "9998887654",
    "userId": 12345,
    "deleted": false,
    "created": 1491751408000
  }
}

Parameters

Parameter	In	Type	Required	Description
body	body	Card	true	The Card object to created

Responses

Status	Meaning	Description	Schema
200	OK	OK	Card

Retrieve a card

# You can also use wget
curl -X GET https://api.bentoforbusiness.com/cards/{cardId} \
  -H 'Authorization: Bearer {access_token}'

GET /cards/{cardId}

Retrieves the details of an existing card.

Parameters

Parameter	In	Type	Required	Description
cardId	path	integer(int64)	true	The Id of the card

Responses

Status	Meaning	Description	Schema
200	OK	OK	Card

Update a card

# You can also use wget
curl -X PUT https://api.bentoforbusiness.com/cards/{cardId} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'

PUT /cards/{cardId}

Updates the specified card by setting the value of the parameters passed. This request accepts the same arguments as the card creation and get card calls.

{
  "cardId": 12345,
  "type": "CategoryCard",
  "lifecycleStatus": "ACTIVATED",
  "status": "TURNED_ON",
  "expiration": "1221",
  "lastFour": "1234",
  "virtualCard": false,
  "alias": "My Card",
  "availableAmount": 123.45,
  "allowedDays": [
    "MONDAY"
  ],
  "allowedDaysActive": true,
  "allowedCategoriesActive": true,
  "allowedCategories": [
    {
      "transactionCategoryId": 10
    }
  ],
  "createdOn": 1491751408000,
  "updatedOn": 1491751408000,
  "spendingLimit": {
    "active": true,
    "amount": 123.45,
    "period": "Day",
    "customStartDate": 1491751408000,
    "customEndDate": 1491751408000
  },
  "user": {
    "firstName": "John",
    "lastName": "Smith",
    "birthDate": 1491751408000,
    "email": "me@myemail.com",
    "phone": "9998887654",
    "userId": 12345,
    "deleted": false,
    "created": 1491751408000
  }
}

Parameters

Parameter	In	Type	Required	Description
cardId	path	integer(int64)	true	The Id of the card
body	body	Card	true	the card object to update

Responses

Status	Meaning	Description	Schema
200	OK	OK	Card

Delete a card

# You can also use wget
curl -X DELETE https://api.bentoforbusiness.com/cards/{cardId} \
  -H 'Authorization: Bearer {access_token}'

DELETE /cards/{cardId}

Permanently deletes the specified card from our system and card can no longer be used. It cannot be undone.

Parameters

Parameter	In	Type	Required	Description
cardId	path	integer(int64)	true	The Id of the card

Responses

Status	Meaning	Description	Schema
200	OK	OK	Card

Activate a card

# You can also use wget
curl -X POST https://api.bentoforbusiness.com/cards/{cardId}/activation \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'

POST /cards/{cardId}/activation

Activates the specified card. Physical cards can not be used until it is activated with last four. Virtual cards are automatically activated upon creation.

{
  "cardId": 12345,
  "type": "CategoryCard",
  "lifecycleStatus": "ACTIVATED",
  "status": "TURNED_ON",
  "expiration": "1221",
  "lastFour": "1234",
  "virtualCard": false,
  "alias": "My Card",
  "availableAmount": 123.45,
  "allowedDays": [
    "MONDAY"
  ],
  "allowedDaysActive": true,
  "allowedCategoriesActive": true,
  "allowedCategories": [
    {
      "transactionCategoryId": 10
    }
  ],
  "createdOn": 1491751408000,
  "updatedOn": 1491751408000,
  "spendingLimit": {
    "active": true,
    "amount": 123.45,
    "period": "Day",
    "customStartDate": 1491751408000,
    "customEndDate": 1491751408000
  },
  "user": {
    "firstName": "John",
    "lastName": "Smith",
    "birthDate": 1491751408000,
    "email": "me@myemail.com",
    "phone": "9998887654",
    "userId": 12345,
    "deleted": false,
    "created": 1491751408000
  }
}

Parameters

Parameter	In	Type	Required	Description
cardId	path	integer(int64)	true	The Id of the card
body	body	Card	true	the card object to Activate

Responses

Status	Meaning	Description	Schema
200	OK	OK	Card

Reissue a card

# You can also use wget
curl -X POST https://api.bentoforbusiness.com/cards/{cardId}/reissue \
  -H 'Authorization: Bearer {access_token}'

POST /cards/{cardId}/reissue

Reissues the specified card. This permanetly deletes the old card and new card will be created with the old properties. It cannot be undone.

Parameters

Parameter	In	Type	Required	Description
cardId	path	integer(int64)	true	The Id of the card

Responses

Status	Meaning	Description	Schema
200	OK	OK	Card

Retrieve a card's PAN

# You can also use wget
curl -X GET https://api.bentoforbusiness.com/cards/{cardId}/pan \
  -H 'Authorization: Bearer {access_token}'

GET /cards/{cardId}/pan

Retrieves the specified card's Primary Account Number (PAN) and CVV.

Parameters

Parameter	In	Type	Required	Description
cardId	path	integer(int64)	true	The Id of the card

Responses

Status	Meaning	Description	Schema
200	OK	OK	Inline

Response Schema

Status Code 200

Name	Type	Required	Description
pan	string	false	the card number
cvv	string	false	the card CVV

Retrieve a card's billing address

# You can also use wget
curl -X GET https://api.bentoforbusiness.com/cards/{cardId}/billingaddress \
  -H 'Authorization: Bearer {access_token}'

GET /cards/{cardId}/billingaddress

Retrieves the billing address for the specified card.

Parameters

Parameter	In	Type	Required	Description
cardId	path	integer(int64)	true	The Id of the card

Responses

Status	Meaning	Description	Schema
200	OK	OK	Address

Create a card's billing address

# You can also use wget
curl -X POST https://api.bentoforbusiness.com/cards/{cardId}/billingaddress \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'

POST /cards/{cardId}/billingaddress

Creates a new billing address for the specified card.

{
  "active": true,
  "addressType": "BUSINESS_ADDRESS",
  "city": "San Francisco",
  "id": 12345,
  "state": "CA",
  "street": "123 Main Street",
  "zipCode": "94123"
}

Parameters

Parameter	In	Type	Required	Description
cardId	path	integer(int64)	true	The Id of the card
body	body	Address	true	The billing address to add

Responses

Status	Meaning	Description	Schema
200	OK	OK	Address

Update a card's billing address

# You can also use wget
curl -X PUT https://api.bentoforbusiness.com/cards/{cardId}/billingaddress \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'

PUT /cards/{cardId}/billingaddress

Updates the card's existing billing address if one exists.

{
  "active": true,
  "addressType": "BUSINESS_ADDRESS",
  "city": "San Francisco",
  "id": 12345,
  "state": "CA",
  "street": "123 Main Street",
  "zipCode": "94123"
}

Parameters

Parameter	In	Type	Required	Description
cardId	path	integer(int64)	true	The Id of the card
body	body	Address	true	The billing address to update

Responses

Status	Meaning	Description	Schema
200	OK	OK	Address

Card Transactions

Card transactions created by cards owned by business

List all card transactions

# You can also use wget
curl -X GET https://api.bentoforbusiness.com/transactions \
  -H 'Authorization: Bearer {access_token}'

GET /transactions

Retrieves list of card transactions for the current business.

Parameters

Parameter	In	Type	Required	Description
status	query	string	false	Query only COMPLETE, PENDING or DECLINED transactions.
type	query	string	false	Query only transactions of the specified type.
dateStart	query	integer(int64)	false	Only transactions after this date. Default is 1 month ago. Date value in milliseconds elapsed since the UNIX epoch.
dateEnd	query	integer(int64)	false	Only transactions before this date. Default is now. Date value in milliseconds elapsed since the UNIX epoch.
cards	query	integer(int64)	false	A list of cardIds to filter.
tags	query	string	false	A list of tags to filter.
categories	query	integer(int64)	false	A list of categoryIds to filter.
cardLifecycle	query	string	false	Filter cards on specific lifecycleStatus.
search	query	string	false	Query for transactions with specified text. When you use this options, all other filters are ignored.

Responses

Status	Meaning	Description	Schema
200	OK	OK	CardTransactionPage

Retrieve a transaction

# You can also use wget
curl -X GET https://api.bentoforbusiness.com/transactions/{transactionId} \
  -H 'Authorization: Bearer {access_token}'

GET /transactions/{transactionId}

Retrieves a single transaction.

Parameters

Parameter	In	Type	Required	Description
transactionId	path	integer(int64)	true	the Id of the transaction

Responses

Status	Meaning	Description	Schema
200	OK	OK	CardTransaction

Create a transaction tag

# You can also use wget
curl -X POST https://api.bentoforbusiness.com/transactions/{transactionId}/tags \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'

POST /transactions/{transactionId}/tags

Creates a new tag on a transaction. Multiple transaction tags are supported by repeating the creation request for each tag.

{
  "name": "string"
}

Parameters

Parameter	In	Type	Required	Description
transactionId	path	integer(int64)	true	the Id of the transaction
body	body	object	true	No description
name	body	string	false	No description

Responses

Status	Meaning	Description	Schema
200	OK	OK	CardTransaction

Delete a transaction tag

# You can also use wget
curl -X DELETE https://api.bentoforbusiness.com/transactions/{transactionId}/tags/{tagId} \
  -H 'Authorization: Bearer {access_token}'

DELETE /transactions/{transactionId}/tags/{tagId}

Deletes a tag on a transactions.

Parameters

Parameter	In	Type	Required	Description
transactionId	path	integer(int64)	true	the Id of the transaction
tagId	path	string	true	The tag to be deleted

Responses

Status	Meaning	Description	Schema
200	OK	OK	CardTransaction

Update a transaction's notes

# You can also use wget
curl -X PUT https://api.bentoforbusiness.com/transactions/{transactionId}/notes \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}'

PUT /transactions/{transactionId}/notes

Update notes on a transaction.

"string"

Parameters

Parameter	In	Type	Required	Description
transactionId	path	integer(int64)	true	the Id of the transaction
body	body	string	true	The note

Responses

Status	Meaning	Description	Schema
200	OK	OK	CardTransaction

Webhooks

List all webhook subscriptions

# You can also use wget
curl -X GET https://api.bentoforbusiness.com/webhooks \
  -H 'Authorization: Bearer {access_token}'

GET /webhooks

Retrives list of webhook subscriptions for the current business.

Responses

Status	Meaning	Description	Schema
200	OK	OK	WebhookSubscriptionPage

Create a webhook subscription

# You can also use wget
curl -X POST https://api.bentoforbusiness.com/webhooks \
  -H 'Authorization: Bearer {access_token}'

POST /webhooks

Creates a webhook subscription.

Responses

Status	Meaning	Description	Schema
200	OK	OK	WebhookSubscription

Retrieve a webhook subscription

# You can also use wget
curl -X GET https://api.bentoforbusiness.com/webhooks/{webhookSubscriptionId} \
  -H 'Authorization: Bearer {access_token}'

GET /webhooks/{webhookSubscriptionId}

Retrieves the details of an existing webhook subscription.

Parameters

Parameter	In	Type	Required	Description
webhookSubscriptionId	path	string(uuid)	true	The Id of the webhook subscription

Responses

Status	Meaning	Description	Schema
200	OK	OK	WebhookSubscription

Update a webhook subscription

# You can also use wget
curl -X PUT https://api.bentoforbusiness.com/webhooks/{webhookSubscriptionId} \
  -H 'Authorization: Bearer {access_token}'

PUT /webhooks/{webhookSubscriptionId}

Updates a webhook subscription.

Responses

Status	Meaning	Description	Schema
200	OK	OK	WebhookSubscription

Delete a webhook subscription

# You can also use wget
curl -X DELETE https://api.bentoforbusiness.com/webhooks/{webhookSubscriptionId} \
  -H 'Authorization: Bearer {access_token}'

DELETE /webhooks/{webhookSubscriptionId}

Deletes a webhook subscription.

Responses

Status	Meaning	Description	Schema
200	OK	OK	WebhookSubscription

Schemas

ApiApplication

{
  "apiApplicationId": 12345,
  "name": "My App Name",
  "accessKey": "string"
}

Properties

Name	Type	Required	Description
apiApplicationId	integer(int64)	false	Api Application Identifier
name	string	false	Name of the Application
accessKey	string	false	Access key used for API Application

BusinessesResponse

{
  "businesses": [
    {
      "businessId": 12345,
      "companyName": "My Company Inc",
      "nameOnCard": "My Company",
      "phone": "9998881234",
      "accountNumber": "820187766",
      "businessStructure": "LLC",
      "status": "APPROVED",
      "createdDate": 1491751408000,
      "approvalDate": 1491751408000,
      "approvalStatus": "Approved",
      "balance": 100.99,
      "timeZone": "America/Los_Angeles",
      "addresses": [
        {
          "active": true,
          "addressType": "BUSINESS_ADDRESS",
          "city": "San Francisco",
          "id": 12345,
          "state": "CA",
          "street": "123 Main Street",
          "zipCode": "94123"
        }
      ]
    }
  ]
}

Properties

Name	Type	Required	Description
businesses	[Business]	false	List of businesses that you have access to

Business

{
  "businessId": 12345,
  "companyName": "My Company Inc",
  "nameOnCard": "My Company",
  "phone": "9998881234",
  "accountNumber": "820187766",
  "businessStructure": "LLC",
  "status": "APPROVED",
  "createdDate": 1491751408000,
  "approvalDate": 1491751408000,
  "approvalStatus": "Approved",
  "balance": 100.99,
  "timeZone": "America/Los_Angeles",
  "addresses": [
    {
      "active": true,
      "addressType": "BUSINESS_ADDRESS",
      "city": "San Francisco",
      "id": 12345,
      "state": "CA",
      "street": "123 Main Street",
      "zipCode": "94123"
    }
  ]
}

Properties

Name	Type	Required	Description
businessId	integer(int64)	false	Business Identifier
companyName	string	false	Legal name of the Business
nameOnCard	string	false	Name that appears on the business line of the card
phone	string	false	The business phone
accountNumber	string	false	Account number for the business
businessStructure	string	false	Business structure
status	string	false	The status of the business.
createdDate	integer(int64)	false	No description
approvalDate	integer(int64)	false	The Date the business has been approved
approvalStatus	string	false	Status of the application of the business
balance	number(double)	false	The business balance
timeZone	string	false	No description
addresses	[Address]	false	No description

Enumerated Values

Property	Value
businessStructure	Sole_Proprietorship
businessStructure	Partnership
businessStructure	LLC
businessStructure	S_Corp
businessStructure	C_Corp
businessStructure	Non_Profit
status	APPROVED
status	SUSPENDED
status	CANCELED
status	REJECTED
status	NOT_APPROVED
approvalStatus	Approved
approvalStatus	Rejected
approvalStatus	Reffered
approvalStatus	Not_Checked_Yet

Address

{
  "active": true,
  "addressType": "BUSINESS_ADDRESS",
  "city": "San Francisco",
  "id": 12345,
  "state": "CA",
  "street": "123 Main Street",
  "zipCode": "94123"
}

Properties

Name	Type	Required	Description
active	boolean	false	No description
addressType	string	false	No description
city	string	false	No description
id	integer(int64)	false	No description
state	string	false	No description
street	string	false	No description
zipCode	string	false	No description

Enumerated Values

Property	Value
addressType	BUSINESS_ADDRESS
addressType	USER_ADDRESS

User

{
  "firstName": "John",
  "lastName": "Smith",
  "birthDate": 1491751408000,
  "email": "me@myemail.com",
  "phone": "9998887654",
  "userId": 12345,
  "deleted": false,
  "created": 1491751408000
}

Properties

Name	Type	Required	Description
firstName	string	false	No description
lastName	string	false	No description
birthDate	integer(int64)	false	No description
email	string	false	No description
phone	string	false	No description
userId	integer(int64)	false	No description
deleted	boolean	false	No description
created	integer(int64)	false	No description

Card

{
  "cardId": 12345,
  "type": "CategoryCard",
  "lifecycleStatus": "ACTIVATED",
  "status": "TURNED_ON",
  "expiration": "1221",
  "lastFour": "1234",
  "virtualCard": false,
  "alias": "My Card",
  "availableAmount": 123.45,
  "allowedDays": [
    "MONDAY"
  ],
  "allowedDaysActive": true,
  "allowedCategoriesActive": true,
  "allowedCategories": [
    {
      "transactionCategoryId": 10
    }
  ],
  "createdOn": 1491751408000,
  "updatedOn": 1491751408000,
  "spendingLimit": {
    "active": true,
    "amount": 123.45,
    "period": "Day",
    "customStartDate": 1491751408000,
    "customEndDate": 1491751408000
  },
  "user": {
    "firstName": "John",
    "lastName": "Smith",
    "birthDate": 1491751408000,
    "email": "me@myemail.com",
    "phone": "9998887654",
    "userId": 12345,
    "deleted": false,
    "created": 1491751408000
  }
}

Properties

Name	Type	Required	Description
cardId	integer(int64)	false	No description
type	string	false	No description
lifecycleStatus	string	false	No description
status	string	false	No description
expiration	string	false	No description
lastFour	string	false	No description
virtualCard	boolean	false	No description
alias	string	false	No description
availableAmount	number(double)	false	No description
allowedDays	[string]	false	Card will only accept transactions on days specified
allowedDaysActive	boolean	false	Must be active for card to be respect `allowedDays` restriction
allowedCategoriesActive	boolean	false	No description
allowedCategories	[object]	false	No description
transactionCategoryId	integer(int64)	false	No description
createdOn	integer(int64)	false	Date card was created
updatedOn	integer(int64)	false	Date card was last updated
spendingLimit	SpendingLimit	false	No description
user	User	false	No description

Enumerated Values

Property	Value
type	BusinessOwnerCard
type	EmployeeCard
type	CategoryCard
lifecycleStatus	TERMINATED
lifecycleStatus	ACTIVATED
lifecycleStatus	NEVER_ACTIVATED
lifecycleStatus	NOT_ISSUED_YET
status	CANCELED
status	FRAUD_PREVENTION
status	TURNED_ON
status	TURNED_OFF
status	WEEKLY_RESTRICTION

CardPage

{
  "size": 0,
  "cards": [
    {
      "cardId": 12345,
      "type": "CategoryCard",
      "lifecycleStatus": "ACTIVATED",
      "status": "TURNED_ON",
      "expiration": "1221",
      "lastFour": "1234",
      "virtualCard": false,
      "alias": "My Card",
      "availableAmount": 123.45,
      "allowedDays": [
        "MONDAY"
      ],
      "allowedDaysActive": true,
      "allowedCategoriesActive": true,
      "allowedCategories": [
        {
          "transactionCategoryId": 10
        }
      ],
      "createdOn": 1491751408000,
      "updatedOn": 1491751408000,
      "spendingLimit": {
        "active": true,
        "amount": 123.45,
        "period": "Day",
        "customStartDate": 1491751408000,
        "customEndDate": 1491751408000
      },
      "user": {
        "firstName": "John",
        "lastName": "Smith",
        "birthDate": 1491751408000,
        "email": "me@myemail.com",
        "phone": "9998887654",
        "userId": 12345,
        "deleted": false,
        "created": 1491751408000
      }
    }
  ]
}

Properties

Name	Type	Required	Description
size	integer	false	Total number of cards in query (disregarding the index and limit query parameters) - Used to calculate total number of pages.
cards	[Card]	false	Current page of cards given total size of query, and the limit and index sent up in parameters.

SpendingLimit

{
  "active": true,
  "amount": 123.45,
  "period": "Day",
  "customStartDate": 1491751408000,
  "customEndDate": 1491751408000
}

Properties

Name	Type	Required	Description
active	boolean	false	Limits are in effect
amount	number(double)	false	Max card spending limit
period	string	false	Time length of restriction. Custom allows advanced controls.
customStartDate	integer(int64)	false	Only for custom periods. From present to future date. Date value in milliseconds elapsed since the UNIX epoch.
customEndDate	integer(int64)	false	Only for custom periods. Up to two years in the future. Date value in milliseconds elapsed since the UNIX epoch.

Enumerated Values

Property	Value
period	Day
period	Week
period	Month
period	Custom

CardTransaction

{
  "cardTransactionId": 12345,
  "amount": 123.45,
  "approvalCode": "987654",
  "availableBalance": 123.45,
  "card": {
    "cardId": 12345,
    "type": "CategoryCard",
    "lifecycleStatus": "ACTIVATED",
    "status": "TURNED_ON",
    "expiration": "1221",
    "lastFour": "1234",
    "virtualCard": false,
    "alias": "My Card",
    "availableAmount": 123.45,
    "allowedDays": [
      "MONDAY"
    ],
    "allowedDaysActive": true,
    "allowedCategoriesActive": true,
    "allowedCategories": [
      {
        "transactionCategoryId": 10
      }
    ],
    "createdOn": 1491751408000,
    "updatedOn": 1491751408000,
    "spendingLimit": {
      "active": true,
      "amount": 123.45,
      "period": "Day",
      "customStartDate": 1491751408000,
      "customEndDate": 1491751408000
    },
    "user": {
      "firstName": "John",
      "lastName": "Smith",
      "birthDate": 1491751408000,
      "email": "me@myemail.com",
      "phone": "9998887654",
      "userId": 12345,
      "deleted": false,
      "created": 1491751408000
    }
  },
  "category": {
    "transactionCategoryId": 12,
    "description": "Restaurants",
    "group": "Restaurants and Food",
    "mccs": [
      1234
    ],
    "name": "Restaurants",
    "type": "SPENDING"
  },
  "currency": "USD",
  "deleted": false,
  "fees": 0,
  "ledgerBalance": 123.45,
  "note": "This is a note",
  "settlementDate": 1491751408000,
  "status": "COMPLETE",
  "tags": [
    "Project1"
  ],
  "transactionDate": 1491751408000,
  "type": "CREDIT",
  "payee": {
    "name": "Greatest Restaurant",
    "city": "San Francisco",
    "state": "CA",
    "country": "USA",
    "zip": "94123"
  }
}

Properties

Name	Type	Required	Description
cardTransactionId	integer(int64)	false	No description
amount	number(double)	false	No description
approvalCode	string	false	No description
availableBalance	number(double)	false	No description
card	Card	false	No description
category	Category	false	No description
currency	string	false	No description
deleted	boolean	false	No description
fees	number(double)	false	No description
ledgerBalance	number(double)	false	No description
note	string	false	No description
settlementDate	integer(int64)	false	No description
status	string	false	No description
tags	[string]	false	No description
transactionDate	integer(int64)	false	No description
type	string	false	No description
payee	object	false	No description
name	string	false	No description
city	string	false	No description
state	string	false	No description
country	string	false	No description
zip	string	false	No description

Enumerated Values

Property	Value
status	PENDING
status	COMPLETE
status	DECLINED
type	UNKNOWN
type	CREDIT
type	LOAD
type	DEBIT
type	REFUND
type	ATM
type	CASHBACK
type	FEE

CardTransactionPage

{
  "amount": 0,
  "size": 0,
  "cardTransactions": [
    {
      "cardTransactionId": 12345,
      "amount": 123.45,
      "approvalCode": "987654",
      "availableBalance": 123.45,
      "card": {
        "cardId": 12345,
        "type": "CategoryCard",
        "lifecycleStatus": "ACTIVATED",
        "status": "TURNED_ON",
        "expiration": "1221",
        "lastFour": "1234",
        "virtualCard": false,
        "alias": "My Card",
        "availableAmount": 123.45,
        "allowedDays": [
          "MONDAY"
        ],
        "allowedDaysActive": true,
        "allowedCategoriesActive": true,
        "allowedCategories": [
          {
            "transactionCategoryId": 10
          }
        ],
        "createdOn": 1491751408000,
        "updatedOn": 1491751408000,
        "spendingLimit": {
          "active": true,
          "amount": 123.45,
          "period": "Day",
          "customStartDate": 1491751408000,
          "customEndDate": 1491751408000
        },
        "user": {
          "firstName": "John",
          "lastName": "Smith",
          "birthDate": 1491751408000,
          "email": "me@myemail.com",
          "phone": "9998887654",
          "userId": 12345,
          "deleted": false,
          "created": 1491751408000
        }
      },
      "category": {
        "transactionCategoryId": 12,
        "description": "Restaurants",
        "group": "Restaurants and Food",
        "mccs": [
          1234
        ],
        "name": "Restaurants",
        "type": "SPENDING"
      },
      "currency": "USD",
      "deleted": false,
      "fees": 0,
      "ledgerBalance": 123.45,
      "note": "This is a note",
      "settlementDate": 1491751408000,
      "status": "COMPLETE",
      "tags": [
        "Project1"
      ],
      "transactionDate": 1491751408000,
      "type": "CREDIT",
      "payee": {
        "name": "Greatest Restaurant",
        "city": "San Francisco",
        "state": "CA",
        "country": "USA",
        "zip": "94123"
      }
    }
  ]
}

Properties

Name	Type	Required	Description
amount	number(double)	false	Total amount of card transactions included in this page
size	integer(int64)	false	Total number of card transactions for a given query (ignoring pagination parameters) - Used for calculating total number of pages
cardTransactions	[CardTransaction]	false	Card transactions for the given page

WebhookEvent

{
  "webhookEventId": "76754760-376f-4f88-81cb-5b9fc01a98c0",
  "webhookSubscriptionId": "76754760-376f-4f88-81cb-5b9fc01a98c0",
  "topic": "transaction",
  "data": {}
}

Properties

Name	Type	Required	Description
webhookEventId	string(uuid)	false	No description
webhookSubscriptionId	string(uuid)	false	No description
topic	string	false	No description
data	object	false	No description

Enumerated Values

Property	Value
topic	transaction

WebhookSubscription

{
  "webhookSubscriptionId": "76754760-376f-4f88-81cb-5b9fc01a98c0",
  "businessId": 12345,
  "url": "https://mydomain.example/webhook",
  "topic": "transaction",
  "method": "post",
  "created": 1491751408000,
  "updated": 1491751408000
}

Properties

Name	Type	Required	Description
webhookSubscriptionId	string(uuid)	false	No description
businessId	integer(int64)	false	Business Identifier
url	string	false	No description
topic	string	false	No description
method	string	false	No description
created	integer(int64)	false	No description
updated	integer(int64)	false	No description

Enumerated Values

Property	Value
topic	transaction
method	post

WebhookSubscriptionPage

{
  "cardTransactions": [
    {
      "webhookSubscriptionId": "76754760-376f-4f88-81cb-5b9fc01a98c0",
      "businessId": 12345,
      "url": "https://mydomain.example/webhook",
      "topic": "transaction",
      "method": "post",
      "created": 1491751408000,
      "updated": 1491751408000
    }
  ]
}

Properties

Name	Type	Required	Description
cardTransactions	[WebhookSubscription]	false	All webhook subscriptions

Bento for Business API

Base API URLs

Authentication

How to use

Guides

Getting Started

Creating a Virtual Card

Types of Cards

1. Create a virtual card

2. Poll the card status until it is processed

3. Retrieve the card number, cvv, and expiration date

4. Change the card billing address (Optional)

Change Spending Limits

Daily, Weekly, Monthly

Custom

Using Webhooks

Webhook Payload

Topics

Getting Started

Best Practices

Connecting your API Key to Multiple Bento Businesses

Resources

Session

Login

Parameters

Responses

Business

Get current business

Responses

Cards

List all cards

Parameters

Enumerated Values

Responses

Create a new card

Parameters

Responses

Retrieve a card

Parameters

Responses

Update a card

Parameters

Responses

Delete a card

Parameters

Responses

Activate a card

Parameters

Responses

Reissue a card

Parameters

Responses

Retrieve a card's PAN

Parameters

Responses

Response Schema

Retrieve a card's billing address

Parameters

Responses

Create a card's billing address

Parameters

Responses

Update a card's billing address

Parameters

Responses

Card Transactions

List all card transactions

Parameters

Responses

Retrieve a transaction

Parameters

Responses

Create a transaction tag

Parameters

Responses

Delete a transaction tag

Parameters

Responses

Update a transaction's notes

Parameters