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 scopes. However, we do recommend selecting the payments-write-counterparty scope, which allows making payments to a 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

Creates an ACH counterparty for a specific customer.

Verb	`POST`
Url	`https://api.s.unit.sh/counterparties`
Required Scope	`counterparties-write`
Data Type	`achCounterparty`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
name	string	The account holder's name (whether an individual or a business, maximum of 50 characters).
routingNumber	string	Valid 9-digit ABA routing transit number.
accountNumber	string	Bank account number.
accountType	string	(defaults to checking). Either `Checking`, `Savings` or `Loan`.
type	string	Either `Business`, `Person` or `Unknown`.
tags	object	Optional. See Tags.
permissions	string	Optional, custom counterparty permissions. Only `DebitOnly` or `CreditAndDebit` are valid values when using the permissions' attribute. 'CreditOnly' will be assigned as defualt value when permissions attribute is not declared. If the account and rounting number of the counterparty belong to an account under your org on Unit, you may specify "CreditAndDebit" or "DebitOnly" permissions as well.
idempotencyKey	string	Optional. See Idempotency.

info

The 'accountType' field should be collected from the customer. If the accountType provided to Unit is incorrect, the payment might still be processed, or you may receive a return.

Relationships

Name	Type	Description
customer	JSON:API Relationship	The customer that the counterparty belongs to.

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": "011000133",
      "accountNumber": "123",
      "accountType": "Checking",
      "type": "Person"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "111111"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	ACH Counterparty	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "achCounterparty",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "name": "Joe Doe",
      "routingNumber": "011000133",
      "bank": "Bank Of America",
      "accountNumber": "123",
      "accountType": "Checking",
      "type": "Person",
      "permissions": "CreditOnly"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "111111"
        }
      }
    }
  }
}

Create Counterparty with Plaid token

Creates a counterparty for a specific customer.

info

For more information on using Plaid, please read Unit's Plaid partnership guide

Verb	`POST`
Url	`https://api.s.unit.sh/counterparties`
Required Scope	`counterparties-write`
Data Type	`achCounterparty`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
type	string	Either `Business`, `Person` or `Unknown`
name	string	The account holder's name (whether an individual or a business).
plaidProcessorToken	string	Plaid integration token See Plaid processor token
verifyName	boolean	Optional, default to false. Verify a match between the `name` of the counterparty and the name of the external account's owner as provided by Plaid. If the name verification fails the request will fail with `code` field set to `NameVerificationFailed`.
permissions	string	Optional, custom counterparty permissions. Either `CreditOnly`, `DebitOnly`, `CreditAndDebit`. Default is `CreditAndDebit`.
tags	object	Optional. See Tags.
idempotencyKey	string	Optional. See Idempotency.

note

Unit is using a fuzzy name-match algorithm for name verification, which is not always accurate, because of that we include the counterparty account owners in the error returned under meta.owners. You can use that information to implement a manual review process.

Relationships

Name	Type	Description
customer	JSON:API Relationship	The customer that the counterparty belongs to.

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": "Sherlock Holmes",
      "plaidProcessorToken": "processor-5a62q307-ww0a-6737-f6db-pole26004556",
      "type": "Person",
      "permissions": "DebitOnly"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "111111"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	ACH Counterparty	The target resource after the operation was completed.

408 Request Timeout

The request to Plaid has timed-out, probably because of a technical issue with the counterparty bank. You might want to retry the request without the verifyName flag.

409 Conflict

The counterparty with specified Plaid token already exists. existingIds of the duplicate entries are specified in the response message.

Example Conflict Response:
{
  "errors": [
    {
      "title": "Already Exists",
      "status": "409",
      "details": "Counterparty with such name already exists",
      "detail": "Counterparty with such name already exists",
      "meta": {
        "existingIds": [
          "49",
          "51"
        ],
        "supportId": "b99998b8-aaaa-47467-b8c8-c14467777999"
      }
    }
  ]
}

Delete

Delete a counterparty resource by id.

Verb	`DELETE`
Url	`https://api.s.unit.sh/counterparties/{id}`
Required Scope	`counterparties`
Timeout (Seconds)	`5`

Response

204 No Content

curl -X DELETE 'https://api.s.unit.sh/counterparties/1' \
-H "Authorization: Bearer ${TOKEN}"

Get by Id

Get a counterparty resource by id.

Verb	`GET`
Url	`https://api.s.unit.sh/counterparties/{id}`
Required Scope	`counterparties`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	ACH Counterparty	Counterparty resource.

curl -X GET 'https://api.s.unit.sh/counterparties/:counterpartyId' \
-H "Authorization: Bearer ${TOKEN}"

Get Counterparty Balance By Id

Get a counterparty resource by id.

note

Counterparty must be created with Plaid Processor token in order to run this request.
The external account balance will only be returned if customer is the owner of the counterparty account.

Verb	`GET`
Url	`https://api.s.unit.sh/counterparties/{id}/balance`
Required Scope	`counterparties`
Timeout (Seconds)	`120`

curl -X GET 'https://api.s.unit.sh/counterparties/:counterpartyId/balance' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Counterparty Balance	Counterparty Balance resource.

