Skip to main content

Add your client's payment details

In order to pay out to your clients without creating a limited DDA bank account in their name, you need to add them as a Recipient. A recipient is a way to represent anyone you want to make a payment to. The type of recipient you need to create for this pathway is a SETTLEMENT_ACCOUNT .

Use the /recipients resource to add your client's bank account as the only possible recipient of funds paid out from your platform in their name.

You can use the POST /recipients endpoint to add a single recipient account that belongs to your client.

Table of mandatory recipient fields

To ensure your client's account can receive payments, you must provide:

  • Party type - individual or business
  • First name
  • Last name
  • Business name (if this is a business account)
  • Country code
  • Account type - checking or savings
  • Bank code type - always USABA

Add a recipient

Once you have the required details, you can send the request. You must include in the request:

  • partyDetails - the object containing the personal details of your client. 
  • account - the object containing the settlement account details. 
  • type - must be SETTLEMENT_ACCOUNT.

Sample POST /recipients request:

Json
{
    "partyDetails": {
    "address": {
    "addressLine1": "251 N Bristol Ave",
    "addressLine2": null,
    "addressLine3": null,
    "city": "Los Angeles",
    "countryCode": "US",
    "state": "ND",
    "postalCode": "58008"
    },
    "type": "INDIVIDUAL",
    "firstName": "Philip",
    "lastName": "Banks",
    "businessName": "Banks Family Bungalows",
    "contacts": [
    {
    "contactType": "PHONE",
    "countryCode": "+1",
    "value": "7606810558"
    }
    ]
    },
    "account": {
        "number": "322270521",
        "type": "CHECKING",
        "routingInformation": [
        {
            "transactionType": "ACH",
            "routingCodeType": "USABA",
            "routingNumber": "028000024"
        }
        ],
        "countryCode": "US"
    },
    "type": "SETTLEMENT_ACCOUNT"
}

Sample response - including Account Validation Service (AVS) response that you receive only if using AVS:

Json
{
    "id": "828be449-8507-4a5e-ad3f-62202af0f2b3",
    "partyDetails": {
        "address": {
                "addressType": null,
                "addressLine1": "251 N Bristol Ave",
                "addressLine2": null,
                "addressLine3": null,
                "city": "Los Angeles",
                "countryCode": "US",
                "state": "ND",
                "postalCode": "58008"
        },
        "type": "INDIVIDUAL",
        "firstName": "Philip",
        "lastName": "Banks",
        "businessName": "Banks Family Bungalows",
        "contacts": [
            {
                "contactType": "PHONE",
                "countryCode": "+1",
                "value": "7606810558"
            }
        ]
    },
    "partyId": null,
    "account": {
        "number": "322270521",
        "type": "CHECKING",
        "routingInformation": [
            {
                "transactionType": "ACH",
                "routingCodeType": "USABA",
                "routingNumber": "028000024"
            }
        ],
        "countryCode": "US"
    },
    "type": "SETTLEMENT_ACCOUNT",
    "status": "ACTIVE",
    "clientId": null,
    "createdAt": "2024-05-02T13:46:51.352485Z",
    "updatedAt": "2024-05-02T13:46:51.352488Z",
    "accountValidationResponse": [
        {
        "requestId": "257de3c8-49e4-49b4-8702-4bbf47337c88",
        "profileName": null,
        "responses": [
        {
            "codes": {
                "error": null,
                "verification": {
                    "code": 1002,
                    "message": "Open Valid"
                },
                "authentication": {
                    "code": 5002,
                    "message": "Ownership Match"
                },
                "verificationMicroDeposit": null,
                "authenticationMicroDeposit": null
            },
            "provider": "EWS",
            "details": {
                "accountNumber": "XXXXXXXX521",
                "financialInstitutionId": {
                "clearingSystemId": {
                "id": "028000024",
                "idType": "ABA"
              }
            }
          }
        }
      ]
      }
    ]
}

Add a recipient with multiple transaction methods

When you set up a settlement account for your client, you must ensure that all required information is provided to enable ACH payments. This includes ACH routing numbers.

