Skip to content
/
Create payment instrument

Create payment instrument

Request

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.

Security
oauth2(Required scopes: payment.instrument:create) or bearerAuth or apiKeyHeader
Path
personIdstring(AnyId)^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+$write-onlyrequired

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

Query
forceboolean

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

Default:false
syncboolean

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

Default:false
allowDuplicatesboolean

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

Default:false
Bodyapplication/jsonrequired
isExternalboolean

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.

pendingAtstring or null, (date-time)

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

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

inactiveReasonstring

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

Enum:"fraudAlert""updated""notVerified""expired""failed""deleted"
nicknamestring

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

statusstring

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.

Default:"pending"
Enum:"active""inactive""pending"
verifiedboolean

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.

Default:false
instrumentTypestringrequired
Value:"bankAccount"
Discriminator
routingNumberstringrequired

The routing number.

accountHolderNamestringrequired

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.

accountHolderTypestringrequired

Type of entity that is the account holder.

Enum:"business""personal"
accountTypestringrequired

Type of the account.

Enum:"checking""savings"
institutionNamestring, <= 36 characters

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

accountNumberstring^[0-9]+$write-onlyrequired

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.

sendNoticeboolean

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

Default:true
POST
/people/{personId}/payment-instruments
curl -i -X POST \
  'https://sandboxapi.peach.finance/api/people/{personId}/payment-instruments?force=false&sync=false&allowDuplicates=false' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "isExternal": true,
    "pendingAt": "2019-08-24T14:15:22Z",
    "externalId": "string",
    "inactiveReason": "fraudAlert",
    "nickname": "string",
    "status": "active",
    "verified": false,
    "instrumentType": "bankAccount",
    "routingNumber": "string",
    "accountHolderName": "string",
    "accountHolderType": "business",
    "accountLink": {
      "accessToken": "string",
      "accountId": "string",
      "dataServices": [
        "accountInfo"
      ],
      "itemId": "string",
      "recentError": {
        "errorCodeByVendor": "string",
        "errorDescriptionBorrower": "string",
        "errorDescriptionInternal": "string",
        "errorType": "retry",
        "errorTypeByVendor": "string"
      },
      "status": "active",
      "vendor": "plaid"
    },
    "accountType": "checking",
    "institutionName": "string",
    "accountNumber": "string",
    "sendNotice": true
  }'

Responses

Payment Instruments

Bodyapplication/json
countinteger, (int32)read-onlyrequired

Total number of items in this result.

statusinteger

HTTP status code.

dataArray of any(PaymentInstrument)required
Response
{
  "count": 0,
  "status": 0,
  "data": [
    { … }
  ]
}