Settlement Instruments

This object represents a bank account belonging to an investor. Peach will settle payment proceed into that account.

Create settlement instrument

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
companyId
required
string

The unique company identifier.

investorId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Unique investor indentifier.

Request Body schema: application/json
isExternal
boolean

A payment instrument marked isExternal=true is not verified and creates transactions for record purposes only. The payment.instrument:external permission is required to set this flag.

externalId
string or null non-empty

A lender's identifier for the instrument.

After the object is successfully created, a lender can use id or externalId identifiers to fetch the object.

To fetch the object using externalId you need to add ext- to the URL.

Note: Don't add ext- to the identifier value. For example: if the external identifier is ABCDE, then pass externalId=ACBCE and NOT ext-ABCDE when creating the object.

pendingAt
string or null <date-time>

The date and time at which the instrument was set to pending.

failureReason
string or null

The transaction failure reason.

Enum: "insufficientFunds" "chargeback" "accountClosed" "invalidAccount" "unknownReason" "invalidCvv" "invalidExpirationDate" "avsFailed" "networkError" "cardDeclined" "accountFrozen" "deceased" "invalidRouting" "paymentStopped" "microdepositsFailed" "microdepositsAttemptFailed" "incorrectNumber" "fraudulent" "unauthorizedDebit"
status
string
Default: "pending"

Status of the instrument. Can only be set if isExternal=true.

  • active - the instument can be charged.
  • pending - the instrument is pending to be verified.
  • inactive - the instrument is not active and cannot be charged.
Enum: "active" "inactive" "pending"
inactiveReason
string

The reason the instrument is inactive. Required when setting status=inactive.

Enum: "fraudAlert" "updated" "notVerified" "expired" "failed" "deleted"
nickname
string

A nickname for the instrument. The nickname can be displayed in UI.

instrumentType
required
string
Value: "bankAccount"
accountNumber
required
string^[0-9]+$

The account number. If isExternal=true then only the last four digits of the account number can be provided.

routingNumber
required
string

The routing number.

accountType
required
string

Type of the account.

Enum: "checking" "savings"
accountHolderType
required
string

Type of entity that is the account holder.

Enum: "business" "personal"
accountHolderName
required
string

For personal accounts, the full name of the account holder. For business accounts, the business name.

This is not an account nickname. It should match the name on file for the account with the bank.

object

An object representing a link with a third party vendor (e.g. Plaid) that allows fetching additional account details.

Responses
201

Settlement Instrument Created

post/companies/{companyId}/investors/{investorId}/settlement-instruments
Request samples
application/json
{
  • "isExternal": true,
  • "externalId": "string",
  • "pendingAt": "2019-08-24T14:15:22Z",
  • "failureReason": "insufficientFunds",
  • "status": "active",
  • "inactiveReason": "fraudAlert",
  • "verified": false,
  • "nickname": "string",
  • "instrumentType": "bankAccount",
  • "accountNumber": "string",
  • "routingNumber": "string",
  • "accountType": "checking",
  • "accountHolderType": "business",
  • "accountHolderName": "string",
  • "accountLink": {
    }
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Get settlement instruments

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
companyId
required
string

The unique company identifier.

investorId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Unique investor indentifier.

Responses
200

Settlement Instruments

get/companies/{companyId}/investors/{investorId}/settlement-instruments
Response samples
application/json
{
  • "count": 0,
  • "data": [
    ]
}

Get settlement instrument by ID

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
companyId
required
string

The unique company identifier.

investorId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Unique investor indentifier.

settlementInstrumentId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Unique settlement instrument identifier. Normally a bank account.

Responses
200

Payment Instrument

get/companies/{companyId}/investors/{investorId}/settlement-instruments/{settlementInstrumentId}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Update settlement instrument

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
companyId
required
string

The unique company identifier.

investorId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Unique investor indentifier.

settlementInstrumentId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Unique settlement instrument identifier. Normally a bank account.

Request Body schema: application/json
status
string
Default: "pending"

Status of the instrument. Can only be set if isExternal=true.

  • active - the instument can be charged.
  • pending - the instrument is pending to be verified.
  • inactive - the instrument is not active and cannot be charged.
Enum: "active" "inactive" "pending"
inactiveReason
string

The reason the instrument is inactive. Required when setting status=inactive.

Enum: "fraudAlert" "updated" "notVerified" "expired" "failed" "deleted"
nickname
string

A nickname for the instrument. The nickname can be displayed in UI.

accountType
string

Type of the account.

Enum: "checking" "savings"
accountHolderType
string

Type of entity that is the account holder.

Enum: "business" "personal"
accountHolderName
string

For personal accounts, the full name of the account holder. For business accounts, the business name.

This is not an account nickname. It should match the name on file for the account with the bank.

object

An object representing a link with a third party vendor (e.g. Plaid) that allows fetching additional account details.

Responses
204

Settlement Instrument Updated

put/companies/{companyId}/investors/{investorId}/settlement-instruments/{settlementInstrumentId}
Request samples
application/json
{
  • "status": "active",
  • "inactiveReason": "fraudAlert",
  • "verified": false,
  • "nickname": "string",
  • "accountType": "checking",
  • "accountHolderType": "business",
  • "accountHolderName": "string",
  • "accountLink": {
    }
}