Peach Finance

Funding Instruments

Create funding instrument

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
companyId
required
string

The unique company identifier.

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

The payment processor ID.

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.

Responses
201

Funding Instrument Created

post/companies/{companyId}/payment-processors/{paymentProcessorId}/funding-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": {
    }
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Get funding instruments

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
companyId
required
string

The unique company identifier.

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

The payment processor ID.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 25

The maximum count of results to retrieve.

startingAfter
string

Return results starting after the provided object identifier.

endingBefore
string

Return results ending before the provided object identifier.

Responses
200

Funding Instruments

get/companies/{companyId}/payment-processors/{paymentProcessorId}/funding-instruments
Response samples
application/json
{
  • "status": 0,
  • "count": 0,
  • "data": [
    ]
}

Get funding instrument by ID

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
companyId
required
string

The unique company identifier.

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

The payment processor ID.

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

Unique funding instrument identifier. Normally a bank account.

Responses
200

Payment Instrument

get/companies/{companyId}/payment-processors/{paymentProcessorId}/funding-instruments/{fundingInstrumentId}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Update funding instrument

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
companyId
required
string

The unique company identifier.

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

The payment processor ID.

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

Unique funding 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

Funding Instrument Updated

put/companies/{companyId}/payment-processors/{paymentProcessorId}/funding-instruments/{fundingInstrumentId}
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 Employees

Request sandbox access