Skip to main content

Payments: 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

Attributes#

NameTypeDescription
namestringThe account holder's name (whether an individual or a business).
routingNumberstringValid 9-digit ABA routing transit number.
accountNumberstringBank account number.
accountTypestringEither Checking or Savings.
typestringEither Business, Person or Unknown.
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": "011000138",      "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": "011000138",      "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

VerbPOST
Urlhttps://api.s.unit.sh/counterparties
Required Scopecounterparties-write
Data TypeachCounterparty

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 the name of the counterparty, if the name verification fails the request will fail with code field set to NameVerificationFailed.
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"    },    "relationships": {      "customer": {        "data": {          "type": "customer",          "id": "111111"        }      }    }  }}'

Delete#

Delete a counterparty resource by id.

VerbDELETE
Urlhttps://api.s.unit.sh/counterparties/{id}
Required Scopecounterparties

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

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

List#

List counterparties. Filtering and paging can be applied.

VerbGET
Urlhttps://api.s.unit.sh/counterparties
Required Scopecounterparties

Query Parameters#

NameTypeDefaultDescription
page[limit]integer100Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Number of resources to skip. See Pagination.
filter[customerId]string(empty)Optional. Filters the results by the specified customer id.
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

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

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": "011000138",      "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 the name of the counterparty.
  • 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.