Example Response:
{
  "data": {
    "type": "counterpartyBalance",
    "id": "123456",
    "attributes": {
      "balance": 11000,
      "available": 10000
    },
    "relationships": {
      "counterparty": {
        "data": {
          "type": "counterparty",
          "id": "123456"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "8"
        }
      }
    }
  }
}

List

List counterparties. Filtering and paging can be applied.

Verb	`GET`
Url	`https://api.s.unit.sh/counterparties`
Required Scope	`counterparties`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Optional. Number of resources to skip. See Pagination.
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id.
filter[accountNumber]	string	(empty)	Optional. Filters the results by the specified account number.
filter[routingNumber]	string	(empty)	Optional. Filters the results by the specified routing number.
filter[tags]	Tags (JSON)	(empty)	Optional. Filter Counterparties by Tags.
filter[permissions][]	string	(empty)	Optional. Filters the results by the specified counterparty permissions either `CreditOnly`, `DebitOnly`, `CreditAndDebit`. Usage example: filter[permissions][0]=CreditOnly&filter[permissions][1]=CreditAndDebit
sort	string	`sort=createdAt`	Optional. `sort=createdAt` for ascending order or `sort=-createdAt` (leading minus sign) for descending order.

curl -X GET 'https://api.s.unit.sh/counterparties?page[limit]=20&page[offset]=0' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of ACH Counterparty	Array of counterparty resources.

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"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "limit": 20,
      "offset": 0
    }
  }
}

Update Counterparty

Update a Counterparty. Relink existing counterparty with a new Plaid processor token.

Verb	`PATCH`
Url	`https://api.s.unit.sh/counterparties/:counterpartyId`
Required Scope	`counterparties-write`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
plaidProcessorToken	string	Optional, unless updating a Plaid counterparty. Plaid integration token See Plaid processor token
verifyName	boolean	Optional, default to false. Verify the name of the counterparty, if the name verification fails the request will fail with `code` field set to `NameVerificationFailed`.
permissions	string	Optional, custom counterparty permissions. Either `CreditOnly`, `DebitOnly`, `CreditAndDebit`.
tags	object	Optional. See Tags.

Update a counterparty:
curl -X PATCH 'https://api.s.unit.sh/counterparties/:counterpartyId'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "counterparty",
    "attributes": {
      "plaidProcessorToken": "processor-sandbox-b14ad1fd-3398-46a8-a316-5bf574fc2459"
    },
    "permissions": "CreditOnly"
  }
}'

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	ACH Counterparty	The target resource after the operation was completed.
meta	JSON object that contains pagination data	Pagination data includes offset, limit and total (estimated total items).

Example Response:
{
  "data": {
    "type": "achCounterparty",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "name": "Joe Doe",
      "routingNumber": "011000133",
      "bank": "Bank Of America",
      "accountNumber": "123",
      "accountType": "Checking",
      "type": "Person",
      "permissions": "CreditOnly"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "111111"
        }
      }
    }
  }
}

Account Funding

Account Funding - allowing a customer that just created an account to fund his new account using an external account (account within another bank or institution) owned by the customer.

Unit supports Account Funding by creating a counterparty with Plaid Processor Token and then creating an ACH Debit Payment.

caution

Anything that involves ACH Debit is high risk. The counterparty can claim that an ACH Debit is unauthorized and return it up to 60 days after receiving the ACH Debit. A known fraud is to originate an ACH Debit, wait for the payment to be cleared, spend the entire balance and to then claim that the payment was not authorized.

caution

You should deeply think about your Account Funding limits, per single payment, daily and monthly. Please consult Unit team on the matter.

Verifying the identity and balance

Because Account Funding is high risk, Unit recommends that you would verify the identity and balance of the counterparty using Plaid. Unit supports both of those operations:

Identity - specify true for the verifyName field when creating the counterparty, Unit would use Plaid Identity and a fuzzy name match algorithm to verify a match between the name of the counterparty and the name of the external account's owner.
Balance - specify true for the verifyCounterpartyBalance field when creating the payment, Unit would use Plaid to verify that the counterparty account has sufficient funds.

note

When creating a counterparty for Account Funding purposes, make sure to use the same name as the name of the customer.

How To Fund an Account

Use Plaid Link to allow the customer to provide the account for Account Funding.
Exchange the access token to Unit's processor token.
Create a counterparty with the processor token, name set to the customer name and the verifyName set to true.
Create an ACH Debit Payment, set the verifyCounterpartyBalance to true.
Wait for the payment to be cleared.

Counterparties

Create Counterparty​

Attributes​

Relationships​

Response​

201 Created​

Create Counterparty with Plaid token​

Attributes​

Relationships​

Response​

201 Created​

408 Request Timeout​

409 Conflict​

Delete​

Response​

204 No Content​

Get by Id​

Response​

200 OK​

Get Counterparty Balance By Id​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Update Counterparty​

Attributes​

Response​

200 OK​

Account Funding​

Verifying the identity and balance​

How To Fund an Account​

Create Counterparty

Attributes

Relationships

Response

201 Created

Create Counterparty with Plaid token

Attributes

Relationships

Response

201 Created

408 Request Timeout

409 Conflict

Delete

Response

204 No Content

Get by Id

Response

200 OK

Get Counterparty Balance By Id

Response

200 OK

List

Query Parameters

Response

200 OK

Update Counterparty

Attributes

Response

200 OK

Account Funding

Verifying the identity and balance

How To Fund an Account