Direct API Documentation

Version 0.13

Updated December 29th, 2022

Summary

dash.fi’s Direct API allows authorized customers to access some features of the platform directly through an API, in addition to the normal web UI.

The API has rate limiting to ensure high performance across all customers. Requests per customer are limited to 20 requests per second.

To request access to our Direct API, contact support@dash.fi.

💡 NOTE: For more information about the API and best practices recommendation you can check out our API - Details and Recommendations page.

Authentication

Authentication is achieved using a Bearer token, where the token is your account’s API key. This needs to be included with every request, using the Authorization HTTP header.

Example:

Authorization: Bearer <your API key>

You can see your API key within your Account → Personal page.

Endpoints

Status

Method

GET

URL

https://app.dash.fi/api-v1/status

Description

Get the status of the dash.fi Direct API.

Request Body

None

Response Body

{
	"data": {
		"status": "ok"
	}
}

Create a Card

Method

POST

URL

https://app.dash.fi/api-v1/cards

Description

Create a new card.

Request Body

{
	"category": <integer>,
	"external_id": <string>,
	"name": <string>,
	"spending_frequency": "single-use"|"recurring"
}

Whereas…

external_id is an optional field, which can be used to store a string for your own purpose. This value will be present when you retrieve the list of cards as well. If no value is supplied, it will have the null value when returned.
spending_frequency means:
- single-use The card can be used for a single transaction
- recurring The card can be used for multiple transactions.
category values are:

Aa Expense Type	Description	# Category Value
Other	General Expense	6
Ad Platform	Facebook Ads	7
Ad Platform	Google Ads	8
Ad Platform	Taboola	9
Ad Platform	Snap	10
Ad Platform	TikTok	11
Ad Platform	Amazon Ads	21
Ad Platform	Other Ad Platform Expenses	12
Shipment	FedEx	13
Shipment	UPS	14
Shipment	USPS	15
Shipment	3PL	16
Shipment	Other Shipping Service Expenses	17
Saas	Shopify	18
SaaS	Klaviyo	19
SaaS	Other SaaS Expenses	20

Response Body

{
	"data": {
		"id": <integer>,
		"category": <integer>,
		"external_id": <string>|null,
		"name": <string>,
		"spend_limit": 0,
		"spend_limit_duration": "TRANSACTION",
		"spending_frequency": "single-use"|"recurring",
		"state": "OPEN",
		"embedded_url": <string>,
                "create_at": "2023-01-06T17:55:41.000000Z",
                "last_four": "1234"
	}
}

Whereas…

id is the new card’s ID (to be used for other API calls).
embedded_url is a URL that can be used to display an embeddable widget containing the card’s PAN, expiration date, and CVV value, without having to store this information locally.

Note: New cards created always have no spending limit. As such, spend_limit is 0 . Also, when spend_limit is 0 , spend_limit_duration is ignored. This means that newly created cards are always unlimited.

Update a Card’s Spend Limit

Method

PATCH

URL

https://app.dash.fi/api-v1/cards/<card_id>/limit

Description

Update a card’s spend limit, whereas:

limit_amount is the card’s spend limit, as a dollars.cents amount;
limit_type is the card’s spend limit duration, such as:
- MONTHLY the limit is checked for the trailing month, if a transaction would bring the sum of the trailing month above the limit it will be declined;
- TRANSACTION the limit is checked for every transaction, transactions above the limit will be declined;
- FOREVER the limit is checked for the lifetime of the card, if a transaction would bring the sum of all transactions of this card above the limit, it will be declined;
- NO-LIMIT the card doesn’t have a limit. The limit_amount needs to be set to 0 as well.

Request Body

{
	"limit_amount": 1553,
        "limit_type: "MONTHLY,
}

Response Body

{
	"data": {
		"status": "ok",
		"message": "Card limit updated successfully."
	}
}

Freeze a Card

Method

POST

URL

https://app.dash.fi/api-v1/cards/***<card_id>***/freeze

Description

Freeze a card. When a card is frozen, no new transactions on the card are possible.

Request Body

None

Response Body

{
	"data": {
		"status": "ok",
		"message": "card freeze"
	}
}

Unfreeze a Card

Method

POST

URL

https://app.dash.fi/api-v1/cards/***<card_id>***/unfreeze

Description

Unfreeze a card. When a card is unfrozen, new transactions on the card are possible again.

Request Body

None

Response Body

{
	"data": {
		"status": "ok",
		"message": "card unfreeze"
	}
}

Archive a Card

Method

DELETE

URL

https://app.dash.fi/api-v1/cards/***<card_id>***

