Skip to main content

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.

VerbPOST
Urlhttps://api.s.unit.sh/counterparties
Required Scopecounterparties-write
Data TypeachCounterparty
Timeout (Seconds)5

Attributes

NameTypeDescription
namestringThe account holder's name (whether an individual or a business, maximum of 50 characters).
routingNumberstringValid 9-digit ABA routing transit number.
accountNumberstringBank account number.
accountTypestring(defaults to checking). Either Checking, Savings or Loan.
typestringEither Business, Person or Unknown.
tagsobjectOptional. See Tags.
permissionsstringOptional, 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.
idempotencyKeystringOptional. 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

NameTypeDescription
customerJSON:API RelationshipThe 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

FieldTypeDescription
dataACH CounterpartyThe 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

VerbPOST
Urlhttps://api.s.unit.sh/counterparties
Required Scopecounterparties-write
Data TypeachCounterparty
Timeout (Seconds)5

Attributes

NameTypeDescription
typestringEither Business, Person or Unknown
namestringThe account holder's name (whether an individual or a business).
plaidProcessorTokenstringPlaid integration token
See Plaid processor token
verifyNamebooleanOptional, 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.
permissionsstringOptional, custom counterparty permissions. Either CreditOnly, DebitOnly, CreditAndDebit. Default is CreditAndDebit.
tagsobjectOptional. See Tags.
idempotencyKeystringOptional. 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

NameTypeDescription
customerJSON:API RelationshipThe 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

FieldTypeDescription
dataACH CounterpartyThe 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.

VerbDELETE
Urlhttps://api.s.unit.sh/counterparties/{id}
Required Scopecounterparties
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.

VerbGET
Urlhttps://api.s.unit.sh/counterparties/{id}
Required Scopecounterparties
Timeout (Seconds)5

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataACH CounterpartyCounterparty 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.

VerbGET
Urlhttps://api.s.unit.sh/counterparties/{id}/balance
Required Scopecounterparties
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

FieldTypeDescription
dataCounterparty BalanceCounterparty 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.

VerbGET
Urlhttps://api.s.unit.sh/counterparties
Required Scopecounterparties
Timeout (Seconds)5

Query Parameters

NameTypeDefaultDescription
page[limit]integer100Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Optional. 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
sortstringsort=createdAtOptional. 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

FieldTypeDescription
dataArray of ACH CounterpartyArray 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.

VerbPATCH
Urlhttps://api.s.unit.sh/counterparties/:counterpartyId
Required Scopecounterparties-write
Timeout (Seconds)5

Attributes

NameTypeDescription
plaidProcessorTokenstringOptional, unless updating a Plaid counterparty. Plaid integration token
See Plaid processor token
verifyNamebooleanOptional, default to false. Verify the name of the counterparty, if the name verification fails the request will fail with code field set to NameVerificationFailed.
permissionsstringOptional, custom counterparty permissions. Either CreditOnly, DebitOnly, CreditAndDebit.
tagsobjectOptional. 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

FieldTypeDescription
dataACH CounterpartyThe target resource after the operation was completed.
metaJSON object that contains pagination dataPagination 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

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