Payment Method Edge Cases

There are four edge cases that would trigger a user into a non approved state after submitting KYC information and connecting a bank account.

A user needs to re-submit a piece of initial account information.
User needs to re-submit an ID image
A user needs to submit a Proof of Address
A user needs to submit an ACH authorization form.

1. A user needs to re-submit a piece of initial account information.

This typically happens when a user submit KYC information during the account creation stage and his/her information doesn't match up with the ID that was submitted, incorrect/invalid info provided, such as incorrect DOB, invalid address, misspelled legal name, or SSN/ITIN is needed.

On the API level, after a user submits data, the status of each fieldId in the response object from the get_account endpoint returns back a PENDING status for whichever fieldId that corresponds to the incorrectly input KYC data point.

{
  "id" : "AC-U4BWHGZDG6W",
	...,
	"profileFields" : [ {
    "fieldId" : "individualSsn",
    "fieldType" : "STRING",
    "value" : null,
    "note" : "Please provide a valid social security number.",
    "status" : "OPEN"
  }, {
  ...
  }]
}

There could be a different note for each user action based on each KYC data point.

2. User needs to re-submit an ID image

This typically happens when a user submits an ID that:

isn't legible, blurry image
pictures doesn't encapsulate the entire image, all four corners are not showing
Image doesn't match with the correct initial account KYC data

On the API level, the key/value "fieldId":"individualGovernmentId" will go from PENDING after an image is submitted, back to OPEN if the image is rejected.

{
  "id" : "AC-U4BWHGZDG6W",
	...,
	"profileFields" : [ {
    "fieldId" : "individualGovernmentId",
    "fieldType" : "DOCUMENT",
    "value" : ["DO_B9QJCMN2QBB"],
    "note" : "Document is expired",
    "status" : "OPEN"
  }, {
  ...
  }]
}

It's important to look at the note section of the server response object. The note will give context as to why an image will not work. Other notes include:

Identification needs to be in full color
Identification is blurry/hard to read
Document must include all four corners
Please submit a passport, driver's license or govt. issued identification document
Identification document is not supported

3. A user needs to submit a Proof of Address

This typically happens when a user submits an ID and inputs KYC address data that doesn't match.
A proof of address document such as a:

Utility Bill
Bank Statement

On the API level, the key/value "fieldId":"individualGovernmentId" will go from PENDING after an image is submitted, back to OPEN if the image is rejected.

{
  "id" : "AC-U4BWHGZDG6W",
	...,
	"profileFields" : [{
   "fieldId": "individualGovernmentId"
    "fieldType": "DOCUMENT",
    "value": [DO_B9QJCMN2QB9],
    "note": "Document must include all four corners",
    "status": "OPEN"
 	}, {
  ...
  }]
}

It's important to look at the note section of the server response object. The note will give context as to why an image will not work. Other notes include:

Please provide a translated copy of this document
Utility Bill does not match profile address
Bank Statement does not match profile address
Please provide utility bill that matches profile address
Please provide all pages of Bank statement for verification

4. A user needs to submit an ACH authorization form.

This typically happens when a user submits an ID, inputs KYC data, uploads a bank account payment method and data doesn't match. Examples include:

Does not match the registered legal name
Does not match the registered email
Does not match the registered phone number
Does not match the registered address nor have a valid proof of address on file
Does not have transaction posted in transaction history
Does not have a sufficient balance to cover the transaction

You'll then need to instruct your user to upload a photo of his/her self next to a piece of paper with the following written down:

Once submitted, our team will review and process the information.

Upload Document Endpoint

It is possible to upload missing account documents via the API. The Upload Document endpoint requires the accountId and fieldId: /v3/accounts/:accountId/:fieldId

The response to the account and paymentMethod endpoints will update accordingly during the following states when collecting the ACH form. The account endpoint response will only update if the payment method is the individual source of funds.

When an ACH form has been initially been requested:

//GET /accounts/:accountId

[
	...
  {
  	fieldId: "individualSourceOfFunds",
    fieldType: "PAYMENT_METHOD",
    value: "PM_XXXXX",
    note: "Additional information is required.",
    status: "OPEN"
  }
]

// GET /paymethMethod/PM_XXXXX

{
    ...
    status: "AWAITING_FOLLOWUP",
    waitingPrompts: [{
    	id: "ACH_FORM"
      prompt: "Please upload a picture of yourself with the following written down on a piece of paper next to your face: `Wyre`, today's date, the last 4 digits of your bank account number and your signature.",
  		type: "DOCUMENT"
		}]
}

When an ACH form has been submitted through the upload document for payment method endpoint and is in review:

//GET /accounts/:accountId

[
	...
  {
  	fieldId: "individualSourceOfFunds",
    fieldType: "PAYMENT_METHOD",
    value: "PM_XXXXX",
    note: "Payment method is under review.",
    status: "PENDING"
  }
]

// GET /paymethMethod/PM_XXXXX
{
    ...
    status: "AWAITING_FOLLOWUP",
    waitingPrompts: []
}

When an ACH form has been submitted through the upload documents for payment method endpoint and has been approved:

//GET /accounts/:accountId

[
	...
  {
  	fieldId: "individualSourceOfFunds",
    fieldType: "PAYMENT_METHOD",
    value: "PM_XXXXX",
    note: null,
    status: "APPROVED"
  }
]

// GET /paymethMethod/PM_XXXXX
{
    ...
    status: "APPROVED",
    waitingPrompts: []
}