Peach Finance

Payment Instruments

This object represents a payment method (e.g. bank account, credit card, debit card, etc.) belonging to a borrower.

Create payment instrument

Create a payment instrument.

When creating a payment instrument using the Plaid Account option, two flows are supported:

  1. Pass only accessToken and accountIds. This will create a payment instrument with status=inactive. You can then use Update payment instrument endpoint to set the accountHolderType, and accountHolderName fields, and set the status to active.

  2. Pass the required fields as well as accountHolderType, and accountHolderName. This will create a payment instrument with status=active. The payment instrument will then be ready to use.

Note: This endpoint returns an array containing a single payment instrument to allow future support for Plaid multi-account select.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

query Parameters
force
boolean
Default: false

Overrides the results of BIN / Routing Number lookup. Requires the payment.instrument:force permission.

sync
boolean
Default: false

Make the payment instrument authentication process synchronous. Only relevant for cards.

allowDuplicates
boolean
Default: false

For external payment instruments, skip duplicate checks. Allows the creation two external payment instruments with the same last 4 digits on the same borrower.

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

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.

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 only the last four digits of the account number can be provided.

sendNotice
boolean
Default: true

When set to true, the system will send a paymentMethodAdded notice to the borrower.

Responses
201

Payment Instruments

409

Duplicate instrument

post/people/{personId}/payment-instruments
Request samples
application/json
{
  • "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",
  • "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",
  • "sendNotice": true
}
Response samples
application/json
{
  • "status": 0,
  • "count": 0,
  • "data": [
    ]
}

Get payment instruments

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

query Parameters
isExternal
boolean

Fetch entities that are marked external.

includeDeleted
boolean
Default: false

Include entities that are marked deleted.

showFullAccountNumber
boolean
Default: false

Provide raw untokenized account details: cardNumber for cards, accountNumber for bank accounts, checks, wires, and money orders.

Requires the payment.instrument:read.sensitive permission.

Responses
200

Payment Instruments

get/people/{personId}/payment-instruments
Response samples
application/json
{
  • "status": 0,
  • "count": 0,
  • "data": [
    ]
}

Get payment instrument by ID

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

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

The payment instrument identifier.

query Parameters
showFullAccountNumber
boolean
Default: false

Provide raw untokenized account details: cardNumber for cards, accountNumber for bank accounts, checks, wires, and money orders.

Requires the payment.instrument:read.sensitive permission.

Responses
200

Payment Instrument

get/people/{personId}/payment-instruments/{paymentInstrumentId}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Update payment instrument

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

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

The payment instrument identifier.

query Parameters
sync
boolean
Default: false

Make the payment instrument authentication process synchronous. Only relevant for cards.

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

sendNotice
boolean
Default: true

When set to true, the system will send a paymentMethodUpdated notice to the borrower.

Responses
204

Payment Instrument Updated

put/people/{personId}/payment-instruments/{paymentInstrumentId}
Request samples
application/json
{
  • "externalId": "string",
  • "status": "active",
  • "inactiveReason": "fraudAlert",
  • "verified": false,
  • "nickname": "string",
  • "accountType": "checking",
  • "accountHolderType": "business",
  • "accountHolderName": "string",
  • "institutionName": "string",
  • "accountLink": {
    },
  • "sendNotice": true
}

Delete payment instrument

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

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

The payment instrument identifier.

Responses
204

Payment Instrument Deleted

delete/people/{personId}/payment-instruments/{paymentInstrumentId}

Verify amounts of microdeposits

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

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

The payment instrument identifier.

Request Body schema: application/json
required
deposit1
required
integer
deposit2
required
integer
Responses
204

Success

post/people/{personId}/payment-instruments/{paymentInstrumentId}/verify
Request samples
application/json
{
  • "deposit1": 0,
  • "deposit2": 0
}

Create account link

Add a data vendor link for this payment instrument. If one is already present, it is replaced.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

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

The payment instrument identifier.

Request Body schema: application/json
required
vendor
required
string

The data vendor identifier.

Value: "plaid"
accessToken
required
string

The vendor's access token for initial access. With Plaid, this can be the public_token provided by Plaid Link, or the access_token provided after exchanging the public token.

itemId
string

The vendor's item identifier. With Plaid, this is the item_id.

accountId
required
string

The identifier used to identify an account with the data vendor.

dataServices
Array of strings
Default: ["accountInfo"]

A list of data services available with this link.

Items Enum: "accountInfo" "balance"
status
string

The status of the account link.

Enum: "active" "inactive"
object

The most recent error that occurred while fetching data from this link.

Responses
200

Account Link created

post/people/{personId}/payment-instruments/{paymentInstrumentId}/account-link
Request samples
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Refresh balance data

Fetch updated balance data from the account link associated with this payment instrument.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

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

The payment instrument identifier.

Responses
200

Success

post/people/{personId}/payment-instruments/{paymentInstrumentId}/balance
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Get balance data

Get stored balance data for the account associated with the payment instrument.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

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

The payment instrument identifier.

Responses
200

Success

get/people/{personId}/payment-instruments/{paymentInstrumentId}/balance
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}
➔ Next to Consent