Description

Delete a card. When a card is deleted, no new transactions on the card are possible. THIS IS A NON-REVERSIBLE OPERATION. Once a card is deleted, it will never be usable again.

Request Body

None

Response Body

{
	"data": {
		"status": "ok",
		"message": "card archived"
	}
}

List all the Cards

Method

GET

URL

https://app.dash.fi/api-v1/cards?name=Card&last_four=2421&page=1&per_page=20

Description

Get a list of all the cards.

Query Params

name (optional) string: Card's name
last_four (optional) string: Card's last four digits
page (optional) string: The page offset at which you'd like to resume fetching Cards.
per_page (optional) string: Number of cards per page. Default is 20.

Request Body

None

Response Body

{
	"data": [
	    {
	        "id": <integer>,
		"category": <integer>,
		"external_id": <string>|null,
		"name": <string>,
		"spend_limit": <string>,
		"spend_limit_duration": "MONTHLY"|"TRANSACTION"|"FOREVER",
		"spending_frequency": "single-use"|"recurring",
		"state": "OPEN"|"PAUSED",
		"embedded_url": <string>,
                "created_at": <DateTime ISO>,
                "last_four": <string>
	    },
		...
	],
	"links": {
	    "first": <string>|null,
	    "last": <string>|null,
	    "prev": <string>|null,
	    "next": <string>|null
	},
	"meta": {
	    "current_page": <integer>,
	    "from": <integer>,
	    "last_page": <integer>,
	    "path": "<https://app.dash.fi/api-v1/cards>",
	    "per_page": <integer>,
	    "to": <integer>,
	    "total": <integer>
	}
}

Whereas…