If you wish to use wire transfers or RTP (Real Time Payments) methods, you may need to include additional details about the recipient, as well as additional routing codes.

At a glance, the minimum details of a settlement account holder for each payment type are:

  • Wire transfer:
    • Individual or business name.
    • Country code.
    • Address including City, State, Postal Code.
    • Routing and account numbers.
  • ACH or direct payment:
    • Individual or business name.
    • Country code.
    • Routing and account numbers.
    • Account type (Checking or Savings).
  • Real Time Payments (RTP):
    • Individual or business name.
    • Country code.
    • Routing and account numbers.

Routing Numbers

A settlement account can have between 1-3 different routing numbers for ACH, Wire and RTP payments respectively. You can represent routing numbers and related information in the routingInformation object. Each routing number consists of:

  • transactionType - the type of transaction. This can be RTP, ACH or WIRE
  • routingCodeType - always USABA.
  • routingNumber - the routing number for this payment type.

Update routing information for a settlement account

You may need to update details about a settlement account to allow additional payment methods, such as wire or RTP transactions. You can update details about a recipient using POST /recipients/{id}. In the payload, you only need to include the object you wish to update.

In this example, a new wire and RTP routing numbers are added to a settlement account:

Json
{
"account": {
      "number": "0182119492",
      "type": "CHECKING",
      "routingInformation": [
         {
            "routingNumber": "122199983",
            "transactionType": "ACH",
            "routingCodeType": "USABA"
          }, {
            "routingNumber": "021000021",
            "transactionType": "WIRE",
            "routingCodeType": "USABA"
        }, {
            "routingNumber": "021000021",
            "transactionType": "RTP",
            "routingCodeType": "USABA"
         }
      ],
      "countryCode": "US" 
} 
}

Sample response: 

Json
{
  "id": "1c5cda4a-16eb-4e9d-b384-6b8299893c27",
  "partyDetails": {
    "address": {
      "addressType": null,
      "addressLine1": "49479 Sanford Fields",
      "addressLine2": "Kayden Drive",
      "addressLine3": "Rose House",
      "city": "Newyork",
      "state": "AL",
      "postalCode": "87109",
      "countryCode": "US"
    },
    "type": "ORGANIZATION",
    "firstName": null,
    "lastName": null,
    "businessName": "Test EP - Simonis - Kulas - QAT",
    "contacts": [
      {
        "contactType": "WEBSITE",
        "countryCode": null,
        "value": "http://ruby.biz"
      }
    ]
  },
  "partyId": "3455326201",
  "account": {
    "number": "0182119492",
    "type": "CHECKING",
    "routingInformation": [
      {
        "routingNumber": "021000021",
        "transactionType": "RTP",
        "routingCodeType": "USABA"
      },
      {
        "routingNumber": "021000021",
        "transactionType": "WIRE",
        "routingCodeType": "USABA"
      },
      {
        "routingNumber": "122199983",
        "transactionType": "ACH",
        "routingCodeType": "USABA"
      }
    ],
    "countryCode": "US"
  },
  "type": "LINKED_ACCOUNT",
  "status": "ACTIVE",
  "clientId": "2545701795",
  "createdAt": "2024-11-27T16:00:58.842406Z",
  "updatedAt": "2024-11-27T16:00:58.842417Z",
  "accountValidationResponse": null
}

Verify a settlement account with AVS

If you are onboarded to Account Validation Service (AVS) and you have requested that your AVS details are used for your implementation in thie pathway of Embedded Payments, a verification process is triggered when you add a settlement account.

The verification details are passed on to you in responses to POST /recipients and GET /recipients/{id} APIs so that you can decide for yourself what the recipient status should be.

The recipient status always defaults to "ACTIVE". It is up to you to update it once you have evaluated the AVS verification payload. If you want to proceed with this account, you can leave the status as "ACTIVE".

If you want to reject this account, you can update the status of a recipient using POST /recipients/{id}:

Json
{
   "status": "REJECTED"
}

Show a list of recipients

You can display a list of recipients using a GET /recipients request.

