Peach Finance

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 (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Unique investor identifier.

Request Body schema: application/json
required
createdAt
string <date-time>
updatedAt
string or null <date-time>
deletedAt
string or null <date-time>
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.

pendingAt
string or null <date-time>

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

failureReason
string (TransactionFailureReason)

The transaction failure reason.

Enum: "insufficientFunds" "chargeback" "accountClosed" "invalidAccount" "unknownReason" "invalidCvv" "invalidExpirationDate" "avsFailed" "networkError" "cardDeclined" "accountFrozen" "deceased" "invalidRouting" "paymentStopped" "microdepositsFailed" "microdepositsAttemptFailed" "incorrectNumber" "fraudulent" "unauthorizedDebit"
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.

status
string
Default: "pending"

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

Statuses:

  • active - the instrument can be charged.
  • pending - the instrument is pending to be verified.
  • inactive - the instrument is not active and cannot be charged.

When updating this field, only the following state transitions are allowed.

active --> inactive
pending --> active (only for payment instrument with isExternal=true)
pending --> inactive (only for payment instrument with isExternal=true)
inactive --> active (only for payment instrument with isExternal=true)
inactive --> pending (only for payment instrument with isExternal=true)

Note: if you update the status from inactive to active or pending, the system will clear the following attributes: inactiveReason, deletedAt, failureReason, failureDescriptionShort, failureDescriptionLong.

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

institutionName
string

The name of the financial institution where this account resides. If empty, will default to the name associated with the routing number.

object (AccountLink)

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

accountNumber
required
string^[0-9]+$

The account number. If isExternal=true then the last two, three, or four digits of the account number can be provided. Provide four digits if available, otherwise provide two or three digits.

Responses
201

Settlement Instrument Created

post/companies/{companyId}/investors/{investorId}/settlement-instruments
Request samples
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "isExternal": true,
  • "pendingAt": "2019-08-24T14:15:22Z",
  • "failureReason": "insufficientFunds",
  • "externalId": "string",
  • "status": "active",
  • "inactiveReason": "fraudAlert",
  • "verified": false,
  • "nickname": "string",
  • "instrumentType": "bankAccount",
  • "routingNumber": "string",
  • "accountType": "checking",
  • "accountHolderType": "business",
  • "accountHolderName": "string",
  • "institutionName": "string",
  • "accountLink": {
    },
  • "accountNumber": "string"
}
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 (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Unique investor identifier.

Responses
200

Settlement Instruments

get/companies/{companyId}/investors/{investorId}/settlement-instruments
Response samples
application/json
{
  • "status": 0,
  • "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 (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Unique investor identifier.

settlementInstrumentId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[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 (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Unique investor identifier.

settlementInstrumentId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Unique settlement instrument identifier. Normally a bank account.

Request Body schema: application/json
required
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.

status
string
Default: "pending"

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

Statuses:

  • active - the instrument can be charged.
  • pending - the instrument is pending to be verified.
  • inactive - the instrument is not active and cannot be charged.

When updating this field, only the following state transitions are allowed.

active --> inactive
pending --> active (only for payment instrument with isExternal=true)
pending --> inactive (only for payment instrument with isExternal=true)
inactive --> active (only for payment instrument with isExternal=true)
inactive --> pending (only for payment instrument with isExternal=true)

Note: if you update the status from inactive to active or pending, the system will clear the following attributes: inactiveReason, deletedAt, failureReason, failureDescriptionShort, failureDescriptionLong.

Enum: "active" "inactive" "pending"
inactiveReason
string

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

Enum: "fraudAlert" "updated" "notVerified" "expired" "failed" "deleted"
verified
boolean
Default: false

Indicates whether the instrument has been verified.

User must have the payment.instrument:skip.verification permission to set this value to true, or the payment instrument must be marked isExternal=true.

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.

institutionName
string

The name of the financial institution where this account resides. If empty, will default to the name associated with the routing number.

object (AccountLink)

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
{
  • "externalId": "string",
  • "status": "active",
  • "inactiveReason": "fraudAlert",
  • "verified": false,
  • "nickname": "string",
  • "accountType": "checking",
  • "accountHolderType": "business",
  • "accountHolderName": "string",
  • "institutionName": "string",
  • "accountLink": {
    }
}
➔ Next to Loan Tape Types