Introduction
Welcome to the Unit API! Our documentation will walk you from the basics (authentication, request structure) to using and creating financial products (accounts, cards, payments etc.).
Unit treats each client as a standalone organization. You may log into the Unit Dashboard to manage your organization's API tokens, users, applications, customers, accounts and more.
Ready to get started? Contact us to request sandbox access and we'll get your organization set up. We will send you a welcome email that includes your dashboard credentials, a front-end code sample (React) and a server code sample (Node.js).
This introduction section describes our environments, authentication and other general topics.
Environments
Our API and Dashboard are available in two environments:
Name | Dashboard URL | API URL |
---|---|---|
Sandbox | https://app.s.unit.sh/ | https://api.s.unit.sh/ |
Production | Please contact Unit | Please contact Unit |
The sandbox environment contains special API operations that allow you to easily test and simulate different activities, from incoming payments to card spend. You can find the full reference under Simulations.
Postman Collection
You can interact immediately with the Unit API via Postman.
To get started, import the Unit API Postman Collection into Postman, either by link or by downloading and importing the file. For more information, see the following under the Postman help: Importing Data into Postman.
The collection contains two variables:
Key | Value |
---|---|
token |
Your API Token. You can create it from the API Tokens page on the Unit Dashboard |
server_url |
Initially set to the sandbox environment |
Authentication
Example
GET /accounts HTTP/1.1
Host: api.s.unit.sh
Authorization: Bearer v2.public.eyJyb2xlIjoib3JnIiwidX...
Unit's API uses OAuth 2.0 Bearer Token to authenticate requests. All API calls must include the bearer token. You can create an API Token from the API Tokens page on the Unit Dashboard.
When creating an API Token you would need to select the scopes of the token, by default the Create Token Page selects the recommended scopes for an API token.
The unselected scopes are sensitive scopes that are related to funds movement and cards creation. Unit recommends that for those scopes you would use a Customer Token.
Customer Token
A secure alternative to a broad bearer token is a customer-specific bearer token, also known as Customer Token. This type of token is limited to resources under a particular customer (accounts, transactions, statements and more). For instructions, see Create Customer Token.
Rate Limits
Our rate limit is based on your IP address and is set to 1,000 requests per minute. The limit applies to each environment (sandbox and production) separately. If the limit is exceeded, responses will include an HTTP 429 status code along with a relevant message.
Tags
{
"data": {
"type": "depositAccount",
"attributes": {
/// ...
"tags": {
"purpose": "tax",
"my_account_id": "b6f395c9-e58a-40a5-a5a4-901d603440b9"
}
},
/// ...
}
To help you manage, categorize and enrich resources, Unit allows you to attach your own metadata to them in the form of tags (key-value pairs). Common examples:
- Attaching a
my_customer_id
tag to an application with a value that helps you connect the application to a unique customer identifier in your app. - Attaching a
purpose
tag to an account with a value such astax
,saving
orchecking
.
Tag Inheritance
Unit currently allows you to attach tags to the following resources: application, deposit account and payment.
Two additional resources- customer and transaction- are always created as a result of you creating a parent resource (application and payment respectively). They therefore inherit all tags from their parent resource:
- A customer resource inherits all the tags from the application that created it
- A transaction resource inherits all the tags from the payment that created it
Updating Tags
You can add, update or delete tags from resources with the tags
attribute on their corresponding Update operation (for example, Update Deposit Account).
Unit follows the JSON Merge Patch RFC when updating the tags. In general:
- To add or update a tag, specify its key and value
- To delete a tag, specify its key and
null
for the value
Tag Constraints
- Maximum number of tags per resource: 15
- Keys and values are case-sensitive
- Key constraints: 128 characters consisting of letters, numbers and underscores
- Value constraints: 256 characters
Full-text Search
The Find operation under certain resources (such as Application, Customer or Transaction) supports full-text search, to help you find the desired resources more easily.
In particular, you can use full-text search to quickly build better end-customer experiences. An example would be adding a search box that lets end-customers search for transactions by merchant name (e.g. ‘starbucks’) when browsing transactions under their account.
Full-text search rules:
-
unquoted text
: text without quote marks will be converted into words separated by ‘And’ operators. Example: ‘john doe’ will search for a resource with the value ‘john’ and the value ‘doe’. -
OR
: will be converted into words separated by the ‘Or’ operator. Example: ‘john or doe’ will search for a resource with either the value ‘john’ or the value ‘doe’. -
-
: will be converted into the ‘Not’ operator. Example: ‘john -doe’ will search for a resource with the value ‘john’ and without the value ‘doe’.
Idempotency
Some of our API operations support request idempotency, allowing you to call a sensitive operation multiple times and assume that its work will be done no more than once. You may use any string of up to 255 characters as an idempotency key (we recommend UUID version 4).
The guarantee of idempotency is crucial when an API call has failed without a clear reason and a retry is due. For example, if creating a payment does not succeed due to a network error, you can safely retry creating the payment, passing the same idempotency key and assume the payment will occur no more than once, regardless of the number of calls.
Idempotency keys are guaranteed effective for 48 hours from the time they're used successfully. After this time window, they will be recycled and will therefore be treated as new.
Organization Accounts
Organization accounts are special-purpose accounts that only Unit is authorized to create. They can belong to one of the following types:
- Revenue account
- Reserve account
- Cash advance account
- Batch account (see batch payments)
You may access data in organization accounts in the same way that you access data in deposit accounts (for example, by calling Find Transactions).
About JSON:API
Unit's API is REST-based and follows the JSON:API specification.
JSON:API specifies how a client should request resources to be fetched or modified, and how a server should respond to those requests. Resources in Unit include applications, customers, cards, accounts, transactions and more.
JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.
JSON:API requires the use of the JSON:API media type (application/vnd.api+json
) for exchanging data.
Request and Response Structure
Single Resource Object Example:
{
"data": {
"type": "individualCustomer",
"id": "1",
"attributes": {
// ... this customer's attributes
},
"relationships": {
// ... this customer's relationships
}
}
}
Array of Resource Objects Example:
{
"data": [
{
"type": "individualCustomer",
"id": "1",
"attributes": {
// ... this customer's attributes
},
"relationships": {
// ... this customer's relationships
}
}, {
"type": "businessCustomer",
"id": "2",
"attributes": {
// ... this customer's attributes
},
"relationships": {
// ... this customer's relationships
}
}
]
}
All JSON:API requests and responses are JSON documents.
A document MUST contain one of the following top-level members:
- data: the document's “primary data”. Example: when creating an individual application resource, the primary data will contain the individual's personal information.
- errors: an array of error objects.
Primary data MUST be either:
- a single resource object for requests that target single resources, or
- an array of resource objects for requests that target resource collections.
Resource Object
Resource Example:
{
"type": "individualCustomer",
"id": "53",
"attributes": {
"createdAt": "2020-05-12T19:41:04.123Z",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"nationality": "US",
"ssn": "721074426",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "15555555"
}
},
"relationships": {
// ... relationships
}
}
JSON:API documents may contain resource objects to represent objects in the business domain. Unit's resources include applications, customers, cards, accounts, transactions and more.
A resource object MUST contain both the id and the type members.
In addition, a resource object MAY contain these members:
- attributes: an attributes object represents some of the resource’s data (examples include the resource name, address, email, etc.)
- relationships: a relationship object describes the relationship between the current resource and other resources
Relationships
Resource with relationships example:
{
"type": "depositAccount",
"id": "50",
"attributes": {
// ...
},
"relationships": { // relationships object
"customer": { // relationship object
"data": { // resource linkage with single resource identifier
"type": "businessCustomer",
"id": "39"
}
}
}
}
The relationships
object describes the relationship between the current resource and other resources. Each member of the relationships object represents one reference.
In this example, we describe the relationship between a DepositAccount and the customer
it belongs to.
Relationship
A “relationship object” MUST contain a data member with one of the following:
null
for empty to-one relationships.- an empty array (
[]
) for empty to-many relationships. - a single resource identifier (
type
andid
) for non-empty to-one relationships. - array of resource identifiers (
type
andid
) for non-empty to-many relationships.
Errors
Unit's API uses HTTP Status Codes to communicate whether a request has been successfully processed. A request may stop processing as soon as a problem is encountered, or it may continue processing and encounter multiple problems. In either case, the response will contain all available errors.
An “error object” MUST contain a title
and the HTTP status
code members with one or more of the following:
- code: a Unit-specific code, uniquely identifying the error type
- details: additional information about the error
Applications
To onboard an end-customer, create an Application
resource.
Unit supports two types of applications, depending on the type of end-customer: individual and business. Once you create an application, you will receive a response containing its status and a list of required documents.
Application Statuses
The final statuses for an application are Approved
or Denied
. Once an application is approved, a Customer
resource will be created and associated with the application resource.
The new created customer resources will be referenced in the relationships object.
In most cases, an application will reach one of these final statuses immediately after creation, without requiring any documents.
In some cases, documents will be required and the application will enter an AwaitingDocuments
status. Once you upload all the required documents, Unit will use the information provided to approve or deny the application. The decision may take seconds in some cases and up to an hour in other cases (when a manual review is required). Once the process is complete, you will receive a webhook containing the result.
An application can also be evaluated asynchronously, in which case its status will be Pending
as long as the evaluation process is running. Once the process is complete, the status will change to either Approved
, Denied
or AwaitingDocuments
and the relevant webhook will be fired (see Pending
status description below)
Below is a diagram describing the lifecycle of an application:
Below are all application statuses and their descriptions:
Status | Description |
---|---|
AwaitingDocuments |
Certain documents are required for the process to continue. You may upload them via Upload Document |
PendingReview |
The application is pending review by Unit |
Pending |
The application is being evaluated asynchronously and a result should be available shortly. Listen for webhooks (application.denied, customer.created and application.awaitingdocuments) for the final result, or periodically query the application with Get by Id) |
Approved |
The application was approved. A Customer resource was created |
Denied |
The application was denied. A Customer resource will not be created |
Create Individual Application
Example Request:
curl -X POST 'https://api.s.unit.sh/applications' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "individualApplication",
"attributes": {
"ssn": "721074426",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"dateOfBirth": "2001-08-10",
"address": {
"street": "20 Ingram St",
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"ip": "127.0.0.1",
"ein": "123456789",
"dba": "Piedpiper Inc",
"soleProprietorship": true,
"tags": {
"userId": "106a75e9-de77-4e25-9561-faffe59d7814"
}
}
}
}'
Verb | POST |
Url | https://api.s.unit.sh/applications |
Required Scope | applications-write |
Data Type | individualApplication |
Attributes
Name | Type | Description |
---|---|---|
ssn | string | SSN of the individual (numbers only). Either an SSN or a passport number is required |
passport | string | Passport number of the individual (numbers only). Either an SSN or a passport is required |
nationality | ISO31661-Alpha2 string | Required on passport only. Two letters representing the individual nationality. (e.g. “US”) |
fullName | FullName | Full name of the individual |
dateOfBirth | RFC3339 string | e.g. "2001-08-10" |
address | Address | Address of the individual |
phone | Phone | Phone number of the individual |
string | Email address of the individual | |
ip | string | IP address of the customer |
ein | string | Optional. If the individual is a sole proprietor who has an Employer Identification Number, specify it here. Not all sole proprietors have an EIN, so this attribute is optional, even when soleProprietorship is set to true . |
dba | String | Optional. If the individual is a sole proprietor who is doing business under a different name, specify it here. This attribute is optional, even when soleProprietorship is set to true . |
soleProprietorship | boolean | Optional. Default: false. Indicates whether the individual is a sole proprietor. |
tags | object | See tags. Tags will copied to the customer that this application creates- see tag inheritance. |
Response
Response is a JSON:API document.
Example Response:
{
"data": {
"type": "individualApplication",
"id": "53",
"attributes": {
"createdAt": "2020-01-14T14:05:04.718Z",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"ssn": "721074426",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"status": "AwaitingDocuments",
"evaluationOutcome": "Approved",
"ip": "127.0.0.1",
"ein": "123456789",
"dba": "Piedpiper Inc",
"soleProprietorship": true,
"tags": {
"userId": "106a75e9-de77-4e25-9561-faffe59d7814"
}
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
}
]
}
}
},
"included": [
{
"type": "document",
"id": "1",
"attributes": {
"documentType": "AddressVerification",
"status": "Required",
"name": "Peter Parker",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
}
}
},
{
"type": "document",
"id": "2",
"attributes": {
"documentType": "IdDocument",
"status": "Required",
"name": "Peter Parker",
"dateOfBirth": "2001-08-10"
}
}
]
}
201 Created
Field | Type | Description |
---|---|---|
data | IndividualApplication resource | The newly created resource |
included | Array of ApplicationDocument Resource | Required documents for this application. Each document resource includes the document status |
Create Business Application
Example Request:
curl -X POST 'https://api.s.unit.sh/applications' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "businessApplication",
"attributes": {
"name": "Pied Piper",
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"stateOfIncorporation": "DE",
"ein": "123456789",
"entityType": "Corporation",
"ip": "127.0.0.1",
"website": "https://www.piedpiper.com",
"contact": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
}
},
"officer": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"dateOfBirth": "2001-08-10",
"title": "CEO",
"ssn": "721074426",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
},
"beneficialOwners": [
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"dateOfBirth": "2001-08-10",
"ssn": "123456789",
"email": "richard@piedpiper.com",
"percentage": 75,
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
}
],
"tags": {
"userId": "2ab1f266-04b9-41fb-b728-cd1962bca52c"
}
}
}
}'
Verb | POST |
Url | https://api.s.unit.sh/applications |
Required Scope | applications-write |
Data Type | businessApplication |
Attributes
Name | Type | Description |
---|---|---|
name | String | Name of the business |
dba | String | Optional. “Doing business as”. |
address | Address | Address of the business |
phone | Phone | Phone number of the business |
stateOfIncorporation | string | Two letters representing a US state |
ein | string | Business EIN (numbers only). |
entityType | string | One of "Corporation" , "LLC" or "Partnership" . |
ip | string | IP address of the customer. |
website | string | Business's website. Optional. |
contact | BusinessContact | Primary contact of the business |
officer | Officer | Officer representing the business (must be the CEO, COO, CFO, President or BenefitsAdministrationOfficer). To onboard a business successfully, you must provide the officer's full personal details as well as identifying documents. |
beneficialOwners | Array of BeneficialOwner | Array of beneficial owners in the business. Beneficial owners are all people that, directly or indirectly, own 25% or more of the business. To onboard a business successfully, you must provide each beneficial owner's full personal details as well as identifying documents. |
tags | object | See tags. Tags will copied to the customer that this application creates- see tag inheritance. |
Response
Response is a JSON:API document.
201 Created
Field | Type | Description |
---|---|---|
data | BusinessApplication | The newly created resource |
included | Array of ApplicationDocument Resource | Required documents for this application. Each document resource includes the document status |
Example Response:
{
"data": {
"type": "businessApplication",
"id": "50",
"attributes": {
"createdAt": "2020-01-13T16:01:19.346Z",
"name": "Pied Piper",
"dba": null,
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"stateOfIncorporation": "DE",
"ein": "123456789",
"entityType": "Corporation",
"contact": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
}
},
"officer": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"title": "CEO",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"status": "Approved"
},
"beneficialOwners": [
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"email": "richard@piedpiper.com",
"percentage": 75,
"status": "Approved"
}
],
"tags": {
"userId": "2ab1f266-04b9-41fb-b728-cd1962bca52c"
},
"status": "AwaitingDocuments",
"evaluationOutcome": "Approved"
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
},
{
"type": "document",
"id": "3"
}
]
}
}
},
"included": [
{
"type": "document",
"id": "1",
"attributes": {
"documentType": "CertificateOfIncorporation",
"status": "Required",
"name": "Pied Piper"
}
},
{
"type": "document",
"id": "2",
"attributes": {
"documentType": "AddressVerification",
"status": "Required",
"name": "Richard Hendricks",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
}
},
{
"type": "document",
"id": "3",
"attributes": {
"documentType": "IdDocument",
"status": "Required",
"name": "Richard Hendricks"
}
}
]
}
Get by Id
curl -X GET 'https://api.s.unit.sh/applications/43' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/applications/{id} |
Required Scope | applications |
Get an application resource by id.
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | IndividualApplication or BusinessApplication | Application resource. Can be either business or individual, as indicated by the type field. |
included | Array of ApplicationDocument Resource | Application required documents, each document object also include the document status |
Find
curl -X GET 'https://api.s.unit.sh/applications?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/applications |
Required Scope | applications |
Find application resources. Paging can be applied.
Query Parameters
Name | Type | Default | Description |
---|---|---|---|
page[limit] | number | 100 | Maximum number of resources that will be returned. Maximum is 1000 resources. |
page[offset] | number | 0 | Number of resources to skip. |
sort | string | Optional | Optional. sort=createdAt for ascending order or sort=-createdAt (leading minus sign) for descending order. |
filter[query] | string | Optional | Optional. search term according to the Full text search rules |
filter[email] | string | Optional | Optional. filter application by case sensitive email address |
Response
Example Response:
{
"data": [
{
"type": "individualApplication",
"id": "1",
"attributes": {
"createdAt": "2020-01-15T13:47:36.098Z",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"ssn": "721074426",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"status": "AwaitingDocuments",
"message": "Waiting for you to upload the required documents.",
"evaluationOutcome": "Approved"
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
}
]
}
}
},
{
"type": "businessApplication",
"id": "2",
"attributes": {
"createdAt": "2020-01-15T13:48:38.527Z",
"name": "Pied Piper",
"dba": null,
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"stateOfIncorporation": "DE",
"ein": "123456789",
"entityType": "Corporation",
"contact": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
}
},
"officer": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"status": "Approved"
},
"beneficialOwners": [
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"email": "richard@piedpiper.com",
"status": "Approved"
}
],
"status": "AwaitingDocuments",
"message": "Waiting for you to upload the required documents.",
"evaluationOutcome": "Approved"
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
},
{
"type": "document",
"id": "3"
}
]
}
}
}
]
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Array of IndividualApplication or BusinessApplication | Array of application resources. Each resource can be either business or individual, as indicated by the type field. |
Application Document
Application document resources represent the documents that need to be collected for the application to be evaluated.
Their initial status is always Required
. The documents will be different in the case of individual and business applications.
Application document resources are created automatically once an application is created.
Application Document Status
Status | Description |
---|---|
Required |
The document is required for the application to be evaluated |
ReceivedBack |
Back-side of the document was received. Front-side is still required. Only relevant for IdDocument document type |
ReceivedFront |
Front-side of the document was received. Back-side is still required. Only relevant for IdDocument document type |
Invalid |
The document is invalid. You may re-upload the correct document for the application to be evaluated |
Approved |
The document is approved |
PendingReview |
The document is currently undergoing review |
Document Types
Name | Description |
---|---|
IdDocument |
An individual's Drivers License or State ID. Both front-side and back-side are required |
Passport |
An individual's passport |
AddressVerification |
An individual's document to verify address. Document may be a utility bill, bank statement, lease agreement or current pay stub. |
SocialSecurityCard |
An individual's social security card |
CertificateOfIncorporation |
A business's certificate of incorporation |
EINConfirmation |
A business's EIN confirmation document (either IRS form 147c or IRS form CP-575) |
Upload Document
curl --request PUT 'https://api.s.unit.sh/applications/46/documents/3' \
--header 'Content-Type: application/pdf' \
--data-binary 'passport.pdf'
Verb | PUT |
Url | https://api.s.unit.sh/applications/{applicationId}/documents/{documentId} |
Required Scope | applications-write |
Uploads a document file. Supported file types are pdf
, jpeg
or png
.
Headers
Header | Value |
---|---|
Content-Type | One of image/png , image/jpeg , or application/pdf |
Response
Example Response:
{
"data": {
"type": "document",
"id": "3",
"attributes": {
"documentType": "Passport",
"status": "Approved",
"description": "Please provide a current copy of your passport.",
"name": "Richard Hendricks",
"dateOfBirth": "2001-08-10"
}
}
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | ApplicationDocument | The target resource after the operation was completed |
Upload Document Back-Side
curl --request PUT 'https://api.s.unit.sh/applications/46/documents/3/back' \
--header 'Content-Type: application/pdf' \
--data-binary 'driver-license-back.pdf'
Verb | PUT |
Url | https://api.s.unit.sh/applications/{applicationId}/documents/{documentId}/back |
Required Scope | applications-write |
Uploads the back-side of a document. Supported file types are pdf
, jpeg
or png
.
Headers
Header | Value |
---|---|
Content-Type | One of image/png , image/jpeg , or application/pdf |
Response
Example Response:
{
"data": {
"type": "document",
"id": "3",
"attributes": {
"documentType": "IdDocument",
"status": "Approved",
"description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID.",
"name": "Richard Hendricks",
"dateOfBirth": "2001-08-10"
}
}
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | ApplicationDocument | The target resource after the operation was completed |
Find
curl -X GET 'https://api.s.unit.sh/applications/1/documents' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/applications/{applicationId}/documents |
Required Scope | applications |
Find application documents.
Response
Example Response:
{
"data": [
{
"type": "document",
"id": "1",
"attributes": {
"documentType": "CertificateOfIncorporation",
"status": "Required",
"description": "Please provide a certified copy of the Articles of Incorporation or Certificate of Incorporation.",
"name": "Pied Piper"
}
},
{
"type": "document",
"id": "2",
"attributes": {
"documentType": "AddressVerification",
"status": "Required",
"description": "Please provide a document to verify your address. Document may be a utility bill, bank statement, lease agreement or current pay stub.",
"name": "Richard Hendricks",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
}
},
{
"type": "document",
"id": "3",
"attributes": {
"documentType": "IdDocument",
"status": "Required",
"description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID.",
"name": "Richard Hendricks"
}
}
]
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Array of ApplicationDocument Resource | Array of application documents |
Customers
Customers represent individuals or businesses that you may create financial products for.
You cannot create customer resources directly — they are automatically created once an application is approved.
A customer can be either BusinessCustomer or IndividualCustomer.
Get by Id
curl -X GET 'https://api.s.unit.sh/customers/8' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/customers/{id} |
Required Scope | customers |
Get a customer resource by id.
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | BusinessCustomer or IndividualCustomer | Customer resource. Can be either business or individual, as indicated by the type field |
Find
curl -X GET 'https://api.s.unit.sh/customers?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/customers |
Required Scope | customers |
Find customer resources. Paging can be applied.
Query Parameters
Name | Type | Default | Description |
---|---|---|---|
page[limit] | number | 100 | Maximum number of resources that will be returned. Maximum is 1000 resources |
page[offset] | number | 0 | Number of resources to skip |
sort | string | Optional | Optional. sort=createdAt for ascending order or sort=-createdAt (leading minus sign) for descending order. |
filter[query] | string | Optional | Optional. search term according to the Full text search rules |
filter[email] | string | Optional | Optional. filter customers by case sensitive email address |
Response
Example Response:
{
"data": [
{
"type": "businessCustomer",
"id": "1",
"attributes": {
"createdAt": "2020-05-10T12:28:37.698Z",
"name": "Pied Piper",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "1555555566"
},
"stateOfIncorporation": "DE",
"ein": "123456789",
"entityType": "Corporation",
"contact": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "1555555566"
}
}
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"application": {
"data": {
"type": "businessApplication",
"id": "1"
}
}
}
},
{
"type": "individualCustomer",
"id": "8",
"attributes": {
"createdAt": "2020-05-12T19:41:04.123Z",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"ssn": "721074426",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "1555555566"
}
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"application": {
"data": {
"type": "individualApplication",
"id": "8"
}
}
}
}
]
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Array of BusinessCustomer or IndividualCustomer | Array of customer resources. Each resource can be either business or individual, as indicated by the type field |
Create Customer Token
curl -X POST 'https://api.s.unit.sh/customers/8/token' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type":"customerToken",
"attributes": {
"scope": "customers customer-token-create accounts-create accounts"
}
}
}
'
Finding all accounts of a customer:
curl -X GET 'https://api.s.unit.sh/accounts' \
-H "Authorization: Bearer ${CUSTOMER_TOKEN}"
Create a bearer token for a particular customer. The returned token can be used in the Authorization
header as a secure alternative to the broader API token.
A Customer Token can only interact with resources under a particular customer. As an example, calling Find Transactions with a customer bearer token will return only transactions within accounts under that particular customer.
Operations under the following resources may be called with a Customer Bearer Token:
- Customers
- Accounts
- Transactions
- Cards
- Statements
- Payments
- Counterparties
Verb | POST |
Url | https://api.s.unit.sh/customers/:customerId/token |
Required Scope | customer-token-write |
Data Type | customerToken |
Passing the verification challenge response:
{
"data":{
"type":"customerToken",
"attributes": {
"scope": "customers customer-token-create accounts-create accounts",
"verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",
"verificationCode": "203130"
}
}
}
Attributes
Name | Type | Description |
---|---|---|
scope | string | list of Scopes separated by space. |
verificationToken | string | Received as a response from Create Customer Token Verification. Required if scope includes a scope which require two-factor authentication. |
verificationCode | string | 6 digits code sent to the customer through the desired channel. Required if scope include a scope which require two-factor authentication. |
Scopes
The following scopes available when creating a customer token:
Resource | Read Scope | Write Scope |
---|---|---|
Customers | customers | – |
Accounts | accounts | accounts-write |
Cards | cards | cards-write |
Cards Sensitive | cards-sensitive | – |
Transactions | transactions | – |
Statements | statements | – |
Payments | payments | payments-write |
Payments to a counterparty | – | payments-write-counterparty |
Counterparties | counterparties | counterparties-write |
Response
Example Response:
{
"data": {
"type": "customerBearerToken",
"attributes": {
"token": "v2.public.eyJyb2xlIjoiY3VzdG9tZX...",
"expiresIn": 86400
}
}
}
Response is a JSON:API document.
201 Created
Field | Type | Description |
---|---|---|
data.attributes.token | The token issued for the customer. | |
data.attributes.expiresIn | The lifetime of the token (in seconds). |
Create Customer Token Verification
In order to increase security and prevent from token theft, Unit supports two-factor authentication when creating a customer token.
When creating a customer token that contains a scope which require two-factor authentication (see Scopes), it is required to first create a verification challenge that will be sent to the customer.
The challenge is a six digits code and is valid for 10 minutes after its creation.
Create a token verification:
curl -X POST 'https://api.s.unit.sh/customers/10001/token/verification' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type":"customerTokenVerification",
"attributes": {
"channel": "sms"
}
}
}'
Verb | POST |
Url | https://api.s.unit.sh/customers/:customerId/token/verification |
Required Scope | customers |
Data Type | customerTokenVerification |
Attributes
Name | Type | Description |
---|---|---|
channel | string | send a verification code to the customer through one of the following channels sms or call |
Example Response:
{
"data": {
"type": "customerTokenVerification",
"attributes": {
"verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm...."
}
}
}
201 Created
Field | Type | Description |
---|---|---|
verificationToken | string | The verification token that generated for that customer verification, it should be passed back to Create Customer Bearer Token along with the verificationCode the customer received in the specified channel |
Update
update individual customer:
curl -X PATCH 'https://api.s.unit.sh/customers/:customerId' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type": "individualCustomer",
"attributes": {
"address": {
"street": "5231 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94301",
"country": "US"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
}
}
}
}'
Verb | PATCH |
Url | https://api.s.unit.sh/customers/:customerId |
Update Individual
update IndividualCustomer.
Name | Type | Description |
---|---|---|
address | Address | Address of the individual. To modify or add specify the new address type. |
phone | Phone | Phone of the individual. To modify or add specify the new phone type. |
string | Email address of the individual. To modify or add specify the new email address. |
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | IndividualCustomer | Customer resource. |
Deposit Accounts
Create Deposit Account
Example Request:
curl -X POST 'https://api.s.unit.sh/accounts' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "depositAccount",
"attributes": {
"depositProduct": "checking",
"tags": {
"purpose": "checking"
}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "45555"
}
}
}
}
}'
Creates a deposit account for a Customer
using a specified deposit product. A deposit product is a predefined set of terms associated with this deposit account (e.g. interest rate).
Verb | POST |
Url | https://api.s.unit.sh/accounts |
Required Scope | accounts-write |
Data Type | depositAccount |
Attributes
Name | Type | Description |
---|---|---|
depositProduct | string | The name of the deposit product |
tags | object | See tags |
Relationships
Name | Type | Description |
---|---|---|
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or an individual customer |
Response
Response is a JSON:API document.
Example Response:
{
"data": {
"type": "depositAccount",
"id": "42",
"attributes": {
"createdAt": "2000-05-11T10:19:30.409Z",
"name": "Peter Parker",
"depositProduct": "checking",
"routingNumber": "812345678",
"accountNumber": "1000000002",
"currency": "USD",
"balance": 10000,
"hold": 0,
"available": 10000,
"tags": {
"purpose": "checking"
}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "45555"
}
}
}
}
}
201 Created
Field | Type | Description |
---|---|---|
data | DepositAccount resource | The requested resource after the operation was completed |
Get by Id
curl -X GET 'https://api.s.unit.sh/accounts/42' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/accounts/{id} |
Required Scope | accounts |
Get a deposit account resource by id.
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | DepositAccount | The requested resource after the operation was completed |
Find
curl -X GET 'https://api.s.unit.sh/accounts?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/accounts |
Required Scope | accounts |
Find deposit account resources. Paging can be applied.
Query Parameters
Name | Type | Default | Description |
---|---|---|---|
page[limit] | number | 100 | Maximum number of resources that will be returned. Maximum is 1000 resources |
page[offset] | number | 0 | Number of resources to skip |
filter[customerId] | string | Optional | Filters the results by the specified customer id |
Response
Example Response:
{
"data": [
{
"type": "depositAccount",
"id": "42",
"attributes": {
"createdAt": "2000-05-11T10:19:30.409Z",
"name": "Peter Parker",
"depositProduct": "checking",
"routingNumber": "812345678",
"accountNumber": "1000000002",
"currency": "USD",
"balance": 10000,
"hold": 0,
"available": 10000,
"tags": {
"purpose": "tax"
}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "45555"
}
}
}
}
]
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Array of DepositAccount | Array of deposit account resources |
Update
Example Request:
{
"data": {
"type": "depositAccount",
"attributes": {
"tags": {
"purpose": "Tax",
"trackUserId": null,
"newTag": "New tag value"
}
}
}
}
Verb | PATCH |
Url | https://api.s.unit.sh/accounts/:accountId |
Required Scope | depositAccount |
Update a deposit account.
Attributes
Name | Type | Description |
---|---|---|
tags | object | See updating tags |
Response
Response is a JSON:API document.
Example Response:
{
"data": {
"type": "depositAccount",
"id": "42",
"attributes": {
"createdAt": "2000-05-11T10:19:30.409Z",
"name": "Peter Parker",
"depositProduct": "checking",
"routingNumber": "812345678",
"accountNumber": "1000000002",
"currency": "USD",
"balance": 10000,
"hold": 0,
"available": 10000,
"tags": {
"purpose": "checking"
}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "45555"
}
}
}
}
}
200 OK
Field | Type | Description |
---|---|---|
data | DepositAccount resource | The requested resource after the operation was completed |
Payments
Unit allows you to originate and receive ACH payments from/to all deposit accounts. For general information on the ACH network, we recommend the following series from Gusto: How ACH Works: a Developer's Perspective.
ACH Origination overview
In Unit, an ACH payment originates from a Deposit Account. The entity on the other side of the payment is called a Counterparty. A counterparty is a combination of routing number, account number, account type, and name.
Each ACH payment has a direction- either Debit
or Credit
. In the context of ACH origination, the directions work as follows:
- Debit - “pull” funds from the counterparty account. The amount is credited to the originating deposit account on Unit. It may take several business days for the credit to be settled, depending on the settings for your organization.
- Credit - “push” funds to the counterparty account. The amount is debited from the originating deposit account immediately.
ACH returns are an important concept that must be covered by your code. When you originate an ACH payment (both Debit and Credit), the counterparty's institution may issue a return. Returns are much more common in the case of ACH Debit than ACH Credit, with reasons ranging from unauthorized payment to insufficient funds in the counterparty's account.
The ACH is a batch-based network, processing batches of payments with 3 cutoff times during the day. When you originate an ACH payment, it is created with a Pending
status until it is delivered to the ACH network.
ACH Origination requests support Idempotency, ensuring that performing multiple identical requests will have the same effect as performing a single request.
ACH payment to inline Counterparty
Example Request:
curl -X POST 'https://api.s.unit.sh/payments' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "achPayment",
"attributes": {
"amount": 10000,
"direction": "Credit",
"counterparty": {
"routingNumber": "812345678",
"accountNumber": "12345569",
"accountType": "Checking",
"name": "Jane Doe"
},
"description": "ACH PMNT"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "555"
}
}
}
}
}'
Originates an ACH payment to a counterparty which is specified inline (vs to a linked Counterparty resource).
To create a payment, the id
of the deposit account, the counterparty's account number, routing number, name, and account type, as well as the amount
(in cents) and direction
are required.
Verb | POST |
Url | https://api.s.unit.sh/payments |
Required Scope | payments-write |
Data Type | achPayment |
Attributes
Name | Type | Description |
---|---|---|
amount | integer | The amount (in cents) |
direction | string | The direction in which the funds flow |
counterparty | Counterparty | The party on the other side of the ACH payment |
description | string | Payment description (maximum of 50 characters) |
idempotencyKey | string | See idempotency |
tags | object | See tags. Tags will copied to any transaction that this payment creates- see tag inheritance |
Relationships
Name | Type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account originating the payment |
Response
Example Response:
{
"data": {
"type": "achPayment",
"id": "50",
"attributes": {
"createdAt": "2020-01-13T16:01:19.346Z",
"status": "Pending",
"reason": null,
"counterparty": {
"routingNumber": "812345678",
"accountNumber": "12345569",
"accountType": "Checking",
"name": "Jane Doe"
},
"description": "ACH PMNT",
"direction": "Credit",
"amount": 10000,
"tags" : {
"purpose": "internal"
}
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "555"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "99823"
}
}
}
}
}
Response is a JSON:API document.
ACH payment to linked Counterparty
Example Request:
curl -X POST 'https://api.s.unit.sh/payments' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "achPayment",
"attributes": {
"amount": 10000,
"direction": "Credit",
"description": "ACH PMNT"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "555"
}
},
"counterparty": {
"data": {
"type": "counterparty",
"id": "4567"
}
}
}
}
}'
Originates an ACH payment to a Counterparty, the counterparty should be created separately through Create Counterparty.
To create a payment, the id
of the deposit account, the id
of the counterparty, amount
(in cents) and direction
are required.
Verb | POST |
Url | https://api.s.unit.sh/payments |
Required Scope | payments-write-counterparty |
Data Type | achPayment |
Attributes
Name | Type | Description |
---|---|---|
amount | integer | The amount (in cents) |
direction | string | The direction in which the fu nds flow |
description | string | Payment description (maximum of 50 characters) |
idempotencyKey | string | See idempotency |
tags | object | See tags. Tags will copied to any transaction that this payment creates- see tag inheritance |
Relationships
Name | Type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account originating the payment |
counterparty | JSON:API Relationship | The Counterparty the payment to be made to |
Response
Example Response:
{
"data": {
"type": "achPayment",
"id": "50",
"attributes": {
"createdAt": "2020-01-13T16:01:19.346Z",
"status": "Pending",
"reason": null,
"counterparty": {
"routingNumber": "812345678",
"accountNumber": "12345569",
"accountType": "Checking",
"name": "Jane Doe"
},
"description": "ACH PMNT",
"direction": "Credit",
"amount": 10000,
"tags" : {
"purpose": "internal"
}
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "555"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "99823"
}
},
"counterparty": {
"data": {
"type": "counterparty",
"id": "4567"
}
}
}
}
}
Response is a JSON:API document.
Receive an ACH payment
You can receive ACH payments (both Debit and Credit) into any deposit account. To do so, you may provide the routing number and account number to trusted third parties. These numbers are both attributes of any deposit account.
Received ACH payments are processed or returned automatically by Unit. Examples:
- Receiving an ACH Credit in the amount of $20 when the balance is $0 will automatically result in a balance increase. Two transactions will be created: one received ACH transaction and one associated fee transaction (if the fee is non-zero).
- Receiving an ACH Debit in the amount of $20 when the balance is $10 will automatically result in an ACH return to the originating side of the payment. No transactions will be created.
To get notified on received ACH payments, you may process the transaction.created
webhook and inspect the payload for received ACH transactions.
ACH Status
The ACH network works in batches, and it therefore doesn't provide immediate success responses (only error responses). As payments are being processed, you can track the progress by checking the status
attribute on the ACH response object.
The possible status
values are:
Status | Description |
---|---|
Pending |
The payment was created on the Unit ledger but was not yet delivered to the ACH network. Payments with Pending status may be canceled by the originator |
Rejected |
The payment was rejected due to insufficient funds or exceeding daily ACH limits (see reason for more details) |
Clearing |
(Debit only) The payment was sent but the deposit account was not credited yet |
Sent |
The payment was processed by the ACH network. This is the final state for successful payments |
Canceled |
The payment was canceled |
Returned |
The payment was processed but the network or the receiving bank returned the payment (see reason for more details) |
Book Transfers
Book transfers are free and instant fund movements between two accounts under the same bank. Common uses for book transfers include:
- Moving funds between two accounts that belong to the same end-customer
- Moving funds between two accounts that belong to different end-customers
- Moving funds from clearing accounts to end-customer accounts
- Moving funds from your organization's revenue account to an end-customer account
To initiate a book transfer, originate an ACH Credit payment between two accounts that reside on the same bank. Unit will automatically identify such payments as book transfers and process them instantly and free of charge. The result will be one book transaction in each account.
Find
curl -X GET 'https://api.s.unit.sh/payments?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/payments |
Required Scope | payments |
Find payments resources. Filtering, paging and sorting can be applied.
Query Parameters
Name | Type | Default | Description |
---|---|---|---|
page[limit] | number | 100 | Maximum number of resources that will be returned. Maximum is 1000 resources |
page[offset] | number | 0 | Number of resources to skip |
filter[accountId] | string | Optional | Filters the results by the specified account id |
filter[customerId] | string | Optional | Filters the results by the specified customer id |
sort | string | Optional | Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order |
Response
Example Response:
{
"data": [
{
"type": "achPayment",
"id": "50",
"attributes": {
"createdAt": "2020-01-13T16:01:19.346Z",
"status": "Pending",
"counterparty": {
"routingNumber": "812345678",
"accountNumber": "12345569",
"accountType": "Checking",
"name": "Jane Doe"
},
"description": "ACH PMNT",
"direction": "Credit",
"amount": 10000
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "555"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "99823"
}
},
"counterparty": {
"data": {
"type": "counterparty",
"id": "4567"
}
},
"transaction": {
"data": {
"type": "transaction",
"id" : "4003"
}
}
}
}
]
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Array of Ach Payment | Array of payment resources |
Get by Id
curl -X GET 'https://api.s.unit.sh/payments/100' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/payments/{id} |
Required Scope | payments |
Get a payment by payment id.
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Ach Payment | Payment resources |
Cards
The card
resource represents a debit card under an account.
Create Individual Debit Card
Example Request:
curl -X POST 'https://api.s.unit.sh/cards' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type":"individualDebitCard",
"attributes": {
"shippingAddress": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "2"
}
}
}
}
}'
Verb | POST |
Url | https://api.s.unit.sh/cards |
Required Scope | cards-write |
Data Type | individualDebitCard |
Creates and ships a debit card to an individual. You must link the card to an account using the account
field under relationships
object. The linked account must belong to an individual customer (and not a business)
Attributes
Name | Type | Description |
---|---|---|
shippingAddress | Address | Address to ship the card to. Optional, if not specified, the individual address is used |
Relationships
Name | Type | Description |
---|---|---|
account | JSON:API Relationship | Link to the account the card belongs to. Holder of the account must be an individual |
Response
Response is a JSON:API document.
Example Response:
{
"data": {
"type": "individualDebitCard",
"id": "8",
"attributes": {
"createdAt": "2020-05-13T09:07:47.645Z",
"last4Digits": "1234",
"expirationDate": "2022-05",
"shippingAddress": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"status": "Inactive"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "2"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "2"
}
}
}
}
}
201 Created
Field | Type | Description |
---|---|---|
data | IndividualDebitCard resource | The target resource after the operation was completed |
Create Business Debit Card
Example Request:
curl -X POST 'https://api.s.unit.sh/cards' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type":"businessDebitCard",
"attributes": {
"shippingAddress": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
}
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1"
}
}
}
}
}'
Verb | POST |
Url | https://api.s.unit.sh/cards |
Required Scope | cards-write |
Data Type | businessDebitCard |
Creates and ships a debit card to a business. You must link the card to an account using the account
field under relationships
object. The linked account must belong to a business customer.
Attributes
Name | Type | Description |
---|---|---|
shippingAddress | Address | Address to ship the card to. Optional, if not specified, card holder address is used. |
ssn | string | SSN of the card holder (numbers only). Either an SSN or a passport number is required |
passport | string | Passport number of the card holder (numbers only). Either an SSN or a passport is required |
nationality | ISO31661-Alpha2 string | Required on passport only. Two letters representing the card holder nationality. (e.g. “US”) |
fullName | FullName | Full name of the card holder |
dateOfBirth | RFC3339 string | Date of birth of the card holder (e.g. "2001-08-10" ) |
address | Address | Address of the card holder |
phone | Phone | Phone of the card holder |
string | Email address of the card holder |
Relationships
Name | Type | Description |
---|---|---|
account | JSON:API Relationship | The account the card belongs to. Holder of the account must be a business |
Response
Response is a JSON:API document.
Example Response:
{
"data": {
"type": "businessDebitCard",
"id": "9",
"attributes": {
"createdAt": "2020-05-13T09:42:21.857Z",
"last4Digits": "2074",
"expirationDate": "2022-05",
"shippingAddress": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"phone": {
"countryCode": "1",
"number": "5555555666"
},
"email": "richard@piedpiper.com",
"dateOfBirth": "2001-08-10",
"ssn": "123456789",
"status": "Inactive"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1"
}
},
"customer": {
"data": {
"type": "businessCustomer",
"id": "1"
}
}
}
}
}
201 Created
Field | Type | Description |
---|---|---|
data | BusinessDebitCard resource | The target resource after the operation was completed |
Create Individual Virtual Debit Card
Example Request:
curl -X POST 'https://api.s.unit.sh/cards' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type":"individualVirtualDebitCard",
"attributes": {
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "2"
}
}
}
}
}'
Verb | POST |
Url | https://api.s.unit.sh/cards |
Required Scope | cards-write |
Data Type | individualVirtualDebitCard |
Creates a debit card for an individual. You must link the card to an account using the account
field under relationships
object. The linked account must belong to an individual customer (and not a business)
Attributes
Name | Type | Description |
---|
Relationships
Name | Type | Description |
---|---|---|
account | JSON:API Relationship | Link to the account the card belongs to. Holder of the account must be an individual |
Response
Response is a JSON:API document.
Example Response:
{
"data": {
"type": "individualVirtualDebitCard",
"id": "8",
"attributes": {
"createdAt": "2020-05-13T09:07:47.645Z",
"last4Digits": "1234",
"expirationDate": "2022-05",
"status": "Inactive"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "2"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "2"
}
}
}
}
}
201 Created
Field | Type | Description |
---|---|---|
data | IndividualVirtualDebitCard resource | The target resource after the operation was completed |
Create Business Virtual Debit Card
Example Request:
curl -X POST 'https://api.s.unit.sh/cards' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type":"businessVirtualDebitCard",
"attributes": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
}
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1"
}
}
}
}
}'
Verb | POST |
Url | https://api.s.unit.sh/cards |
Required Scope | cards-write |
Data Type | businessVirtualDebitCard |
Creates a debit card for a business. You must link the card to an account using the account
field under relationships
object. The linked account must belong to a business customer.
Attributes
Name | Type | Description |
---|---|---|
ssn | string | SSN of the card holder (numbers only). Either an SSN or a passport number is required |
passport | string | Passport number of the card holder (numbers only). Either an SSN or a passport is required |
nationality | ISO31661-Alpha2 string | Required on passport only. Two letters representing the card holder nationality. (e.g. “US”) |
fullName | FullName | Full name of the card holder |
dateOfBirth | RFC3339 string | Date of birth of the card holder (e.g. "2001-08-10" ) |
address | Address | Address of the card holder |
phone | Phone | Phone of the card holder |
string | Email address of the card holder |
Relationships
Name | Type | Description |
---|---|---|
account | JSON:API Relationship | The account the card belongs to. Holder of the account must be a business |
Response
Response is a JSON:API document.
Example Response:
{
"data": {
"type": "businessVirtualDebitCard",
"id": "9",
"attributes": {
"createdAt": "2020-05-13T09:42:21.857Z",
"last4Digits": "2074",
"expirationDate": "2022-05",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"phone": {
"countryCode": "1",
"number": "5555555666"
},
"email": "richard@piedpiper.com",
"dateOfBirth": "2001-08-10",
"ssn": "123456789",
"status": "Inactive"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1"
}
},
"customer": {
"data": {
"type": "businessCustomer",
"id": "1"
}
}
}
}
}
201 Created
Field | Type | Description |
---|---|---|
data | BusinessVirtualDebitCard resource | The target resource after the operation was completed |
Virtual Card Sensitive Data
In order to display sensitive data (i.e. card number and CVV2) to a customer, without any of it passing through your systems (which requires PCI compliance), Unit utilizes a 3rd party service called Very Good Security or VGS for short.
VGS provides a JavaScript library (as well as iOS and Android SDKs) called VGS Show
which allows easy integration with your UI components.
VGS Show offloads the PCI compliance burden by enabling the encrypted transmission of sensitive card data from VGS directly to your cardholder.
The VGS Show JavaScript library enables you to securely display sensitive data in a webpage while safely isolating that sensitive data from your systems. VGS Show JavaScript library injects a secure iframe into your HTML. VGS hosts both the iframe and the data on secure, compliant servers.
Integration steps
Example of creating a Customer Token for sensitive data:
curl -X POST 'https://api.s.unit.sh/customers/8/token' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type":"customerToken",
"attributes": {
"scope": "cards-sensitive",
"verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",
"verificationCode": "203130"
}
}
}
'
Example of displaying card number and CVV2:
<!DOCTYPE html>
<html>
<head>
<meta charSet="utf-8">
<title></title>
<style>
iframe {
height: 20px;
}
</style>
</head>
<body>
<h2>Sensitive Data example</h2>
<label>Card Number:</label>
<div id="pan"></div>
<label>CVV2:</label>
<div id="cvv2"></div>
<script type="text/javascript" src="https://js.verygoodvault.com/vgs-show/1.2/ACh8JJTM42LYxwe2wfGQxwj5.js"></script>
<script type="text/javascript">
const show = VGSShow.create('tntazhyknp1');
const customerToken = "<CUSTOMER TOKEN>"
const cvv2iframe = show.request({
name: 'data-text',
method: 'GET',
path: '/cards/<CARD ID>/secure-data/cvv2',
headers: {
"Authorization": "Bearer " + customerToken
},
htmlWrapper: 'text',
jsonPathSelector: 'data.attributes.cvv2'
});
cvv2iframe.render('#cvv2');
const paniframe = show.request({
name: 'data-text',
method: 'GET',
path: '/cards/<CARD ID>/secure-data/pan',
headers: {
"Authorization": "Bearer " + customerToken
},
htmlWrapper: 'text',
jsonPathSelector: 'data.attributes.pan'
});
paniframe.render('#pan');
</script>
</body>
</html>
Import the VGS Show library:
<script type="text/javascript" src="https://js.verygoodvault.com/vgs-show/1.2/ACh8JJTM42LYxwe2wfGQxwj5.js"></script>
Initialize the component:
const show = VGSShow.create('tntazhyknp1');
Provide a valid customer token:
const customerToken = "<CUSTOMER TOKEN>"
For instructions, see Create Customer Token
Provide a valid card identifier
path: '/cards/<CARD ID>/secure-data/cvv2'
Additional resources
SDKs for iOS and Android and additional code examples can be found here
Get by Id
curl -X GET 'https://api.s.unit.sh/cards/1' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/cards/{id} |
Required Scope | cards |
Get a card resource by id.
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard | Card resource, distinguished by the type field |
Find
curl -X GET 'https://api.s.unit.sh/cards?page[limit]=20&page[offset]=0' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/cards |
Required Scope | cards |
Find cards. Filtering and paging can be applied.
Query Parameters
Name | Type | Default | Description |
---|---|---|---|
page[limit] | number | 100 | Maximum number of resources that will be returned. Maximum is 1000 resources. |
page[offset] | number | 0 | Number of resources to skip. |
filter[accountId] | string | Optional | Filters the results by the specified account id |
filter[customerId] | string | Optional | Filters the results by the specified customer id |
Response
Example Response:
{
"data": [
{
"type": "individualDebitCard",
"id": "1",
"attributes": {
"createdAt": "2020-05-10T16:45:02.272Z",
"last4Digits": "1234",
"expirationDate": "2022-05",
"status": "Active"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "2"
}
}
}
},
{
"type": "businessDebitCard",
"id": "4",
"attributes": {
"createdAt": "2020-05-10T20:37:48.069Z",
"last4Digits": "1234",
"expirationDate": "2022-05",
"shippingAddress": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"phone": {
"countryCode": "1",
"number": "5555555789"
},
"email": "richard@piedpiper.com",
"dateOfBirth": "2001-08-10",
"ssn": "123456789",
"status": "Active"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1"
}
},
"customer": {
"data": {
"type": "businessCustomer",
"id": "1"
}
}
}
}
]
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Array of IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard | Array of card resources, distinguished by the type field |
Update
Verb | PATCH |
Url | https://api.s.unit.sh/cards/:cardId |
Required Scope | cards-write |
update business debit card:
curl -X PATCH 'https://api.s.unit.sh/cards/:cardId' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type":"businessDebitCard",
"attributes": {
"shippingAddress": {
"street": "5231 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94301",
"country": "US"
},
"address": {
"street": "5231 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94301",
"country": "US"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555556"
}
}
}
}'
Update Individual Debit Card
Name | Type | Description |
---|---|---|
shippingAddress | Address | Address to ship the card to. To modify or add specify the key and value. To delete a key specify the key name and null for the value. |
Update Business Debit Card
Name | Type | Description |
---|---|---|
shippingAddress | Address | Address to ship the card to. To modify or add specify the key and value. To delete a key specify the key name and null for the value. |
address | Address | Address of the card holder. To modify or add specify the new address type. |
phone | Phone | Phone of the card holder. To modify or add specify the new phone type. |
string | Email address of the card holder. To modify or add specify the new email address. |
Update Business Virtual Debit Card
Name | Type | Description |
---|---|---|
address | Address | Address of the card holder. To modify or add specify the new address type. |
phone | Phone | Phone of the card holder. To modify or add specify the new phone type. |
string | Email address of the card holder. To modify or add specify the new email address. |
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | IndividualDebitCard Or BusinessDebitCard Or BusinessVirtualDebitCard resource |
The target resource after the operation was completed |
Report Stolen
curl -X POST 'https://api.s.unit.sh/cards/6/report-stolen' \
-H "Authorization: Bearer ${TOKEN}"
Verb | POST |
Url | https://api.s.unit.sh/cards/:cardId/report-stolen |
Required Scope | cards-write |
Report card as stolen.
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard | Card resource, distinguished by the type field |
Report Lost
curl -X POST 'https://api.s.unit.sh/cards/5/report-lost' \
-H "Authorization: Bearer ${TOKEN}"
Verb | POST |
Url | https://api.s.unit.sh/cards/:cardId/report-lost |
Required Scope | cards-write |
Report card as lost.
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard | Card resource, distinguished by the type field |
Close Card
curl -X POST 'https://api.s.unit.sh/cards/7/close' \
-H "Authorization: Bearer ${TOKEN}"
Verb | POST |
Url | https://api.s.unit.sh/cards/:cardId/close |
Required Scope | cards-write |
Close a card.
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard | Card resource, distinguished by the type field |
Freeze Card
curl -X POST 'https://api.s.unit.sh/cards/8/freeze' \
-H "Authorization: Bearer ${TOKEN}"
Verb | POST |
Url | https://api.s.unit.sh/cards/:cardId/freeze |
Required Scope | cards-write |
Freeze a card (temporarly block a card).
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard | Card resource, distinguished by the type field |
Unfreeze Card
curl -X POST 'https://api.s.unit.sh/cards/8/unfreeze' \
-H "Authorization: Bearer ${TOKEN}"
Verb | POST |
Url | https://api.s.unit.sh/cards/:cardId/unfreeze |
Required Scope | cards-write |
Unfreeze a frozen card.
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard | Card resource, distinguished by the type field |
Counterparties
The counterparty
resource represents the other party that participates in a financial transaction.
When a customer is expected to send funds to same counterparty on multiple occasions you may create a counterparty
resource and re-use it by creating an ACH payment to linked Counterparty,
instead of the customer typing the routing number and account number repeatedly.
When creating an API Token Unit recommends not to select the payments-write
and counterparties-write
, however we do recommend selecting payments-write-counterparty
scope,
which allows making payments to counterparty resource only.
When using the recommended scopes for API Token you would first need to create a Customer Token(along with two-factor authentication) in order to create the counterparty resource.
The counterparty resource also allows you to make (automated) payments without creating a Customer Token or selecting sensitive scopes for the API Token,
by using ACH payment to linked Counterparty and API Token with only payments-write-counterparty
selected.
This adds another layer of security, because the API Token alone cannot make payments to counterparties which are not created and approved by the customer.
Create Counterparty
Example Request:
curl -X POST 'https://api.s.unit.sh/counterparties' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "achCounterparty",
"attributes": {
"name": "Joe Doe",
"routingNumber": "123456789",
"accountNumber": "123",
"accountType": "Checking",
"type": "Person"
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "111111"
}
}
}
}
}'
Verb | POST |
Url | https://api.s.unit.sh/counterparties |
Required Scope | counterparties-write |
Data Type | achCounterparty |
Creates a counterparty under a specific customer
Attributes
Name | Type | Description |
---|---|---|
name | string | The account holder's name (whether an individual or a business) |
routingNumber | string | Valid 9-digit ABA routing transit number |
accountNumber | string | Bank account number |
accountType | string | Either Checking or Savings |
type | string | Either Business , Person or Unknown |
Relationships
Name | Type | Description |
---|---|---|
customer | JSON:API Relationship | Link to the customer that the counterparty belongs to |
Response
Response is a JSON:API document.
Example Response:
{
"data": {
"type": "achCounterparty",
"id": "8",
"attributes": {
"createdAt": "2020-05-13T09:07:47.645Z",
"name": "Joe Doe",
"routingNumber": "123456789",
"accountNumber": "123",
"accountType": "Checking",
"type": "Person",
"permissions": "CreditOnly"
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "111111"
}
}
}
}
}
201 Created
Field | Type | Description |
---|---|---|
data | ACH Counterparty resource | The target resource after the operation was completed |
Get by Id
curl -X GET 'https://api.s.unit.sh/counterparties/1' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/counterparties/{id} |
Required Scope | counterparties |
Get a counterparty resource by id.
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | ACH Counterparty | Counterparty resource |
Find
curl -X GET 'https://api.s.unit.sh/counterparties?page[limit]=20&page[offset]=0' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/counterparties |
Required Scope | counterparties |
Find counterparties. Filtering and paging can be applied.
Query Parameters
Name | Type | Default | Description |
---|---|---|---|
page[limit] | number | 100 | Maximum number of resources that will be returned. Maximum is 1000 resources. |
page[offset] | number | 0 | Number of resources to skip. |
filter[customerId] | string | Optional | Filters the results by the specified customer id |
Response
Example Response:
{
"data": [
{
"type": "achCounterparty",
"id": "8",
"attributes": {
"createdAt": "2020-05-13T09:07:47.645Z",
"name": "Joe Doe",
"routingNumber": "123456789",
"accountNumber": "123",
"accountType": "Checking",
"type": "Person",
"permissions": "CreditOnly"
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "111111"
}
}
}
}
]
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Array of ACH Counterparty | Array of counterparty resources |
Transactions
A transaction is an individual entry that represents any financial movement within an account. The transaction
resource represents confirmed transactions that were posted to the account, including their source, amount, and direction.
Unit currently supports the following types of transactions.
Type | Description |
---|---|
Originated ACH | An ACH payment originated from a deposit account |
Received ACH | An ACH payment received into a deposit account |
Returned ACH | An ACH payment returned by the bank |
Book | A payment between two accounts on the same bank |
Purchase | A purchase via debit card |
ATM | A deposit or a withdrawal of funds from an ATM with a debit card |
Fee | Fees incurred for a transaction |
Card Reversal | A reversal of a previous card transaction |
Card Transaction | A transaction that represents various card transactions that are not Purchase or ATM transactions. Those might be split in the future into different types |
In addition to their own specific fields, all transaction types are guaranteed to contain the following top-level fields:
Field | type | Description |
---|---|---|
direction | string | The direction in which the funds flow- Debit or Credit |
amount | number | The amount (cents) of the transaction |
balance | number | The account balance (cents) after the transaction |
summary | string | Human-friendly summary of the transaction |
Find
curl -X GET 'https://api.s.unit.sh/transactions?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/transactions |
Required Scope | transactions |
Find transaction resources. Filtering, paging and sorting can be applied.
Query Parameters
Name | Type | Default | Description |
---|---|---|---|
page[limit] | number | 100 | Maximum number of resources that will be returned. Maximum is 1000 resources |
page[offset] | number | 0 | Number of resources to skip |
filter[accountId] | string | Optional | Filters the results by the specified account id |
filter[customerId] | string | Optional | Filters the results by the specified customer id |
sort | string | Optional | Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order |
query | string | Optional | Optional. search term according to the Full text search rules |
Response
Example Response:
{
"data": [
{
"type": "originatedAchTransaction",
"id": "337",
"attributes": {
"createdAt": "2020-09-06T07:51:02.570Z",
"direction": "Credit",
"amount": 10000,
"balance": 10000,
"summary": "Counterparty: Unit Inc | Description: ACH PYMT",
"description": "ACH PYMT",
"counterparty": {
"name": "Unit Inc",
"routingNumber": "812345678",
"accountNumber": "1",
"accountType": "Checking"
}
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10001"
}
},
"customer": {
"data": {
"type": "customer",
"id": "3"
}
}
}
},
{
"type": "feeTransaction",
"id": "338",
"attributes": {
"createdAt": "2020-09-06T07:51:03.094Z",
"direction": "Debit",
"amount": 10,
"balance": 9990,
"summary": "Fee - ACH PYMT"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10001"
}
},
"customer": {
"data": {
"type": "customer",
"id": "3"
}
},
"relatedTransaction": {
"data": {
"type": "transaction",
"id": "337"
}
}
}
}
]
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Array of OriginatedAchTransaction or ReceivedAchTransaction or BookTransaction or PurchaseTransaction or AtmTransaction or FeeTransaction or CardTransaction or CardReversalTransaction |
Array of transaction resources |
Get by Id
curl -X GET 'https://api.s.unit.sh/transactions/100?filter[accountId]=10070' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/transactions/{id}?filter[accountId]={accountId} |
Required Scope | transactions |
Get a transaction by transaction id and account id.
Query Parameters
Name | Type | Default | Description |
---|---|---|---|
filter[accountId] | string | Mandatory | Filters the results by the specified account id |
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | One of OriginatedAchTransaction ReceivedAchTransaction BookTransaction PurchaseTransaction AtmTransaction FeeTransaction CardTransaction CardReversalTransaction |
Transaction resources |
Batch Payments
A batch payment is any incoming payment into a batch account, which is a type of organization account. Once a batch payment is received, you are expected to split it between multiple customer accounts in your organization. This action is known as release.
Batch accounts are meant to hold funds for a short period of time (typically less than a day). They serve use cases that deposit accounts cannot serve for compliance reasons. One such use case is send funds representing N businesses from a payment processor (e.g. WePay or Stripe) into N accounts under the same N businesses on Unit.
Batch Account
curl -X GET 'https://api.s.unit.sh/accounts/10104' \
-H "Authorization: Bearer ${TOKEN}"
Example Response
{
"data": {
"type": "batchAccount",
"id": "10104",
"attributes": {
"createdAt": "2020-12-09T12:17:49.849Z",
"name": "Pied Piper batch account",
"routingNumber": "812345678",
"accountNumber": "1000000104",
"balance": 0,
"hold": 0
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
}
}
}
}
A batch account is a type of organization account. You may instruct other institutions or payment processors to send funds directly into it, by sharing its routing number and account number.
Create Batch Releases
Example Request:
curl -X POST 'https://api.s.unit.sh/batch-releases' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":[
{
"type": "batchRelease",
"attributes": {
"amount": 3000,
"description": "Gift",
"senderName": "Sherlock Holmes",
"senderAccountNumber": "4581133972",
"senderAddress": {
"street": "221B Baker Street",
"city": "London",
"postalCode": "NW1 6XE",
"country": "UK"
}
},
"relationships": {
"batchAccount": {
"data": {
"type": "batchAccount",
"id": "10104"
}
},
"receiver": {
"data": {
"type": "depositAccount",
"id": "10097"
}
}
}
},
{
"type":"batchRelease",
"attributes": {
"amount": 2000,
"description": "Purchase",
"senderName": "Peter Parker",
"senderAccountNumber": "5324131257",
"senderAddress": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
},
"relationships": {
"batchAccount": {
"data": {
"type": "batchAccount",
"id": "10104"
}
},
"receiver": {
"data": {
"type": "depositAccount",
"id": "10017"
}
}
}
}]
}'
Release is the act of splitting a single batch payment between multiple customer accounts in your organization. When creating releases, you are required to provide compliance information for the original senders of the funds.
Verb | POST |
Url | https://api.s.unit.sh/batch-releases |
Required Scope | batch-releases-write |
Data Type | batchRelease |
Attributes
Name | Type | Description |
---|---|---|
amount | integer | The amount (in cents) to move from the batch account to the receiver account |
description | string | Description of the payment (maximum of 50 characters) |
senderName | string | Sender name for the payment (maximum of 255 characters) |
senderAddress | Address | Sender address for the payment |
senderAccountNumber | string | A unique identifier for the sender of the payment (maximum of 17 characters). As an example, when the payment comes from a card processor, this identifier may be set to the BIN followed by the last four digits of the card used. |
Relationships
Name | Type | Description |
---|---|---|
batchAccount | JSON:API Relationship | The batch account to release the funds from. |
receiver | JSON:API Relationship | The receiver account to release the funds to. |
Response
Example Response:
{
"data":[
{
"type": "batchRelease",
"id": "100123",
"attributes": {
"amount": 3000,
"description": "Gift",
"senderName": "Sherlock Holmes",
"senderAccountNumber": "4581133972",
"senderAddress": {
"street": "221B Baker Street",
"city": "London",
"postalCode": "NW1 6XE",
"country": "UK"
}
},
"relationships": {
"batchAccount": {
"data": {
"type": "batchAccount",
"id": "10104"
}
},
"receiver": {
"data": {
"type": "depositAccount",
"id": "10097"
}
}
}
},
{
"type":"batchRelease",
"id": "100125",
"attributes": {
"amount": 2000,
"description": "Purchase",
"senderName": "Peter Parker",
"senderAccountNumber": "5324131257",
"senderAddress": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
},
"relationships": {
"batchAccount": {
"data": {
"type": "batchAccount",
"id": "10104"
}
},
"receiver": {
"data": {
"type": "depositAccount",
"id": "10017"
}
}
}
}]
}
Response is a JSON:API document.
201 Created
Field | Type | Description |
---|---|---|
data | Array of BatchRelease | Array of batch release resources |
Simulations (Sandbox only)
Unit's Sandbox environment provides additional operations on top of the regular APIs. Those operations allow you to easily test and simulate activities that would normally take a long time or require interaction with the external world.
A common example for testing would be simulating a received ACH payment to create funds in an account, followed by simulating a card purchase to spend those funds.
Application Statuses
By default, all applications in our sandbox will be approved immediately. Below are ways to simulate other statuses:
Status | Description |
---|---|
PendingReview |
Individual application: set the SSN on the application to 000000004. Business application: set the SSN of the Officer or any Beneficial Owner on the application to 000000004. |
AwaitingDocuments |
Individual application: set the SSN on the application to 000000002 to simulate AwaitingDocuments for Address Verification, or 000000003 to simulate AwaitingDocuments for Id Document, or 000000006 to simulate AwaitingDocuments for Social Security Card. Business application: set the SSN of the Officer on the application to 000000005. |
Denied |
Individual application: set the SSN on the application to 000000001. |
Approve Application
Example Request:
curl -X POST 'https://api.s.unit.sh/sandbox/applications/10001/approve' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "applicationApprove",
"attributes": {
"reason": "sandbox"
}
}
}'
Approves an Application under PendingReview
or AwaitingDocuments
status. The Customer Created webhook event will be fired.
Verb | POST |
Url | https://api.s.unit.sh/sandbox/applications/{applicationId}/approve |
Data Type | applicationApprove |
Deny Application
Example Request:
curl -X POST 'https://api.s.unit.sh/sandbox/applications/10001/deny' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "applicationDeny",
"attributes": {
"reason": "sandbox"
}
}
}'
Denies an Application under PendingReview
or AwaitingDocuments
status. The Application Denied webhook event will be fired.
Verb | POST |
Url | https://api.s.unit.sh/sandbox/applications/{applicationId}/deny |
Data Type | applicationDeny |
Approve Document
Example Request:
curl -X POST 'https://api.s.unit.sh/sandbox/applications/10001/documents/1/approve' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{}'
Approves an Application Document. The Document Approved webhook event will be fired.
Verb | POST |
Url | https://api.s.unit.sh/sandbox/applications/{applicationId}/documents/{documentId}/approve |
Reject Document
Example Request:
curl -X POST 'https://api.s.unit.sh/sandbox/applications/10001/documents/1/reject' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "documentReject",
"attributes": {
"reason": "blurry image"
}
}
}'
Rejects an Application Document. The Document Rejected webhook event will be fired.
Verb | POST |
Url | https://api.s.unit.sh/sandbox/applications/{applicationId}/documents/{documentId}/reject |
Data Type | documentReject |
Received ACH payment
Example Request:
curl -X POST 'https://api.s.unit.sh/sandbox/payments' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type":"achPayment",
"attributes": {
"amount": 10000,
"direction": "Credit",
"description": "Payment from Sandbox"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1000"
}
}
}
}
}'
This API allows you to credit your account with the specified amount (in cents) for testing purposes.
Verb | POST |
Url | https://api.s.unit.sh/sandbox/payments |
Data Type | achPayment |
Attributes
Name | Type | Description |
---|---|---|
amount | integer | The amount (in cents) |
direction | string | The direction in which the funds flow (currently, only Credit is supported) |
description | string | Payment description (maximum of 50 characters) |
Relationships
Name | Type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account receiving the payment |
Example Response:
{
"data": {
"type": "achPayment",
"id": "3",
"attributes": {
"createdAt": "2020-06-29T13:17:59.816Z",
"amount": 10000,
"direction": "Credit",
"companyName": "SANDBOX",
"description": "Payment from Sandbox",
"status": "Sent",
"reason": null
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1000"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "1"
}
}
}
}
}
Note: the status for the sandbox payment requests is always Sent
. Please refer to ACH Status for more information about the status codes.
Card Purchases
curl -X POST 'https://api.s.unit.sh/sandbox/purchases' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data":{
"type":"purchaseTransaction",
"attributes": {
"amount": 1000,
"direction": "Debit",
"merchantName": "Apple Inc.",
"merchantType": 1000,
"merchantLocation": "Cupertino, CA",
"coordinates": {
"longitude": -77.0364,
"latitude": 38.8951
}
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "10000"
}
}
}
}
}'
This API allows you to simulate a card purchase (or a refund) with the specified amount (in cents) for testing purposes.
Verb | POST |
Url | https://api.s.unit.sh/sandbox/purchases |
Data Type | purchase |
Attributes
Name | Type | Description |
---|---|---|
amount | integer | The amount (in cents) |
direction | string | The direction of the purchase- Debit for purchase, Credit for refund |
merchantName | string | The name of the merchant |
merchantType | integer | The 4-digit ISO 18245 merchant category code (MCC). Use any number (e.g. 1000 for testing) |
merchantLocation | string | Optional. The location (city, state, etc.) of the merchant |
coordinates | Coordinates | Optional. Coordinates of the purchase transaction |
Relationships
Name | Type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
Example Response:
{
"data": {
"type": "purchaseTransaction",
"id": "12",
"attributes": {
"createdAt": "2020-10-12T21:22:09.528Z",
"amount": 2500,
"direction": "Debit",
"balance": 148490,
"merchantName": "Apple Inc.",
"merchantType": 1000,
"merchantLocation": "Cupertino, CA",
"coordinates": {
"longitude": -77.0364,
"latitude": 38.8951
}
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "10001"
}
},
"customer": {
"data": {
"type": "customer",
"id": "2"
}
}
}
}
}
Activate Card
Example Request:
curl -X POST 'https://api.s.unit.sh/sandbox/cards/9/activate' \
-H "Authorization: Bearer ${TOKEN}"
Activate a card.
Verb | POST |
Url | https://api.s.unit.sh/sandbox/cards/{cardId}/activate |
Generate Account Statement
Example Request:
curl -X POST 'https://api.s.unit.sh/sandbox/accounts/10001/generate-statement' \
-H "Authorization: Bearer ${TOKEN}"
Generate an account statement. The statement includes any transactions performed between the beginning of the current month and up until EOD yesterday
Verb | POST |
Url | https://api.s.unit.sh/sandbox/accounts/{cardId}/generate-statement |
Statements
An account statement is a list of all transactions for an account over a monthly period. The statement includes deposits, charges, withdrawals, as well as the starting and ending balance for the period.
The account statement API enables customers to track their spending, identify fraudulent activity and save money by tracking the fees they pay.
Unit provides white-labeled HTML based account statements supporting all browsers and standard screen resolutions.
Find
curl -X GET 'https://api.s.unit.sh/statements?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/statements |
Required Scope | statements |
Find statement resources. Filtering and paging can be applied.
Query Parameters
Name | Type | Default | Description |
---|---|---|---|
page[limit] | number | 100 | Maximum number of resources that will be returned. Maximum is 1000 resources |
page[offset] | number | 0 | Number of resources to skip |
filter[accountId] | string | Optional | Filters the results by the specified account id |
filter[customerId] | string | Optional | Filters the results by the specified customer id |
Response
Example Response:
{
"data": [
{
"type": "statement",
"id": "1",
"attributes": {
"period": "2020-07"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "1000"
}
},
"customer": {
"data": {
"type": "customer",
"id": "1"
}
}
}
},
{
"type": "statement",
"id": "2",
"attributes": {
"period": "2020-08"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "1000"
}
},
"customer": {
"data": {
"type": "customer",
"id": "1"
}
}
}
}
]
}
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Array of Statement | Array of statement resources |
Get HTML by Id
curl -X GET 'https://api.s.unit.sh/statements/1/html' \
-H "Authorization: Bearer ${TOKEN}"
Verb | GET |
Url | https://api.s.unit.sh/statements/{id}/html |
Required Scope | statements |
Get a statement HTML output by id.
Response
Response is a HTML document.
Webhooks
Unit uses webhooks to notify your application when an event occurs.
Example events: Application Denied, Customer created, Transaction completed.
When one of those events is triggered, an HTTP POST request is sent to the webhook's configured URL, allowing you to act upon it.
Use Unit's Dashboard to create and manage your webhooks.
Securing your webhooks
Example of a NodeJS server verifying webhook payload
const express = require('express')
var crypto = require('crypto')
const app = express()
const port = 4000
app.post('/my-webhhok', (request, response) => {
response.send('request passed signature validation...')
})
app.use(express.json());
app.use(express.urlencoded({
extended: true
}));
app.use((request, response, next) => {
var signature = request.header("x-unit-signature")
var hmac = crypto.createHmac('sha1', <your secret>)
hmac.update(JSON.stringify(request.body))
if(hmac.digest('base64') == signature) {
next()
}
else {
response.status(500).send("Signatures didn't match!")
}
})
app.listen(port, (err) => {
console.log(`server is listening on ${port}`)
})
Ensure your server is only receiving the expected Unit requests.
Once your server is configured to receive payloads, it'll listen for any payloads sent to the endpoint you configured.
For security reasons, you probably want to verify that the payloads are coming from Unit.
To verify the payloads when creating a webhook you can set up a secret token which Unit will use to sign the payloads.
Setting up your secret token
You'll need to set up your secret token in two places: Unit dashboard and your server. To set your token in Unit Dashboard:
- Navigate to Webhooks on the left side menu.
- Click on create and fill up the token field.
Verifying payloads from Unit
If your secret token is set, Unit will use it to create a hash signature with the entire body of the webhook request.
This hash signature, encoded with base64 is passed along with each request in the headers as X-Unit-Signature.
Unit uses an HMAC SHA1 to compute the hash.
Testing
To test the Webhook functionality you can use https://webhook.site. This site will let you generate a unique URL to use for your Webhook and then capture incoming requests, allowing you to examine the event's contents.
Another alternative is to use https://ngrok.com which enables you to expose a port on your development machine to the internet.
Types of events
This is a list of all the types of events we currently send, but we are constantly adding more.
Our event types follow a specific structure: resource.event
.
Our goal is to design a consistent system that makes things easier to follow and code against.
Each event includes an id
field, which uniquely identifies the event instance,
and a type
field that identifies the type of the event instance.
application.denied
Example application.created payload:
{
"data": [
{
"id": "28",
"type": "application.denied",
"attributes": {
"createdAt": "2020-07-29T12:53:05.882Z"
},
"relationships": {
"application": {
"data": {
"id": "52",
"type": "individualApplication"
}
}
}
}
]
}
Occurs when an Application is denied.
document.approved
Example document.approved payload:
{
"data": [
{
"id": "193",
"type": "document.approved",
"attributes": {
"createdAt": "2020-11-09T09:05:49.999Z"
},
"relationships": {
"document": {
"data": {
"id": "6",
"type": "document"
}
},
"application": {
"data": {
"id": "10009",
"type": "individualApplication"
}
}
}
}
]
}
Occurs when an Application Document is approved.
document.rejected
Example document.rejected payload:
{
"data": [
{
"id": "190",
"type": "document.rejected",
"attributes": {
"reason": "blurry image",
"createdAt": "2020-11-08T18:34:38.533Z"
},
"relationships": {
"document": {
"data": {
"id": "6",
"type": "document"
}
},
"application": {
"data": {
"id": "10009",
"type": "individualApplication"
}
}
}
}
]
}
Occurs when an Application Document is rejected.
application.awaitingDocuments
Example application.awaitingDocuments payload:
{
"data": [
{
"id": "3000",
"type": "application.awaitingDocuments",
"attributes": {
"createdAt": "2020-07-29T12:53:05.882Z"
},
"relationships": {
"application": {
"data": {
"id": "87",
"type": "individualApplication"
}
}
}
}
]
}
Occurs when additional Application Documents are required to approve an Application.
customer.created
Example customer.created payload:
{
"data": [
{
"id": "28",
"type": "customer.created",
"attributes": {
"createdAt": "2020-07-29T12:53:05.882Z"
},
"relationships": {
"customer": {
"data": {
"id": "52",
"type": "individualCustomer"
}
},
"application": {
"data": {
"id": "52",
"type": "individualApplication"
}
}
}
}
]
}
Occurs when a new Customer is created.
transaction.created
Example transaction.created payload:
{
"data": [
{
"id": "34",
"type": "transaction.created",
"attributes": {
"summary": "ACH PYMT",
"direction": "Debit",
"amount": "2500",
"createdAt": "2020-07-30T09:17:21.593Z"
},
"relationships": {
"transaction": {
"data": {
"type": "receivedAch",
"id": "10001"
}
},
"account": {
"data": {
"id": "1000",
"type": "account"
}
},
"customer": {
"data": {
"id": "1",
"type": "customer"
}
},
"payment": {
"data": {
"id": "515",
"type": "payment"
}
}
}
}
]
}
Occurs when a Transaction is created.
Resources
IndividualApplication
Example IndividualApplication resource:
{
"type": "individualApplication",
"id": "53",
"attributes": {
"createdAt": "2020-01-14T14:05:04.718Z",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"ssn": "721074426",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "1555555578"
},
"status": "AwaitingDocuments",
"message": "Waiting for you to upload the required documents.",
"evaluationOutcome": "Approved",
"tags": {
"userId": "106a75e9-de77-4e25-9561-faffe59d7814"
}
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
}
]
}
}
}
IndividualApplication
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the application resource |
type | string | Type of the application resource. For individual application the value is always individualApplication |
attributes | JSON Object | JSON object representing the application data |
relationships | JSON:API Relationships | Describes relationships between the application resource and other resources (documents) |
Attributes
Field | type | Description |
---|---|---|
status | string | One of AwaitingDocuments , PendingReview , Approved or Denied , see Application Statuses. |
message | string | A message describing the IndividualApplication status |
createdAt | RFC3339 Date string | The date the resource was created |
ssn | string | SSN of the individual (numbers only). Either ssn or passport will be populated |
passport | string | Individual passport number. Either ssn or passport will be populated |
nationality | ISO31661-Alpha2 string | Only when Passport is populated. Two letters representing the individual nationality (e.g. "US" ) |
fullName | FullName | Full name of the individual |
dateOfBirth | RFC3339 string | e.g. "2001-08-10" |
address | Address | Address of the individual |
phone | Phone | Phone of the individual |
string | Email address of the individual | |
tags | object | See tags |
Relationships
Field | type | Description |
---|---|---|
documents | Array of JSON:API Relationship | Application's documents |
customer | JSON:API Relationship | Optional. The created Customer in case of approved application. |
BusinessApplication
Example BusinessApplication resource:
{
"type": "businessApplication",
"id": "50",
"attributes": {
"createdAt": "2020-01-13T16:01:19.346Z",
"name": "Pied Piper",
"dba": null,
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "1555555578"
},
"stateOfIncorporation": "DE",
"ein": "123456789",
"entityType": "Corporation",
"contact": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "1555555578"
}
},
"officer": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "1555555589"
},
"status": "Approved"
},
"beneficialOwners": [
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"ssn": "123456789",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"phone": {
"countryCode": "1",
"number": "1555555589"
},
"email": "richard@piedpiper.com",
"status": "Approved"
}
],
"tags": {
"userId": "106a75e9-de77-4e25-9561-faffe59d7814"
},
"status": "AwaitingDocuments",
"message": "Waiting for you to upload the required documents.",
"evaluationOutcome": "Approved"
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"documents": {
"data": [
{
"type": "document",
"id": "1"
},
{
"type": "document",
"id": "2"
},
{
"type": "document",
"id": "3"
}
]
}
}
}
BusinessApplication
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the application resource |
type | string | Type of the application resource, for business application the value is always businessApplication |
attributes | JSON Object | JSON object representing the application data |
relationships | JSON:API Relationships | Describes relationships between the application resource and other resources (documents) |
Attributes
Field | type | Description |
---|---|---|
status | string | One of AwaitingDocuments , PendingReview , Approved or Denied , see Application Statuses. |
message | string | A message describing the BusinessApplication status |
createdAt | RFC3339 Date string | e.g. "2020-01-13T16:01:19.346Z" |
name | string | Name of the business |
dba | string | Optional. “Doing business as” |
address | Address | Address of the business |
phone | Phone | Phone of the business. |
stateOfIncorporation | string | Two letters representing a US state |
ein | string | Business EIN (numbers only) |
entityType | string | One of "Corporation" , "LLC" or "Partnership" |
contact | BusinessContact | Primary contact of the business. |
officer | Officer | Officer representing the business, must be CEO, CFO, President or BenefitsAdministrationOfficer. The officer would need to go over KYC process and provide documents |
beneficialOwners | Array of BeneficialOwner | Array of beneficial owners of the business. Beneficial Owner is anyone with more than 25% ownership. Beneficial Owners would need to go over KYC process and provide documents |
tags | object | See tags |
Relationships
Field | type | Description |
---|---|---|
documents | Array of JSON:API Relationship | Application's documents |
customer | JSON:API Relationship | Optional. The created Customer in case of approved application. |
ApplicationDocument
Example ApplicationDocument resource:
{
"type": "document",
"id": "3",
"attributes": {
"documentType": "IdDocument",
"status": "Approved",
"description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID.",
"name": "Richard Hendricks",
"dateOfBirth": "2001-08-10"
}
}
ApplicationDocument
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the document resource |
type | string | Always document |
attributes | JSON Object | JSON object representing the document’s data |
Attributes
Field | type | Description |
---|---|---|
status | string | One of Required , ReceivedBack , ReceivedFront , Invalid , Approved or PendingReview , see Application Document Status |
documentType | string | One of IdDocument , Passport , AddressVerification , CertificateOfIncorporation or EINConfirmation |
description | string | The document requirements description |
name | string | Name of business or individual |
address | Address | Individual address, present only for the AddressVerification document type |
dateOfBirth | RFC3339 string | Present only for Passport and License document types |
passport | string | Individual passport number. Present only for the Passport document type |
ein | string | Business EIN. Present only for the EINConfirmation document type |
reasonCode | string | Application Document rejection reason code. Present only when document status is Invalid . One of PoorQuality , NameMismatch , SSNMismatch , AddressMismatch , DOBMismatch , ExpiredId , EINMismatch , StateMismatch , Other |
reason | string | Application Document rejection reason. Present only when document status is Invalid |
IndividualCustomer
Example IndividualCustomer resource:
{
"type": "individualCustomer",
"id": "8",
"attributes": {
"createdAt": "2020-05-12T19:41:04.123Z",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"ssn": "721074426",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "1555555578"
},
"tags": {
"userId": "106a75e9-de77-4e25-9561-faffe59d7814"
}
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"application": {
"data": {
"type": "individualApplication",
"id": "8"
}
}
}
}
IndividualCustomer
is a JSON:API resource, describing the individual customer. Top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the individual resource. |
type | string | Type of the resource, the value is always individualCustomer |
attributes | JSON Object | JSON object representing the individual data |
relationships | JSON:API Relationships | Describes relationships between the customer resource, the Org it belongs to, and the Application it was created by |
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the resource was created |
ssn | string | Individual passport number. Either ssn or passport will be populated |
passport | string | Individual passport number. Either ssn or passport will be populated |
nationality | ISO31661-Alpha2 string | Only when Passport is populated. Two letters representing the individual nationality (e.g. "US" ) |
fullName | FullName | Full name of the individual |
dateOfBirth | RFC3339 string | e.g. "2001-08-10" |
address | Address | Address of the individual |
phone | Phone | Phone of the individual |
string | Email address of the individual | |
tags | object | See tags |
Relationships
Name | Type | Description |
---|---|---|
org | JSON:API Relationship | The Org of the individual |
application | JSON:API Relationship | The Application that created this individual |
BusinessCustomer
Example BusinessCustomer resource:
{
"type": "businessCustomer",
"id": "1",
"attributes": {
"createdAt": "2020-05-10T12:28:37.698Z",
"name": "Pied Piper",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"phone": {
"countryCode": "1",
"number": "1555555578"
},
"stateOfIncorporation": "DE",
"ein": "123456789",
"entityType": "Corporation",
"contact": {
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "1555555578"
}
},
"tags": {
"userId": "106a75e9-de77-4e25-9561-faffe59d7814"
}
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "1"
}
},
"application": {
"data": {
"type": "businessApplication",
"id": "1"
}
}
}
}
BusinessCustomer
is a JSON:API resource, describing the business customer. Top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the business resource. |
type | string | Type of the resource, the value is always businessCustomer |
attributes | JSON Object | JSON object representing the business data |
relationships | JSON:API Relationships | Describes relationships between the customer resource, the Org it belongs to, and the Application it was created by |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | e.g. "2020-01-13T16:01:19.346Z" |
name | string | Name of the business |
dba | string | Optional. “Doing business as” |
address | Address | Address of the business |
phone | Phone | Phone of the business |
stateOfIncorporation | string | Two letters representing a US state |
ein | string | Business EIN (numbers only) |
entityType | string | One of "Corporation" or "LLC" |
contact | BusinessContact | Primary contact of the business |
tags | object | See tags. Inherited from the application tags- see tag inheritance. |
Relationships
Name | Type | Description |
---|---|---|
org | JSON:API Relationship | The Org of the business |
application | JSON:API Relationship | The Application that created this business |
DepositAccount
Example DepositAccount Resource:
{
"type": "depositAccount",
"id": "1",
"attributes": {
"createdAt": "2000-05-11T10:19:30.409Z",
"name": "Peter Parker",
"depositProduct": "checking",
"routingNumber": "812345678",
"accountNumber": "1000000002",
"currency": "USD",
"balance": 10000,
"hold": 0,
"available": 10000,
"tags": {
"purpose": "checking"
}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "45555"
}
}
}
}
DepositAccount
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the deposit account resource |
type | string | Type of the resource, the value is always depositAccount |
attributes | JSON Object | JSON object representing the deposit account data |
relationships | JSON:API Relationships | Describes relationships between the deposit account resource and the customer |
Attributes
Name | Type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the resource was created |
name | string | Name of the account holder |
depositProduct | string | The name of the deposit product |
routingNumber | string | Routing number of account |
accountNumber | string | Account number, together with the routingNumber forms the identifier of the account on the ACH network |
currency | string | Currency of the account. |
balance | integer | The balance amount (in cents) |
hold | integer | The hold amount (in cents) |
available | integer | The available balance for spending (in cents) |
tags | object | See tags |
Note: the currency is currently always set to USD
. The balance is represented in cents.
Relationships
Name | Type | Description |
---|---|---|
customer | JSON:API Relationship | The customer |
IndividualDebitCard
Example IndividualDebitCard resource:
{
"type": "individualDebitCard",
"id": "8",
"attributes": {
"createdAt": "2020-05-13T09:07:47.645Z",
"last4Digits": "1234",
"expirationDate": "2022-05",
"shippingAddress": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"status": "Active"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "2"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "2"
}
}
}
}
IndividualDebitCard
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the card resource |
type | string | Type of the card resource. For individual debit card the value is always individualDebitCard |
attributes | JSON Object | JSON object representing the card data |
relationships | JSON:API Relationships | Describes relationships between the card resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the resource was created |
last4Digits | string | Last 4 digits of the debit card. |
expirationDate | string | Card expiration date, formatted YYYY-MM , e.g "2020-05" . |
shippingAddress | Address | Optional shipping address, if specified. |
status | string | Status of the card, one of: Active , Inactive , Stolen , Lost , Frozen , ClosedByCustomer |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The account the card belongs to |
customer | JSON:API Relationship | The individual or business customer the card belongs to |
BusinessDebitCard
Example BusinessDebitCard resource:
{
"type": "businessDebitCard",
"id": "9",
"attributes": {
"createdAt": "2020-05-13T09:42:21.857Z",
"last4Digits": "2074",
"expirationDate": "2022-05",
"shippingAddress": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"phone": {
"countryCode": "1",
"number": "1555555578"
},
"email": "richard@piedpiper.com",
"dateOfBirth": "2001-08-10",
"ssn": "123456789",
"status": "Active"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1"
}
},
"customer": {
"data": {
"type": "businessCustomer",
"id": "1"
}
}
}
}
BusinessDebitCard
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the card resource |
type | string | Type of the card resource. For business debit card the value is always BusinessDebitCard |
attributes | JSON Object | JSON object representing the card data |
relationships | JSON:API Relationships | Describes relationships between the card resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the resource was created |
last4Digits | string | Last 4 digits of the debit card. |
expirationDate | string | Card expiration date, formatted YYYY-MM , e.g "2020-05" . |
shippingAddress | Address | Optional shipping address, if specified. |
ssn | string | SSN of the card holder (numbers only). Either an SSN or a passport number is required |
passport | string | Passport number of the card holder (numbers only). Either an SSN or a passport is required |
nationality | ISO31661-Alpha2 string | Only when Passport is populated. Two letters representing the card holder nationality. (e.g. “US”) |
fullName | FullName | Full name of the card holder |
dateOfBirth | RFC3339 string | Date of birth of the card holder (e.g. "2001-08-10" ) |
address | Address | Address of the card holder |
phone | Phone | Phone of the card holder |
string | Email address of the card holder | |
status | string | Status of the card, one of: Active , Inactive , Stolen , Lost , Frozen , ClosedByCustomer |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | Account the card belong to |
customer | JSON:API Relationship | Holder of the account |
IndividualVirtualDebitCard
Example IndividualVirtualDebitCard resource:
{
"type": "individualVirtualDebitCard",
"id": "8",
"attributes": {
"createdAt": "2020-05-13T09:07:47.645Z",
"last4Digits": "1234",
"expirationDate": "2022-05",
"status": "Active"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "2"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "2"
}
}
}
}
IndividualVirtualDebitCard
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the card resource |
type | string | Type of the card resource. For individual virtual debit card the value is always individualVirtualDebitCard |
attributes | JSON Object | JSON object representing the card data |
relationships | JSON:API Relationships | Describes relationships between the card resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the resource was created |
last4Digits | string | Last 4 digits of the debit card. |
expirationDate | string | Card expiration date, formatted YYYY-MM , e.g "2020-05" . |
status | string | Status of the card, one of: Active , Inactive , Stolen , Lost , Frozen , ClosedByCustomer |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The account the card belongs to |
customer | JSON:API Relationship | The individual or business customer the card belongs to |
BusinessVirtualDebitCard
Example BusinessVirtualDebitCard resource:
{
"type": "businessVirtualDebitCard",
"id": "9",
"attributes": {
"createdAt": "2020-05-13T09:42:21.857Z",
"last4Digits": "2074",
"expirationDate": "2022-05",
"address": {
"street": "5230 Newell Rd",
"street2": null,
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
},
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"phone": {
"countryCode": "1",
"number": "1555555578"
},
"email": "richard@piedpiper.com",
"dateOfBirth": "2001-08-10",
"ssn": "123456789",
"status": "Active"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1"
}
},
"customer": {
"data": {
"type": "businessCustomer",
"id": "1"
}
}
}
}
BusinessVirtualDebitCard
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the card resource |
type | string | Type of the card resource. For business virtual debit card the value is always businessVirtualDebitCard |
attributes | JSON Object | JSON object representing the card data |
relationships | JSON:API Relationships | Describes relationships between the card resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the resource was created |
last4Digits | string | Last 4 digits of the debit card. |
expirationDate | string | Card expiration date, formatted YYYY-MM , e.g "2020-05" . |
ssn | string | SSN of the card holder (numbers only). Either an SSN or a passport number is required |
passport | string | Passport number of the card holder (numbers only). Either an SSN or a passport is required |
nationality | ISO31661-Alpha2 string | Only when Passport is populated. Two letters representing the card holder nationality. (e.g. “US”) |
fullName | FullName | Full name of the card holder |
dateOfBirth | RFC3339 string | Date of birth of the card holder (e.g. "2001-08-10" ) |
address | Address | Address of the card holder |
phone | Phone | Phone of the card holder |
string | Email address of the card holder | |
status | string | Status of the card, one of: Active , Inactive , Stolen , Lost , Frozen , ClosedByCustomer |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | Account the card belong to |
customer | JSON:API Relationship | Holder of the account |
ACH Counterparty
Example Payment resource:
{
"type": "achCounterparty",
"id": "8",
"attributes": {
"createdAt": "2020-05-13T09:07:47.645Z",
"name": "Joe Doe",
"routingNumber": "123456789",
"accountNumber": "123",
"accountType": "Checking",
"type": "Person",
"permissions": "CreditOnly"
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "111111"
}
}
}
}
Counterparty
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the ACH counterparty resource |
type | string | Type of the ACH counterparty resource |
attributes | JSON Object | JSON object representing the payment resource |
relationships | JSON:API Relationships | Describes relationships between the ACH counterparty and the originating customer |
Attributes
Name | Type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the resource was created |
name | string | The account holder's name (whether an individual or a business) |
routingNumber | string | Valid 9-digit ABA routing transit number |
accountNumber | string | Bank account number |
accountType | string | Either Checking or Savings |
type | string | Either Business , Person or Unknown |
permissions | string | Either CreditOnly or CreditAndDebit |
Relationships
Name | Type | Description |
---|---|---|
customer | JSON:API Relationship | The customer the counterparty belongs to |
ACH Payment
Example Payment resource:
{
"data": {
"type": "achPayment",
"id": "50",
"attributes": {
"createdAt": "2020-01-13T16:01:19.346Z",
"status": "Pending",
"counterparty": {
"routingNumber": "812345678",
"accountNumber": "12345569",
"accountType": "Checking",
"name": "Jane Doe"
},
"description": "ACH PMNT",
"direction": "Credit",
"amount": 10000
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "555"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "99823"
}
},
"counterparty": {
"data": {
"type": "counterparty",
"id": "4567"
}
},
"transaction": {
"data": {
"type": "transaction",
"id" : "4003"
}
}
}
}
}
Payment
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the ACH payment resource |
type | string | Type of the payment resource. For originations the value is achPayment |
attributes | JSON Object | JSON object representing the payment resource |
relationships | JSON:API Relationships | Describes relationships between the ACH payment and the originating deposit account and customer |
Attributes
Name | Type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the resource was created |
status | string | One of Pending , Rejected , Clearing , Sent , Canceled , Returned . See ACH Status. |
reason | string | (Optional) More information about the status |
counterparty | Counterparty | The party on the other side of the ACH payment |
direction | string | The direction in which the funds flow (either Debit or Credit ) |
description | string | Transaction description (maximum of 50 characters) |
amount | string | The amount (cents) of the payment |
tags | object | See tags |
Relationships
Name | Type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account originating the transfer |
customer | JSON:API Relationship | The Customer the deposit account belongs to. The customer is either a business or a individual |
counterparty | JSON:API Relationship | The Counterparty the payment to be made to |
Originated ACH Transaction
Example OriginatedAchTransaction resource:
{
"type": "originatedAchTransaction",
"id": "1",
"attributes": {
"createdAt": "2020-09-06T07:51:02.570Z",
"direction": "Credit",
"amount": 10000,
"balance": 10000,
"summary": "Counterparty: Unit Inc | Description: ACH PYMT",
"description": "ACH PYMT",
"counterparty": {
"name": "Unit Inc",
"routingNumber": "812345678",
"accountNumber": "1",
"accountType": "Checking"
}
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10001"
}
},
"customer": {
"data": {
"type": "customer",
"id": "3"
}
},
"payment": {
"data": {
"type": "payment",
"id": "5"
}
}
}
}
OriginatedAchTransaction
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the transaction resource |
type | string | Type of the transaction resource. The value is always originatedAchTransaction |
attributes | JSON Object | JSON object representing the transaction data |
relationships | JSON:API Relationships | Describes relationships between the transaction resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the transaction was created. Common to all transaction types. |
direction | string | The direction in which the funds flow. Common to all transaction types. |
amount | number | The amount (cents) of the transaction. Common to all transaction types. |
balance | number | The account balance (cents) after the transaction. Common to all transaction types. |
summary | string | Summary of the transaction. Common to all transaction types. |
description | string | Transaction description |
counterparty | Counterparty | The party on the other end of the transaction |
tags | object | See tags. Inherited from the payment tags- see tag inheritance. |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
payment | JSON:API Relationship | The payment belonging to this transaction |
Received ACH Transaction
Example ReceivedAchTransaction resource:
{
"type": "receivedAchTransaction",
"id": "4",
"attributes": {
"createdAt": "2020-09-08T12:41:43.360Z",
"direction": "Debit",
"amount": 80000,
"balance": 90000,
"summary": "Company: Unit Inc | Description: Payment from Unit Inc.",
"description": "Payment from Unit Inc.",
"companyName": "Unit Inc",
"counterpartyRoutingNumber": "812345678"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "1"
}
},
"customer": {
"data": {
"type": "customer",
"id": "3"
}
}
}
}
ReceivedAchTransaction
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the transaction resource |
type | string | Type of the transaction resource. The value is always receivedAchTransaction |
attributes | JSON Object | JSON object representing the transaction data |
relationships | JSON:API Relationships | Describes relationships between the transaction resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the transaction was created. Common to all transaction types. |
direction | string | The direction in which the funds flow. Common to all transaction types. |
amount | number | The amount (cents) of the transaction. Common to all transaction types. |
balance | number | The account balance (cents) after the transaction. Common to all transaction types. |
summary | string | Summary of the transaction. Common to all transaction types. |
description | string | Transaction description |
companyName | string | The name by which the originator is known to the receiver |
counterpartyRoutingNumber | string | The routing number of the party that originated the ACH payment |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
Returned ACH Transaction
Example ReturnedAchTransaction resource:
{
"type": "returnedAchTransaction",
"id": "4",
"attributes": {
"createdAt": "2020-09-08T12:41:43.360Z",
"direction": "Debit",
"amount": 1000,
"balance": 9000,
"summary": "Return due to: NoAccount | Counterparty: Unit Inc",
"companyName": "Unit Inc",
"counterpartyName": "Unit Inc",
"counterpartyRoutingNumber": "812345678",
"reason": "NoAccount"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "1"
}
},
"customer": {
"data": {
"type": "customer",
"id": "3"
}
},
"payment": {
"data": {
"type": "payment",
"id": "1"
}
}
}
}
ReturnedAchTransaction
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the transaction resource |
type | string | Type of the transaction resource. The value is always returnedAchTransaction |
attributes | JSON Object | JSON object representing the transaction data |
relationships | JSON:API Relationships | Describes relationships between the transaction resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the transaction was created. Common to all transaction types. |
direction | string | The direction in which the funds flow. Common to all transaction types. |
amount | number | The amount (cents) of the transaction. Common to all transaction types. |
balance | number | The account balance (cents) after the transaction. Common to all transaction types. |
summary | string | Summary of the transaction. Common to all transaction types. |
companyName | string | The name by which the originator is known to the receiver |
counterpartyName | string | The name of the party that originated the ACH payment |
counterpartyRoutingNumber | string | The routing number of the party that originated the ACH payment |
reason | string | The reason for the transaction return |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
payment | JSON:API Relationship | The returned payment |
Returned Received ACH Transaction
Example ReturnedReceivedAchTransaction resource:
{
"type": "returnedReceivedAchTransaction",
"id": "4",
"attributes": {
"createdAt": "2020-09-08T12:41:43.360Z",
"direction": "Debit",
"amount": 1000,
"balance": 500,
"summary": "Returned received ACH transaction #55 due to: InsufficientFunds",
"companyName": "John Doe",
"reason": "InsufficientFunds"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "1"
}
},
"customer": {
"data": {
"type": "customer",
"id": "3"
}
},
"returned": {
"data": {
"type": "transaction",
"id": "55"
}
}
}
}
The transaction is used to return a received ACH, automatically by Unit (e.g insufficient funds) or by a dispute.
ReturnedReceivedAchTransaction
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the transaction resource |
type | string | Type of the transaction resource. The value is always returnedAchTransaction |
attributes | JSON Object | JSON object representing the transaction data |
relationships | JSON:API Relationships | Describes relationships between the transaction resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the transaction was created. Common to all transaction types. |
direction | string | The direction in which the funds flow. Common to all transaction types. |
amount | number | The amount (cents) of the transaction. Common to all transaction types. |
balance | number | The account balance (cents) after the transaction. Common to all transaction types. |
summary | string | Summary of the transaction. Common to all transaction types. |
companyName | string | The name by which the originator is known to the receiver |
reason | string | The reason for the transaction return |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
returned | JSON:API Relationship | The returned transaction. |
Book Transaction
Example BookTransaction resource:
{
"type": "bookTransaction",
"id": "9547",
"attributes": {
"createdAt": "2020-07-05T15:49:36.864Z",
"direction": "Credit",
"amount": 1000,
"balance": 12000,
"summary": "Counterparty: Jane Smith | Description: Gift",
"counterparty": {
"name": "Jane Smith",
"routingNumber": "812345678",
"accountNumber": "10039",
"accountType": "Checking"
}
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "10035"
}
},
"customer": {
"data": {
"type": "customer",
"id": "5"
}
},
"counterpartyAccount": {
"data": {
"type": "account",
"id": "10036"
}
},
"counterpartyCustomer": {
"data": {
"type": "customer",
"id": "7"
}
}
}
}
BookTransaction
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the transaction resource |
type | string | Type of the transaction resource. The value is always bookTransaction |
attributes | JSON Object | JSON object representing the transaction data |
relationships | JSON:API Relationships | Describes relationships between the transaction resource and other resources (account and customer) |
tags | object | See tags. Inherited from the payment tags- see tag inheritance. |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the transaction was created. Common to all transaction types. |
direction | string | The direction in which the funds flow. Common to all transaction types. |
amount | number | The amount (cents) of the transaction. Common to all transaction types. |
balance | number | The account balance (cents) after the transaction. Common to all transaction types. |
summary | string | Summary of the transaction. Common to all transaction types. |
counterparty | Counterparty | The party on the other end of the transaction |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
counterpartyAccount | JSON:API Relationship | The account of the counterparty |
counterpartyCustomer | JSON:API Relationship | The counterparty customer |
Purchase Transaction
Example PurchaseTransaction resource:
{
"type": "purchaseTransaction",
"id": "51",
"attributes": {
"createdAt": "2020-09-08T12:41:43.360Z",
"direction": "Debit",
"amount": 2500,
"balance": 10523,
"summary": "Car rental",
"cardLast4Digits": "2282",
"merchant": {
"name": "Europcar Mobility Group",
"type": 3381,
"category": "EUROP CAR",
"location": "Cupertino, CA"
},
"coordinates": {
"longitude": -77.0364,
"latitude": 38.8951
}
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10001"
}
},
"customer": {
"data": {
"type": "customer",
"id": "3"
}
}
}
}
PurchaseTransaction
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the transaction resource |
type | string | Type of the transaction resource. The value is always purchaseTransaction |
attributes | JSON Object | JSON object representing the transaction data |
relationships | JSON:API Relationships | Describes relationships between the transaction resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the transaction was created. Common to all transaction types. |
direction | string | The direction in which the funds flow. Common to all transaction types. |
amount | number | The amount (cents) of the transaction. Common to all transaction types. |
balance | number | The account balance (cents) after the transaction. Common to all transaction types. |
summary | string | Summary of the transaction. Common to all transaction types. |
cardLast4Digits | string | The last 4 digits of the debit card involved in the transaction. |
merchant.name | string | The name of the merchant |
merchant.type | integer | The 4-digit ISO 18245 merchant category code (MCC) |
merchant.category | string | The merchant category, described by the MCC code (see this reference for the list of category descriptions) |
merchant.location | string | Optional. The location (city, state, etc.) of the merchant |
coordinates | Coordinates | Optional. Coordinates (latitude, longitude) of where the purchase took place |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
ATM Transaction
Example AtmTransaction resource:
{
"type": "atmTransaction",
"id": "1432",
"attributes": {
"createdAt": "2020-07-05T15:49:36.864Z",
"direction": "Credit",
"amount": 10000,
"balance": 12000,
"summary": "ATM deposit",
"cardLast4Digits": "2282",
"atmName": "First National Bank",
"atmLocation": "Masontown, PA 15461"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "1000"
}
}
}
}
AtmTransaction
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the transaction resource |
type | string | Type of the transaction resource. The value is always atmTransaction |
attributes | JSON Object | JSON object representing the transaction data |
relationships | JSON:API Relationships | Describes relationships between the transaction resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the transaction was created. Common to all transaction types. |
direction | string | The direction in which the funds flow. Common to all transaction types. |
amount | number | The amount (cents) of the transaction. Common to all transaction types. |
balance | number | The account balance (cents) after the transaction. Common to all transaction types. |
summary | string | Summary of the transaction. Common to all transaction types. |
cardLast4Digits | string | The last 4 digits of the debit card involved in the transaction. |
atmName | string | The name of the ATM |
atmLocation | string | Optional. The location (city, state, etc.) of the ATM |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
Fee Transaction
Example FeeTransaction resource:
{
"type": "feeTransaction",
"id": "388",
"attributes": {
"createdAt": "2020-09-08T12:41:43.360Z",
"direction": "Debit",
"amount": 10,
"balance": 89980,
"summary": "Payment fee for transaction #4"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10001"
}
},
"customer": {
"data": {
"type": "customer",
"id": "3"
}
},
"relatedTransaction": {
"data": {
"type": "transaction",
"id": "4"
}
}
}
}
FeeTransaction
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the transaction resource |
type | string | Type of the transaction resource. The value is always feeTransaction |
attributes | JSON Object | JSON object representing the transaction data |
relationships | JSON:API Relationships | Describes relationships between the transaction resource and other resources (account, customer and relatedTransaction) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the transaction was created. Common to all transaction types. |
direction | string | The direction in which the funds flow. Common to all transaction types. |
amount | number | The amount (cents) of the transaction. Common to all transaction types. |
balance | number | The account balance (cents) after the transaction. Common to all transaction types. |
summary | string | Summary of the transaction. Common to all transaction types. |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
relatedTransaction | JSON:API Relationship | Optional. The transaction which the fee is subject to |
Card Reversal Transaction
Example CardReversalTransaction resource:
{
"type": "cardReversalTransaction",
"id": "401",
"attributes": {
"createdAt": "2020-09-14T12:41:43.360Z",
"direction": "Debit",
"amount": 10,
"balance": 89980,
"summary": "Reversal for transaction #400",
"cardLast4Digits": "2282"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10001"
}
},
"customer": {
"data": {
"type": "customer",
"id": "1001"
}
},
"relatedTransaction": {
"data": {
"type": "transaction",
"id": "400"
}
}
}
}
CardReversalTransaction
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the transaction resource |
type | string | Type of the transaction resource. The value is always cardReversalTransaction |
attributes | JSON Object | JSON object representing the transaction data |
relationships | JSON:API Relationships | Describes relationships between the transaction resource and other resources (account, customer and relatedTransaction) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the transaction was created. Common to all transaction types. |
direction | string | The direction in which the funds flow. Common to all transaction types. |
amount | number | The amount (cents) of the transaction. Common to all transaction types. |
balance | number | The account balance (cents) after the transaction. Common to all transaction types. |
summary | string | Summary of the transaction. Common to all transaction types. |
cardLast4Digits | string | The last 4 digits of the debit card involved in the transaction. |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
relatedTransaction | JSON:API Relationship | Optional. The transaction which the reversal is related to |
Card Transaction
Example CardTransaction resource:
{
"type": "cardTransaction",
"id": "410",
"attributes": {
"createdAt": "2020-09-20T12:41:43.360Z",
"direction": "Debit",
"amount": 10,
"balance": 89480,
"summary": "Card transaction details",
"cardLast4Digits": "2282"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10001"
}
},
"customer": {
"data": {
"type": "customer",
"id": "1001"
}
}
}
}
CardTransaction
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the transaction resource |
type | string | Type of the transaction resource. The value is always cardTransaction |
attributes | JSON Object | JSON object representing the transaction data |
relationships | JSON:API Relationships | Describes relationships between the transaction resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
createdAt | RFC3339 Date string | The date the transaction was created. Common to all transaction types. |
direction | string | The direction in which the funds flow. Common to all transaction types. |
amount | number | The amount (cents) of the transaction. Common to all transaction types. |
balance | number | The account balance (cents) after the transaction. Common to all transaction types. |
summary | string | Summary of the transaction. Common to all transaction types. |
cardLast4Digits | string | The last 4 digits of the debit card involved in the transaction. |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account of the customer |
customer | JSON:API Relationship | The customer the deposit account belongs to. The customer is either a business or a individual |
Statement
Example Statement resource:
{
"type": "statement",
"id": "1",
"attributes": {
"period": "2020-07"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "1000"
}
},
"customer": {
"data": {
"type": "customer",
"id": "1"
}
}
}
}
Statement
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the statement resource |
type | string | Type of the statement resource. The value is always statement |
attributes | JSON Object | JSON object representing the statement data |
relationships | JSON:API Relationships | Describes relationships between the statement resource and other resources (account and customer) |
Attributes
Field | type | Description |
---|---|---|
period | string | Period of the statement, formatted YYYY-MM , e.g "2020-05" . |
Relationships
Field | type | Description |
---|---|---|
account | JSON:API Relationship | The account for which the statement was produced |
customer | JSON:API Relationship | The individual or business customer the account belongs to |
BatchRelease
Example BatchRelease resource:
{
"type": "batchRelease",
"id": "100123",
"attributes": {
"amount": 3000,
"description": "Gift",
"senderName": "Sherlock Holmes",
"senderAccountNumber": "4581133972",
"senderAddress": {
"street": "221B Baker Street",
"city": "London",
"postalCode": "NW1 6XE",
"country": "UK"
}
},
"relationships": {
"batchAccount": {
"data": {
"type": "batchAccount",
"id": "10104"
}
},
"receiver": {
"data": {
"type": "depositAccount",
"id": "10097"
}
}
}
}
BatchRelease
is a JSON:API resource, top-level fields:
Field | type | Description |
---|---|---|
id | string | Identifier of the batch-release resource |
type | string | Type of the batch-release resource. The value is always batchRelease |
attributes | JSON Object | JSON object representing the batch-release data |
relationships | JSON:API Relationships | Describes relationships between the batch-release resource and other resources (accounts) |
Attributes
Name | Type | Description |
---|---|---|
amount | integer | The amount (in cents) to move from the batch account to the receiver account |
description | string | Description of the payment |
senderName | string | Name of the sender, before combining the payments |
senderAddress | Address | Address of the sender |
senderAccountNumber | string | Unique identifier to monitor for similar sending accounts, could be the BIN + last four digits of the card number OR a unique identifier generated by you for the sender |
Relationships
Name | Type | Description |
---|---|---|
batchAccount | JSON:API Relationship | The batch account to release the funds from. |
receiver | JSON:API Relationship | The account to release the funds to. |
Types
FullName
Example FullName type:
{
"first": "Peter",
"last": "Parker"
}
Field | Type | Description |
---|---|---|
first | string | Individual first name |
last | string | Individual last name |
Address
Example Address type:
{
"street": "20 Ingram St",
"street2": "Apt #10",
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
}
Field | Type | Description |
---|---|---|
street | string | First line of an address |
street2 | string | Optional. Second line of an address |
city | string | City |
state | string | Two letters representing the state. Only required for US addresses |
postalCode | string | Postal code |
country | ISO31661-Alpha2 string | Two letters representing the country |
Phone
Example Phone type:
{
"countryCode": "1",
"number": "15555555"
}
Field | Type | Description |
---|---|---|
countryCode | string | Country code of the phone number, e.g. "1" for US |
number | string | The phone number without the country code, e.g. "4151193497" |
Officer
Example Officer type:
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"dateOfBirth": "2001-08-10",
"ssn": "721074426",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555"
},
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
}
Field | Type | Description |
---|---|---|
status | string | One of Approved , Denied or PendingReview |
fullName | FullName | Full name of the officer |
title | string | One of CEO , COO , CFO or President |
ssn | string | SSN of the officer (numbers only). One of ssn or passport is required |
passport | string | Passport of the officer (numbers only). One of ssn or passport is required |
nationality | ISO31661-Alpha2 string | Only when Passport is populated. Two letters representing the officer's nationality |
dateOfBirth | RFC3339 string | e.g. "2001-08-10" |
address | Address | The officer's address |
phone | Phone | The officer's phone number |
string | The officer's email address |
BeneficialOwner
Example BeneficialOwner type:
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"dateOfBirth": "2001-08-10",
"ssn": "721074426",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555"
},
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303",
"country": "US"
}
}
Field | Type | Description |
---|---|---|
status | string | One of Approved , Denied or PendingReview |
fullName | FullName | Full name of the beneficial owner |
ssn | string | SSN of the officer (numbers only). One of ssn or passport is required |
passport | string | Passport of the beneficial owner (numbers only). One of ssn or passport is required |
nationality | ISO31661-Alpha2 string | Only when Passport is populated. Two letters representing the beneficial owner's nationality |
dateOfBirth | RFC3339 string | e.g. "2001-08-10" |
address | Address | The beneficial owner's address |
phone | Phone | The beneficial owner's phone number |
string | The beneficial owner's email address | |
percentage | string | The beneficial owner percentage of ownership at the bussiness |
BusinessContact
Example BusinessContact type:
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555"
}
}
Field | Type | Description |
---|---|---|
fullName | FullName | Full name of the contact |
string | The contact's email address | |
phone | Phone | The contact's phone number |
AuthorizedUser
Example AuthorizedUser type:
{
"fullName": {
"first": "Richard",
"last": "Hendricks"
},
"username":"richard",
"email": "richard@piedpiper.com",
"phone": {
"countryCode": "1",
"number": "5555555"
}
}
Field | Type | Description |
---|---|---|
fullName | FullName | Full name of the authorized user |
username | string | The authorized user's username |
string | The authorized user's email address | |
phone | Phone | The authorized user's phone number. This number will be used for One Time Password (OTP) authentication |
Counterparty
Example Counterparty type:
{
"counterparty": {
"routingNumber": "812345678",
"accountNumber": "12345569",
"accountType": "Checking",
"name": "Jane Doe"
}
}
Field | Type | Description |
---|---|---|
routingNumber | string | Valid 9-digit ABA routing transit number |
accountNumber | string | Bank account number |
accountType | string | Either Checking or Savings |
name | string | Name of the person or company that owns the bank account |
Coordinates
Example Coordinates type:
{
"longitude": -77.0364,
"latitude": 38.8951
}
Field | Type | Description |
---|---|---|
longitude | number | The longitude value |
latitude | number | The latitude value |