In your request, you can specify the type of recipients you wish to view. Passing no value in type will result in both recipients and settlement accounts being returned. In this example, the request is for external accounts only:

Curl
curl -X 'GET' \
  'https://base-url/api/v1/eb/recipients?limit=25&page=0&type=SETTLEMENT_ACCOUNT' \
  -H 'accept: application/json' \
  -H 'platform_id: 0030000131'

This returns a list of basic information about existing recipients:

Json
{
  "page": 1,
  "limit": 30,
  "total_items": 1,
  "recipients": [
    {
      "partyId": "616d93a1-ce53-4c71-b03b-02a11396db28",
      "partyDetails": {
        "address": {
          "addressLine1": "90 Bedford Street",
          "addressLine2": "Apt 2E",
          "addressLine3": null,
          "city": "New York",
          "countryCode": "US",
          "state": "NY",
          "postalCode": "10014"
        },
        "type": "INDIVIDUAL",
        "firstName": "Monica",
        "lastName": "Gellar",
        "contacts": [
          {
            "contactType": "PHONE",
            "countryCode": "+1",
            "value": "6316215110"
          }
        ]
      },
      "account": {
        "number": "0182119492",
        "type": "CHECKING",
        "routingInformation": [
           {
              "transactionType": "ACH",
              "routingCodeType": "USABA",
              "routingNumber": "322270521"
           }
        ],
        "countryCode": "US"
      },
      "id": "616d93a1-ce53-4c71-b03b-02a11396db28",
      "type": "SETTLEMENT_ACCOUNT",
       "accountValidationResponse": [
          {
             "requestId": "81950670-d6b3-4fbb-bcce-20169d7a85d3",
             "profileName": "verificationauth",
             "responses": [
                {
                   "codes": {
                      "error": null,
                      "verification": {
                         "code": 1002,
                         "message": "Open valid"
                      },
                      "authentication": {
                         "code": 5002,
                         "message": "Ownership Match"
                      },
                      "verificationMicroDeposit": null,
                      "authenticationMicroDeposit": null
                   },
                   "provider": "EWS",
                   "details": {
                      "accountNumber": "XXXXXXXX052",
                      "financialInstitutionId": {
                         "clearingSystemId": {
                            "id": 987654321,
                            "idType": "ABA"
                         }
                      }
                   }
                }
             ]
          }
       ]
    }
  ]
}

Show more details about a recipient

For more information about a specific recipient, use GET /recipients/{id}.

Curl
  'https://base-url/api/v1/eb/recipients/dea21834-f876-404b-a240-9977e598da5e' \
  -H 'accept: application/json' \
  -H 'platform_id: 0005191231' \

This returns the detailed information about settlement account:

Json
    {
   "partyDetails": {
      "address": {
         "addressLine1": "90 Bedford Street",
         "addressLine2": "Apt 2E",
         "addressLine3": null,
         "city": "New York",
         "countryCode": "US",
         "state": "NY",
         "postalCode": "10014"
      },
      "type": "INDIVIDUAL",
      "firstName": "Monica",
      "lastName": "Gellar",
      "contacts": [
         {
            "contactType": "PHONE",
            "countryCode": "+1",
            "value": "6316215110"
         }
      ]
   },
   "account": {
      "number": "0182119492",
      "type": "CHECKING",
      "routingInformation": [
         {
            "transactionType": "ACH",
            "routingCodeType": "USABA",
            "routingNumber": "322270521"
         }
      ],
      "countryCode": "US"
   },
   "partyId": "616d93a1-ce53-4c71-b03b-02a11396db28",
   "id": "616d93a1-ce53-4c71-b03b-02a11396db28",
   "type": "SETTLEMENT_ACCOUNT",
   "status": "ACTIVE",
   "accountValidationResponse": [
      {
         "requestId": "81950670-d6b3-4fbb-bcce-20169d7a85d3",
         "profileName": "verificationauth",
         "responses": [
            {
               "codes": {
                  "error": null,
                  "verification": {
                     "code": 1002,
                     "message": "Open valid"
                  },
                  "authentication": {
                     "code": 5002,
                     "message": "Ownership Match"
                  },
                  "verificationMicroDeposit": null,
                  "authenticationMicroDeposit": null
               },
               "provider": "EWS",
               "details": {
                  "accountNumber": "XXXXXXXX052",
                  "financialInstitutionId": {
                     "clearingSystemId": {
                        "id": 987654321,
                        "idType": "ABA"
                     }
                  }
               }
            }
         ]
      }
   ]
}

