Embedded Payments

Add payment details for bulk payouts and collection

You can make bulk payouts either to your platform’s own accounts or to an external party on behalf of your client. Similarly, you can collect funds from your platform account or from an external party for your client.

To do this, you must add yourself , client or the external party as a recipient. For this pathway, the recipient type should be SETTLEMENT_ACCOUNT.

Note

This is the exclusive method for platforms to register recipients for payouts or collections.

Use the POST /recipients endpoint to add your account, your client’s bank account, or an external party as the designated recipient for funds paid out from your platform in their name. The types of transactions available are ACH, Wire, Real-Time Payment (RTP) and Push to Card (P2C).

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 and 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
Push to Card (P2C):
- Individual or business name
- Country code (US only)
- Complete address including city, state and postal code
- Cardholder name (max 30 characters, alphabetic and spaces only, no special characters)
- 16-digit debit card number (numeric only, no spaces)
- Card expiration date (YYMM format)

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

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 (ACH, Wire, and RTP):

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 POST /recipients request (P2C):

Json

{
  "partyDetails": {
    "address": {
      "addressLine1": "200 C Park West",
      "addressLine2": "Apt. 777",
      "city": "Tampa",
      "state": "FL",
      "postalCode": "33647",
      "countryCode": "US"
    },
    "type": "INDIVIDUAL",
    "firstName": "Mary",
    "lastName": "Sheen",
    "contacts": [
      {
        "contactType": "PHONE",
        "countryCode": "+1",
        "value": "8137771122"
      },
      {
        "contactType": "EMAIL",
        "value": "MSheen@info.com"
      }
    ]
  },
  "card": {
    "name": "MARY K SHEEN",
    "pan": "16digitcardnumber",
    "expiryDate": "2603"
  },
  "type": "RECIPIENT",
  "clientId": "1000010400"
}

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

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 the 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 are doing validation on the settlement accounts you created, you must ensure that all required information is provided to enable ACH payments. This includes ACH routing numbers.

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

Json

<TBD>

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

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	Wires and P2C only
City	Wires and P2C only
State	Wires and P2C only
Postal code	P2C 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.
Cardholder name	P2C only
16-digit debit card number	P2C only
Card expiration date	P2C only

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
`cardholderName`	Cardholder name as it appears on the debit card. Required for P2C payments. Alphabetic characters and spaces only — no special characters allowed.	<=30 characters	Monica Gellar
`cardNumber`	16-digit debit card number. Required for P2C payments. Numeric only, no spaces or special characters.	16 digits	4111111111111111
`cardExpirationDate`	Expiration date of the debit card. Required for P2C payments. Must be in YYMM format.	YYMM	2709