data[].state means:
- OPEN for an unfrozen card;
- PAUSED for a frozen card.
data[].spend_limit is the card’s spend limit, as a dollars.cents amount (examples: “500.00”. If the value is 0, it means no limit, and spend_limit_duration is ignored.
data[].spend_limit_duration is the card’s spend limit duration, where it means:
- MONTHLY The spend_limit is checked for the trailing month, if a transaction would bring the sum of the trailing month above the limit it will be declined;
- TRANSACTION The spend_limit is checked for every transaction, transactions above the limit will be declined.
- FOREVER The spend_limit is checked for the lifetime of the card, if a transaction would bring the sum above the limit, it will be declined.

LOOKUP A SINGLE CARD

Method

GET

URL

https://app.dash.fi/api-v1/cards/<id>

Description

Get the information for a single card identified by id .

Request Body

None

Response Body

{
	"data": {
		"id": <integer>,
		"category": <integer>,
		"external_id": <string>|null,
		"name": <string>,
		"spend_limit": <string>,
		"spend_limit_duration": "MONTHLY"|"TRANSACTION"|"FOREVER",
		"spending_frequency": "single-use"|"recurring",
		"state": "OPEN"|"PAUSED",
		"embedded_url": <string>,
                "created_at": <DateTime ISO>,
                "last_four": <string>
	]
}

Whereas…

data.state means:
- OPEN for an unfrozen card;
- PAUSED for a frozen card.
data.spend_limit is the card’s spend limit, as a dollars.cents amount (examples: “500.00”. If the value is 0, it means no limit, and spend_limit_duration is ignored.
data.spend_limit_duration is the card’s spend limit duration, where it means:
- MONTHLY The spend_limit is checked for the trailing month, if a transaction would bring the sum of the trailing month above the limit it will be declined;
- TRANSACTION The spend_limit is checked for every transaction, transactions above the limit will be declined.
- FOREVER The spend_limit is checked for the lifetime of the card, if a transaction would bring the sum above the limit, it will be declined.

List all the Transactions

Method

GET

URL

https://app.dash.fi/api-v1/transactions?page=<integer>&per_page=<integer>&begin=<date>&end=<date>

Description

Get a list of all the transactions for all the cards.

You can filter the transactions for a specific date range using the optionals begin and end query params. The date value format is ISO-8601.

The page and per_page (how many transactions per page) query params are used to iterate through all the transactions. per_page is optional and will default to 20 if the parameter isn’t supplied.

Request Body

None

Response Body

{
	"data": [
		{
			"token": <string>,
			"amount": <number>,
			"descriptor": <string>,
			"card": {
				"id": <integer>,
				"name": <string>,
				"last_four": <string>
			},
			"date": <string>,
			"status": "BOUNCED"|"DECLINED"|"PENDING"|"SETTLED"|"SETTLING"|"VOIDED",
			"merchant_country": <string>|null
		},
		...
	],
	"links": {
		"first": <string>|null,
		"last": <string>|null,
		"prev": <string>|null,
		"next": <string>|null
	},
	"meta": {
		"current_page": <integer>,
		"from": <integer>,
		"last_page": <integer>,
		"path": "<https://app.dash.fi/api-v1/transactions>",
		"per_page": <integer>,
		"to": <integer>,
		"total": <integer>
	}
}

Whereas…

data[].token is a unique identifier for the transaction;
data[].amount is the current transaction amount in dollars, which can change over time;
data[].descriptor is the short descriptor of the card acceptor;
data[].card.id is the ID of the card that was used for this transaction;
data[].card.name is the name of the card that was used for this transaction;
data[].card.last_four is the last four digits of the card’s PAN that was used for this transaction;
data[].date is the date the transaction took place, ISO 8601 formatted;
data[].status means:
- BOUNCED There was an error in settling the transaction against the funding source.
- DECLINED The transaction was declined.
- PENDING Authorization is pending completion from the merchant.
- SETTLED The transaction is complete.
- SETTLING Merchant has completed the transaction, funding source being debited.
- VOIDED The merchant has voided the previously pending transaction.
data[].merchant_country is the country (2 or 3 letters) of the merchant;
links.first The API URL for the first page of the transactions list. Can be null ;
links.last The API URL for the last page of the transactions list. Can be null ;
links.prev The API URL for the previous page of the transactions list. Can be null ;
links.next The API URL for the next page of the transactions list. Can be null ;
meta.current_page is the current page number;
meta.from is the number of the first transaction on that page;
meta.to is the number of the last transaction on that page;
meta.last_page is the last page number;
meta.per_page is the number of transactions per pager;
meta.total is the total number of transactions.

Get a single transaction

Method

GET

URL

https://app.dash.fi/api-v1/transactions/<token>

Description

Get information for a single transaction, identified using the token parameter in the URL.

Request Body

None

Response Body

{
    "token": <string>,
    "amount": <number>,
    "descriptor": <string>,
    "card": {
	"id": <integer>,
	"name": <string>,
	"last_four": <string>
    },
     "date": <string>,
     "status": "BOUNCED"|"DECLINED"|"PENDING"|"SETTLED"|"SETTLING"|"VOIDED",
     "merchant_country": <string>|null
}

Whereas…

token is a unique identifier for the transaction;
amount is the current transaction amount in dollars, which can change over time;
descriptor is the short descriptor of the card acceptor;
card.id is the ID of the card that was used for this transaction;
card.name is the name of the card that was used for this transaction;
card.last_four is the last four digits of the card’s PAN that was used for this transaction;
date is the date the transaction took place, ISO 8601 formatted;
status means:
- BOUNCED There was an error in settling the transaction against the funding source.
- DECLINED The transaction was declined.
- PENDING Authorization is pending completion from the merchant.
- SETTLED The transaction is complete.
- SETTLING Merchant has completed the transaction, funding source being debited.
- VOIDED The merchant has voided the previously pending transaction.
merchant_country is the country (2 or 3 letters) of the merchant.

Retrieve available balance

Method

GET

URL

https://app.dash.fi/api-v1/balance

Description

💡 NOTE: Retrieving available balance is not available for POSTPAID customers.

Retrieve your account’s available prepaid balance.

Request Body

None

Response Body

{
    "data": {
	"balance": <string>
    }
}

Where data.balance is the account’s available prepaid balance, in dollars, like "50253.78" .

Transactions Webhook

Description

We do support calling a webhook every time a transaction is processed (new transactions, but changed to existing transactions as well). If you want to enable a webhook for your account, please reach out to support@dash.fi.

💡 NOTE: If you are relying on real-time information, be aware that the webhook can be delayed by a few hours. If you have some use cases that required immediate up-to-date information, we recommend calling the pull API for these.

Request Method

POST

Request Headers

"content-type": "application/json"

Request Body

{
    "token": <string>,
    "amount": <number>,
    "descriptor": <string>,
    "card": {
	"id": <integer>,
	"name": <string>,
	"last_four": <string>
     },
    "date": <string>,
    "status": "BOUNCED"|"DECLINED"|"PENDING"|"SETTLED"|"SETTLING"|"VOIDED",
    "merchant_country": <string>|null
}

Example transaction.

{

"token":"61c8d4c7-dc84-4283-b302-429f9417db7b",

"amount":45.89,

"descriptor":"Bob's shop",

"card":{

"id":32,

"name":"Card1",

"last_four":"4484"

"date":"2022-05-26T16:28:28.000000Z",

"status":"SETTLED",

"merchant_country":"USA"

}