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, 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#

Creates a 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).
routingNumberstringValid 9-digit ABA routing transit number.
accountNumberstringBank account number.
accountTypestring(defaults to checking). Either Checking or Savings.
typestringEither Business, Person or Unknown.
tagsobjectOptional. See Tags.
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.

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.

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"        }      }    }  }}'

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": "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"        }      }    }  }}

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[tags]Tags (JSON)(empty)Optional. Filter Counterparties by Tags.
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"          }        }      }    }  ]}

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
plaidProcessorTokenstringPlaid 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.
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.