Remove/replace a settlement account

Your client can only have one settlement account operational at any given time. If your client wants to change the external account they receive payments into, you must first change the status of the existing settlement account to  "INACTIVE".

You can update the status of a settlement account with a request to POST /recipients/{id}, with only the status field populated:

Json
{
"status": "INACTIVE"
}

You can then add a new settlement account in using the method described in this documentation.

References

Table of mandatory recipient fields

Mandatory recipient fields
Mandatory recipient fields Required by Payment types
Recipient type (Individual or Business) All
First name All if recipient is an individual
Last name All if recipient is an individual
Business name All if recipient is a business
Address line 1 Wire only
City Wire only
State Wire only
County Wire only
Country code All
Account type (checkings or savings) ACH only
Recipient type All - either a settlement account that belongs to the client, or a recipient they want to pay.

The following parameters are used in the Recipients resource: 

Recipients resource query parameters:
Query parameter Description Format Example
clientId Unique client identifier. <= 10 characters 0030000132
type Recipient type to return. Enum: "RECIPIENT" / "LINKED_ACCOUNT / SETTLEMENT_ACCOUNT" RECIPIENT
limit

Number of records per page.

  • Defaults to 25.
 [1 .. 25] 25
page

Page number.

  • Defaults to zero.
 >=0 2
number Demand deposit account number. <=35 characters 0182119492
account.type

Type of bank account (checking or savings).

  • Only required for ACH payments.
  • Exclude field from payload completely if not needed.
 Enum: "CHECKING" / "SAVINGS" CHECKING
countryCode

Two letter country code.

  • Only "US" is supported at this time.
 "US" US
id A unique identifier for a recipient 32 characters 5e64a59d650842cfbabd4efd1f4d1556
routingCodeType

Type of routing code.

  • Only "USABA" is currently supported.
 "USABA" USABA
routingNumber

Routing number corresponding to the routing code.

  • Only "USABA" compliant routing numbers are currently supported.
 9 digits 541798298
addressType Type of address (e.g., 'Primary Residence' | 'Principal place of business').   Primary Residence
addressLine 1 Must not be a PO Box and must begin with a number. <=34 characters  90 Bedford Street
addressLine 2   <=34 characters  Apt 2E
addressLine 3   <=34 characters   
city   <=34 characters  New York
state State code in alpha-2 format. <=30 characters NY
postalCode Postal/ZIP code. <=10 characters 10014
countryCode

Two letter country code based on ISO 3166 standard.

  • Only "US" is currently supported.
   US
partyDetails.type   Enum: "INDIVIDUAL" / "ORGANIZATION" INDIVIDUAL
firstName

Recipient's first name.

  • Mandatory for recipient type INDIVIDUAL.
 <=70 characters Monica
lastName

Recipient's last name.

  • Mandatory for recipient type INDIVIDUAL.
 <=70 characters Gellar
businessName

Recipient company name.

  • Mandatory for recipient type ORGANIZATION.
 <=140 characters Company Inc
contactType Type of contact information being provided. Enum: "EMAIL" / "WEBSITE" / PHONE" PHONE
countryCode E.164 format compatible telephone country code. <=3 digits +1
value

Contact information corresponding to contactType:

  • PHONE (E.164-compliant telephone number (excluding country code)) 
  • EMAIL (addr-spec in Section 3.4 of RFC 5322)
  • WEBSITE (URL starting with http:// or https://)
 [ 1 .. 2048 ] characters 6316215110
recipientId A unique identifier for a recipient. 32 characters 5e64a59d650842cfbabd4efd1f4d1556