### Thank you for choosing Productfy. We're excited to be your partner in building a world-class product! ###

Productfy’s APIs allow you to embed banking functions within your app. These implementation guides provide step-by-step walk-throughs of the technical integration you’ll need to do as well as context you’ll need to understand for launching and supporting these products. View our entire list of APIs [here](/docs/api).



Introduction

# Overview 
Welcome to Productfy! These are the very first steps you need to take to start integrating your application with the Productfy system. 

# Testing out our public sandbox

You don’t need to be a signed Productfy client to start integrating to our APIs. With just your basic login to this site you have already created a Person ID and Organization ID in Productfy’s public sandbox environment, which you can use to invoke many of our APIs. Feel free to read through our [Implementation Guides](/docs/guides/introduction) and [API docs](/docs/api/introduction) and start coding to our APIs. Have questions? Feel free to send them to support@productfy.io. 

If you aren't a Productfy client yet and are using our public sandbox, make all calls to the standard API endpoints on https://user.api.prod.productfy.io. Follow steps 2 and 3 below around using session keys. 

# Building your Productfy integration

The rest of this guide is written assuming you are (or will be soon) a signed Productfy client. Productfy clients get their own dedicated QA and Production environments to build against. Most functions work in a demo mode in QA, however no real money movement is possible in QA so there are some aspects of the system that are best exercised in production. 

There are 3 aspects of your architecture we assume you will be building outside of Productfy:
- **Database** - We recommend you create your own database to keep track of user IDs and store non-Productfy related data. 
- **Middleware** - We recommend you create your own back-end to call Productfy endpoints. 
- **Authentication** - We assume you are using your own authentication mechanism for your customers to login to your application. NOTE - For fraud prevention reasons, Productfy requires that you implement an industry standard multi-factor authentication solution with your login. 

# How to use these docs
Our [Implementation Guides](/docs/guides/introduction) provide step-by-step walkthroughs of what to know and how to build our major features. Our [API documentation](/docs/api/introduction) provides the entire list of Productfy APIs at your disposal. 
 
# GraphQL Builder

We display specific APIs with links like this below which pop-up our GraphQL Builder interface. 

![IssueVirtualDebitCard.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Issue_Virtual_Debit_Card_033859e63a.png)

In this interface you can view the API specification, explore our data structure to see what data is available and make selections on which fields you want to send in the API call and get returned. As you make these selections GraphQL Builder will automatically build the code for your API call for you. You can copy or export this code to your application, as well as run it against the Productfy environment you are connected to. 

# About GraphQL
If you are used to REST APIs and brand new to GraphQL, we recommend you read up a little on what GraphQL is and how it’s different than REST. Here is a good place to start:

- [https://graphql.org/learn/](https://graphql.org/learn/)
- [https://www.graphql.com/guides/](https://www.graphql.com/guides/)

---

# Step 1 - Obtain Productfy environment URL and environment account

You do not need an API key to integrate with Productfy. Productfy Client Services will provide you with the following when your QA and production environments are set up:

- Custom URL to use to make your API calls against 
- Environment Account (username/password) to authenticate your API calls to the Productfy system. 


# Step 2 - Create session keys for each API call

Productfy requires a valid session key to be passed with any API call. Session keys expire every 20 minutes. Use the API below to retrieve a valid session key. 

The session key will be located in the return of the Login API at this path: **data.logIn.login.sessions[0].sessionKey**. It must be included in the Return Fields section of your GraphQL query, an example query might look like this: 

![logInExampleQuery.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/log_In_Example_Query_7930e66225.png)

Store the session key in your database.
You can choose to implement logic to refresh your session key every <20 minutes, or do it with every thread or every API call. 
If your login is successful you will see the session key in the sessionKey property as shown below:

![loginInExampleReturn.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/login_In_Example_Return_ee270f8ce9.png)

[View Login API](mutation:logIn)

# Step 3 - Use session keys in your API calls

In the body of any of your API calls to Productfy, you must insert the **sessionKey** within the extensions object as shown below:

![GraphQLExportTab.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Graph_QL_Export_Tab_977c6cc4fe.png)

There are two major endpoints to the API:
- **/graphql/api/public** that requires no authentication, this is used for the **logIn** mutation.
- **/graphql/api/authenticated** that requires authentication using a valid session key.

# Step 4 - Create Customers

Productfy supports two different concepts of customers: humans/consumers are created as Person IDs in the Productfy system, and businesses are created as Organization IDs. 

As your customers sign up for your app, you should create Person ID and Organization ID records on Productfy using the following APIs:

[View Create Person API](mutation:createPerson)      [View Create Organization API](mutation:saveCompany)

::alert[Note: the Social Security Number must be unique amongst Person IDs in QA and Production]
::alert[Note, you must set the **Primary** field to **true**, for KYC to work correctly on your person ID]

## Save Address Information

To save an address, you must either provide a google places id or fill out the full standard address. In some cases, a google places id may not exist for an address because it is a new address or is too remote to be included in google maps. In that instance, you must use the **`address`** parameter in the API below and provide the following fields:
- **`address.city`**
- **`address.countryCode`**
- **`address.postalCode`**
- **`address.streetName`**
- **`address.streetNumber`**
- **`address.streetSuffix`**
- **`address.unitNumber`** *(if applicable)*
- **`address.unitType`** *(if applicable)*
- **`address.usTerritory`**

![address_smaller.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/address_smaller_9144351d54.png)

Use one of the following APIs to save the address, depending on whether it's for a person ID or organization ID:

[View Save Person Address API](mutation:personAddress)      [View Save Organization Address API](mutation:organizationAddress) 

## Save Additional Customer Information

You will likely want to save additional demographic information as well (some fields are required for KYC / KYB later on), you can use the following APIs for that:

[View Save Person Information API](mutation:updatePerson)           
[View Save Email Address API](mutation:personEmailAddress) 
[View Save Person Phone Number API](mutation:personPhoneNumber) 
 
Finally, you may want to save custom data fields for your Persons or Organizations. The Productfy system allows that through the following APIs:

[View Save Custom Person Data API](mutation:personKvpData)       [View Save Custom Organization Data API](mutation:organizationKvpData) 

Custom data can later be retrieved using the following APIs:

[Get Custom Person Data API](query:personKvpDataSet)       [Get Custom Organization Data API](query:organizationKvpDataSet)

# Step 5 - Client Portal

When your QA and production environments are created by Productfy, you will be given your own URLs for our client portal that you can use to look up customers and data, configure webhooks, and view reports. 

## Viewing Customer Data

You can click on the Users section to search for Persons or Organizations that you have saved to Productfy. These screens allow you to see the data stored on Productfy.

![portal profile.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/portal_profile_71f70a1d5d.png)

## Viewing Reports

You can click on Reports to view standardized data from the Productfy system. 

# Step 6 - Set up Webhooks

We recommend you setup a webhook listener and subscribe to Productfy webhooks. Productfy will trigger webhooks out to your application when various events happen on the system. These webhooks are useful for you to keep your system updated, or to trigger notifications to your customers. For a full listing of webhooks, see our [Webhook documentation](/docs/api/webhooks). 

To set up webhooks, navigate to the Webhooks menu on your Client Portal URL. Next, click on the Edit Webhook button.
![webhooks1.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/webhooks1_f6bda9acfb.png)

Enter a value for Endpoint URL, which needs to be a publicly accessible and SSL-enabled web server that can listen to webhook messages from Productfy, and then check all the webhook events you are interested in.
![webhooks2.jpeg](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/webhooks2_74d070f829.jpeg)

## Example Request Header

To ensure the webhook came from Productfy we include a unique token value per client in the header, as shown below. Please contact support for your specific token value.

`x-pfy-webhook-token: XXXXXXX`


# Step 7 - Next steps
Congrats! You now have the groundwork in place to build the rest of your Productfy integration. Please check out our other [Implementation Guides](/docs/guides/introduction) that cover our other products and features you may need. If you have questions or need help, feel free to reach out at support@productfy.io . 

Getting Started_color.svg

Start here to connect to Productfy, create customers and learn the platform

Getting Started

![Onboarding Chart.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Onboarding_Chart_03f0da6c12.png)

# Overview

This guide explains our implementation process once a client is signed with Productfy. Our goal is to get clients through the onboarding process as quickly as possible. Depending on what products are being implemented, there are a number of setup tasks that need to be completed either by you, by Productfy engineering, by Productfy compliance, or by our partner bank. You will be assigned a team of onboarding specialists from Productfy to help you through the process. 

# Onboarding project overview
The basic phases of onboarding are as follows:
- Due Diligence
- Platform and Program Setup
- Integration and Launch
  - Certification
  - Alpha
  - Beta
  - General Availability

# What to expect 
## Due Diligence

The first phase of onboarding is to collect your business information to fulfill Know-Your-Business (KYB) requirements, such as Registration Information, Business Description, Beneficial Owners etc. In addition, we'll conduct a thorough review of your program, including the flow of funds. Both of these items will be reviewed by the Productfy Compliance team and the Bank Partner.

## Platform and Program Setup

The Productfy client services, engineering, and compliance teams will help set up the structure of the program, including your QA and Production environments, as well as the Program Disclosures (Cardholder Agreements for example, Both Productfy and our Bank Partner will also review sign off on your UI/UX.

## Integration and Launch

During the integration phase, you will be developing and integrating your solution against our APIs and designing your UI/UX. When the Program Disclosures are available, you'll include those into your UI to Customers can accept the terms of the program. 

## Certification

During the Certification phase, we will ask you to complete a number of integration tests to ensure that your Program is working as designed. This includes funding accounts and performing test transactions.

## Alpha

The Alpha testing phase gives you scope to increase your testing and involve more internal users. You will be able to issue more accounts and debit cards, to make sure your Program is ready for public consumption.

## Beta

Beta is designed to give you flexibility on an initial public rollout. We typically recommend F&F and early waitlisted users. We are here to fully support you during this phase.

## General Availability

Integration, check. Disclosures, check. Initial customer testing, check. You are now ready for prime time! We will support your GA launch and our teams will be ready to help provide any support you need, including our Compliance as a Service function.

# How to get launched quickly
You are in control of a number of things that can help your onboarding process go quickly. Here are some tips and things to watch out for to help save time:
- **Be responsive** - when there are forms or questionnaires to be filled out, the sooner you get those back to us the sooner you can go live.
- **Use Productfy standards** - we try to define standard limits, disclosures and product functionality that fall within legal and compliance boundaries we are used to. While we are open to deviating from our standards in cases where it makes sense, this adds time to the implementation process. 
- **Have a clearly defined product in mind to launch** - A lot of time can be lost if clients are still trying to figure out what their product should be. If at all possible, define a clear ‘minimum viable product’ to launch with, and then implement additional functionality with us in future phases once you have a product in market. 
- **Have polished designs of your application ready to go** - The UI review can extend the timeline if the UI is not fully thought out and a lot of changes are needed. 
- **Start on your technical integration early** - You can start building to our APIs now in our public sandbox. Our engineering support team is available to help answer questions (go to support@productfy.io for help). This will only speed things up when you get your own QA and Prod environments and need to go through our certification process. 

# Service levels
Below are the service levels Productfy commits to based on the priority of the issue:

| Priority | Definition | Hours SLA Applies | Initial Response Time | Follow-up time |
|------------------------|---------------------------|----------------------------|--------|-----------|
|      P0      | Complete service failure  |  24 X 7     |   30 min.    | 3 hours       |
|      P1      | Impaired service                |  24 X 7     |   1 hour   |  4 hours      |
|      P2    | Reduced performance      |   Business hours   | 3 hours     | 1 business day   |
|      P3     | Standard priority      |   Business hours   | 1 business day     | 2 business days   |
|      P4     | Low priority      |   Business hours   | 2 business days     | 3 business days   |

Notes:
- Business hours are 9:00 AM EST - 8:00 PM EST / 6:00 AM PST - 5:00 PM PST
- All client identified P0 or P1 issues should be communicated by emailing 911@productfy.io
- All client identified P2-P4 issues should be communicated by emailing support@productfy.io
- All P0 and P1 issues identified by Productfy will be communicated within the given response and follow-up times
- Response times for P2-P4 are based on the time time a client communication is received

Onboarding Icon.svg

See what's involved in onboarding to the Productfy platform

Onboarding Guide

# Overview
At Productfy we understand navigating the world of banking regulations can be a major challenge in launching a fintech experience. This guide is meant to clearly outline some of the places Productfy clients need to pay attention to in order to ensure compliance and a smooth implementation. Financial Institutions are highly regulated and subject to regular audits and oversight. As a bank partner and service provider, it is important you understand and follow the Compliance policies and procedures that we have established for the Program. Don’t worry, we are here to help you navigate these policies and procedures, and we will conduct training for you as part of the onboarding process.  The process of this guide is to provide you with an overview of the Compliance requirements. If you have any questions along the way, please reach out to us through your service coordinator. 

# Disclosure Documents
Depending on what product(s) you're implementing, the legal documents you need to display in your app will differ. Don’t worry, Productfy will provide template legal documents for you during your implementation. While Productfy cannot provide legal advice, we can provide you with sample  privacy notices for your reference.  The PDF documents will be sent to you to host and display in your app, once we have received a completed Client Onboarding Information Form. Productfy will also give you a specific DisclosureID with each document for our tracking purposes (see Tracking Disclosure Data for more info). 

# Changes to Disclosure Documents
As you add or change functionality of your application, disclosures may need to be updated. Any disclosure changes will need to be re-presented to your customer and re-accepted. Please work with your Productfy representative to notify us of any upcoming changes to your functionality. 

# Tracking Disclosure Data
Bank auditors require that Productfy store a record of customers accepting disclosures in two places:
1. At time of account opening
2. At time of each 1-time ACH transfer
We provide a **Save Disclosure Acceptance API** for you to call at the time of account opening for each disclosure document presented and accepted. The API should be connected to the button your customer hits when they accept the disclosure documents presented there. Additionally, within the Initiate Fund Transfer API or Initiate ACH Transfer API there is a disclosureAcceptance object with the same fields that will need to be filled out. Please fill out the fields as indicated below:

| Field | Value                             |
|--------------|------------------------------------|
| acceptanceTime     | The current date/time (in PST) |
| disclosureId     | The disclosure ID provided by Productfy or enter ‘ACH’ for the ACH authorization |
| disclosureType     | The disclosure type associated with the disclosure ID |
| ipAddress     | The IP address of the customer |
| organizationId or personId     | The ID associated with the organization or person on Productfy |

[View Save Disclosure Acceptance API](mutation:saveDisclosureAcceptance)

# Dealing With Changes To Customer Information
Some data fields stored on Productfy are considered Personally Identifiable Information (PII), such as Name, Date of Birth, Social Security Number, Address, Email, Phone Number, etc. When these fields get changed after they have already been entered, it may be a sign of fraud. For this reason there are greater controls around how to handle these changes. Please see the chart below for direction on how to handle changes to each PII field:

| Field that's changing | Client action needed                             |
|--------------|------------------------------------|
| Email     | Change the name via Productfy API, and follow up with emails to the old email address and new email address letting the know the email on the account has been changed |
| Phone Number     | Change the name via Productfy API, and follow up with an email to the email address on file |
| Address     | Change the name via Productfy API, and follow up with an email to the email address on file |
| Name     | Send in a support ticket to Productfy for all name changes to be reviewed |
| Social Security Number   | Send in a support ticket to Productfy for all SSN changes to be reviewed |
| Date of Birth  | Send in a support ticket to Productfy for all DOB changes to be reviewed |

# Marketing and Advertising
Regulatory requirements set forth certain guidelines when advertising and/or marketing banking and financial products. We will work with you to ensure the marketing and advertising for the program is consistent with regulatory guidelines. So, for example, we will review your website pages or app screens, as well as social media messages about the program. Essentially, the regulators expect marketing and advertising to be fair and balanced, easy to understand, and not misleading. 

Clients are provided training regarding Marketing and Advertising Guidelines, with a copy of the presentation being found [here](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Fintech_Marketing_Advertising_Guidelines_2023_03_03_pptx_d705b24a33.pdf).

The [Marketing Compliance Guide](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Final_V3_0_Mkt_Compliance_Guidlines_2023_03_06_0d7d2a006a.pdf) provides detailed information regarding regulatory and Productfy requirements related to the development of marketing and advertising materials.


# Complaint Tracking Process
Per banking regulations we must keep an official record of any concerns/complaints/issues raised by an end user regarding their account or the product. The data provided will be used by our Compliance Team to review the matter and help address the matter to find a timely resolution for the end user. 

A complaint is defined as an oral or written particularized statement of dissatisfaction from a consumer or his or her representative concerning offered products or services. Routine service inquiries are not complaints, nor are generalized statements of dissatisfaction with a product or service, if the statement does not contain actionable information.

Please fill out the Complaint Handling Form [here](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Final_V_2_0_Complaint_Handling_Form_2022_08_12_f7eea27cb3.docx) and send it to Productfy when you receive a complaint. This form needs to be provided within 24 hours of receipt of a customer complaint. You are responsible for ensuring the complaint handling form is provided to Productfy within the required timeframes. 

Clients are provided training regarding Complaint Handling, with a copy of the presentation being found [here](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Complaint_Training_V2_5_2023_01_23_eead96db8d.pdf).

# Books and Records Guidance
By participating in a debit card program, you are acting as a service provider of our partner bank. All records of the program are required to be retained for a minimum of seven years so they can be audited by bank regulators and others. Moreover, they must be preserved in a way that retains the integrity of the record. So, they must not be susceptible to alteration. We have provided below a list of the artifacts that are considered to be records of the program. If you have any questions, please do not hesitate to reach out to the Productfy Compliance Team.

Records that must be preserved:
- Each page of your website or App that references or pertains to the debit card program
- Each end user customer application for a debit card 
- Evidence of acceptance of the disclosures and agreements by the end user customer
- Evidence that you have replaced a prior version of a disclosure or agreement with a new version (for version control purposes)
- Evidence that an end user customer has authorized each ACH transfer
- Evidence of any change on the end user customer’s account, such as a change in name, address, email address, or phone number
- Evidence of your confirmatory email to the customer when the end user customer changes his or her name, address, email address or phone number (this provides us with an audit trail of the changes and provides evidence that we notified the customer of the change on the account to prevent fraud)
- Evidence of delivery of any program disclosure, notice or document, such as delivery of monthly statements to end user customers. Each end user customer must be notified of the availability of the monthly statement, so that the end user customer has the ability to review the statement for accuracy and notify us of any inaccuracies.

All clients are required to provide Productfy with information regarding  vendors that are used for their specific program with Productfy, and for communication with customers. 

# Americans With Disabilities Act
Title III of the Americans with Disabilities Act requires certain businesses that serve as “places of public accommodation” to remove “access barriers” that inhibit a disabled person from accessing goods or services. As we understand it, businesses such as our sponsor bank, as issuer of your consumer debit cards, may be subject to Title III of the ADA. We also understand that Title III does not directly address whether places of public accommodation include websites, mobile applications, or other web-based technology, and that courts are split on this issue. We, therefore, ask that you consult with counsel regarding the applicability of the ADA to the debit card program and, specifically, what steps you should take to ensure that your website or App complies with the Web Content Accessibility Guidelines (WCAG) 2.1 or other applicable ADA standards.

# Yodlee Security Standards
Clients using our account linking or data aggregation services through Yodlee must adhere to their security standards outlined here: [www.productfy.io/data-source-policy](https://www.productfy.io/data-source-policy).

# Unusual Activity Reporting Process
Per banking regulations, Productfy must monitor for and report on unusual activity to its sponsor bank(s). Clients have direct access and interaction with their customers on a regular basis which places you and your employees in the financial services industry’s first line of defense against illicit activity such as money laundering, fraud, terrorist financing, elder abuse, tax evasion, etc. As part of the first line of defense, you and your employees are a vital part of the unusual activity monitoring and reporting process. Any time unusual or out of pattern activity is detected in association with your business, its customers, their accounts and/or their transactions, you are responsible for filling out a new row in your Unusual Activity Reporting Log (located in Box).

Please fill out the Unusual Activity Reporting log in Box and send a notification to Productfy’s Client Success team any time a triggering event is identified. This log needs to be provided within 24 hours of detecting the unusual or out of pattern event/activity. You are responsible for ensuring the unusual activity log is updated and Productfy is notified within the required timeframes.


# KYC / KYB Information Security Standards
Clients using our KYC or KYB services must adhere to the Federal Reserve's guidance on information security outlined here: [www.federalreserve.gov/supervisionreg/interagencyguidelines.htm](https://www.federalreserve.gov/supervisionreg/interagencyguidelines.htm).

[Final_V3.0_Mkt Compliance Guidlines_2023.03.06.pdf](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Final_V3_0_Mkt_Compliance_Guidlines_2023_03_06_0d7d2a006a.pdf)

# Account Closure
Productfy may initiate the closure of accounts based on either a request from the end user customer, the client or based on self-identified issue/concern related to non-compliance such as potential fraud or money laundering activity. Clients should not attempt to collect funds from end user customers after an account has been closed. 

# Mandatory Notice for Commercial Deposit and Debit Card Program

If you are an API client that is partnering with us on a Commercial Deposit and Debit Card program, you must post the following message on your website in a location where commercial deposit and debit card program applicants can read it. The notice warns commercial customers that they must not engage in unlawful internet gambling. For Latinum clients, this notice will be posted by Productfy in the UI.

*Notice to our Commercial Deposit Customers:*

*Under federal banking regulations (12 CFR 233.6) commercial customers must receive notice of the prohibition of conducting unlawful internet gambling transactions through banking systems. This statement provides you with the required notice.*

*You agree that your account shall not be used for the payment or receipt of any gambling transactions which are unlawful under the Unlawful Internet Gambling Enforcement Act of 2006. We reserve the right to decline any transaction which we believe or suspect is prohibited under the Act.*





Compliance Icon.svg

Read up on your obligations and how we help you maintain a compliant program

Compliance Guide

# Overview

Users must link their third party bank account with Productfy before performing any ACH money movement with the account. Linking bank accounts serves the following purposes:

- Verifies that the user owns the account being linked
- Obtains the bank account number and routing number, which are required for initiating subsequent ACH transactions

There are two ways to link an account:
1. Instant Account Verification - Productfy supports its own account linking service in partnership with Yodlee, as well as other third party account linking providers you may have a direct relationship with.
2. Micro-deposit Verification (MDV) - Productfy provides services that can initiate two small micro-deposits to an account, which then need to be verified by the customer to ensure they have access to the account. 

We recommend you use a combination of # 1 and 2 above to ensure your customers can always link their bank accounts. 

# Using third party account linking providers

If you have your own relationship with a non-Yodlee account linking provider (ex. Plaid, MX, etc.), you can use it for account linking and send the Productfy system the account and routing number for the linked account. Work with your Productfy representative to have your environment configured for a non-Yodlee account linking provider. There are two technical steps to follow:

1. Call the **Save External Account API** to save the account and routing number and associate it with the correct Person ID or Organization ID. Note, this API only supports accounts of the following types: checking, savings, money market, loan. 
[View Save External Account API](mutation:createManuallyEnteredExternalFinancialAccountWithOwnerIds)

2. Call **Verify External Link API** to set the account to Verified
[View Verify External Link API](mutation:setFinancialAccountAchConfigurationTenantAdminOverride)

# Yodlee security standards
Clients using Yodlee for account linking or data aggregation must adhere to their security standards outlined here: [www.productfy.io/data-source-policy](https://www.productfy.io/data-source-policy).

# Prerequisites for Yodlee account linking

Before account linking can occur, verify the following requirements are met:

1. You have created a [person](/docs/api/customer#create-person) or [organization](/docs/api/customer#create-organization) on the Productfy system. Person must be created with **`linkWithYodlee`** parameter as **`true`**.
2. The person or organization has completed KYC verification.
3. If linking an organization you must register the organization in Yodlee first using the [Register Organization With Yodlee api](/docs/api/accountlinking#register-organization-with-yodlee)

# Account linking workflow

Start the account linking workflow by displaying the account linking widget, which allows the user to log in to their bank account and instantly link that account to Productfy. If the link can’t be made, the user can manually link their bank account by providing the bank account number and routing number, which triggers the Micro-Deposit Verification (MDV) process using ACH transactions to prove account ownership. 

---

# Step 1 - Get configuration

Use the **Get Yodlee FastLink Configuration** API to retrieve the data needed to initialize the Yodlee Fastlink widget directly.

The **`accessToken`** returned by this Yodlee API expires after **30 minutes**.

[View GraphQL code](query:yodleeFastlinkConfiguration)

---

# Step 2 - Integrate widget

As shown in the following image, Yodlee's widget enables the user to search for their bank and create a connection to that bank’s online system. Follow [Yodlee’s integration requirements](https://developer.yodlee.com/docs/fastlink/4.0/getting-started) to initialize the Fastlink Widget. In Yodlee's fastlink.open() method, please be sure to set **`params.configName`** to **Verification** to use the widget to link an account to be used for money movement (ACH). 

![Fastlink.svg](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Fastlink_d93171b189.svg)

---

# Step 3 - Display the widget

Note - it may take between 1-15 minutes for Yodlee to fully link an account once the user submits their information through the widget. 

Productfy recommends the following best practices to integrate the web widget:

- Display a link for users to choose not to use the account linking widget and manually link their accounts. For example, if the user’s bank is not one of the supported banks, they will not be able to use the widget and must perform the traditional micro-deposit verification.
- Pass in an event handler for errors from the widget to improve customer experience and aid in troubleshooting errors. See Productfy recommended code below:

```javascript {.collapsible collapsible=true} title="FastLink Error Handler"
// Let's keep track of how many times the user failed to log into their bank site
const failedLoginCounter = 0;
const otherErrorsCounter = 0;

const onError = (data) => {
  console.error(data); // If you want to log the error to the browser console
  /**
   * Example of "data"
   *   additionalStatus: "INCORRECT_CREDENTIALS"
   *   fnToCall: "accountStatus"
   *   isMFAError: true
   *   providerAccountId: 11810284
   *   providerId: 2852
   *   providerName: "Bank of America"
   *   reason: "The credentials you've entered are incorrect. Verify that CAPS LOCK is not on
   *     and that the desired financial institution was selected."
   *   requestId: "M+HOk5ylDDDBDTZnaApg2E9VSqI="
   *   status: "FAILED"
   */
  
  if (data && data.status === 'FAILED' && data.additionalStatus === 'INCORRECT_CREDENTIALS') {
    failedLoginCounter++;
  } else {
    otherErrorsCounter++;
  }

  // It would be good to log the error to our backend so that we can investigate possible bugs
  // or system downtime.
  const payload = {
    apiUrl: 'API_URL', // Optional. If you are accessing Productfy's API from the web app.
    pageUrl: window.location.href,
    eventBody: data,
    callbackType: 'onError',
    isError: true,
    fastlinkConfiguration: { // Essentially the values you're passing into the FastLink widget
      fastLinkURL: 'FASTLINK_URL',
      accessToken: 'Bearer YOUR_ACCESS_TOKEN',
      params: {
        configName : 'Aggregation' // Whichever mode you're running FastLink in
      },
    },
    // In this section, if you keep track of the IDs in your web app, passing them to the logs
    // would be helpful.
    session: {
      companyId: 'COMPANY_ID', // Optional
      loginId: 'LOGIN_ID', // Optional
      personId: 'PERSON_ID',  // Optional
      sessionKey: 'SESSION_KEY', // Optional. If you are accessing Productfy's API from the web app.
    },
  };

  try {
    fetch('https://logger.productfy.io/', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload),
    });  
  } catch (e) {
    console.error('Could not log error', e);
  }

  // If the user attempted and failed several times (you can tweak the values and logic
  // to your liking)
  if (failedLoginCounter > 2 || otherErrorsCounter > 2) {
    // Hide FastLink and show a dialog asking if they want to try adding their account
    // using the routing and account numbers. Or redirect them to a support page.
  }
};
```

---

# Step 4 - Save Yodlee FastLink Result

After a user completes the Yodlee FastLink widget flow, it may take up to **15 minutes** for Yodlee to respond back with confirmation that the account is linked. In the meantime, you can temporarily save the account information to Productfy's PersonKVPData object by passing in the Yodlee Provider ID and Yodlee Provider Account ID to one of the APIs below. This will store the **Account Name**, **Account Type**, **Estimate Balance**, and **Bank Name** from Yodlee, which you can use to display to your customer.

For Person: [View GraphQL code](mutation:saveFinancialAccountsFromYodleeFastLinkForPerson)

For Organization: [View GraphQL code](mutation:saveFinancialAccountsFromYodleeFastLinkForOrganization)

---

# Step 5 - Get Productfy Account ID

After the user gets through the Yodlee FastLink widget, Productfy will wait to hear back from Yodlee before creating an account on the system. 

Note - it may take up to **15 minutes** for Yodlee to fully link an account once the user submits their information through the widget. 

You will need the Account ID for subsequent API calls below. There are two ways to obtain the Account ID:

- Listen to Productfy's **[Account Linked webhook](/docs/api/webhooks#account-linked)**. The webhook will trigger after the account is confirmed on the Productfy system and its payload will include the Account ID.
- Call the **Get Multiple Accounts** API with the user's Person ID to retrieve the Account ID once it's available. 
    - You can find this field under the returns section field **`yodlee.accountId`**
    - In the event support is needed from Yodlee, Productfy will also need the field **`yodlee.providerAccountId`** for troubleshooting

![YodleeReturnsDescription.jpeg](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Yodlee_Returns_Description_36cc418e16.jpeg)
The **`yodlee.accountId`**  field represents the ID of the account (i.e. checking/savings/credit card) linked to Yodlee. While the **`yodlee.providerAccountId`** represents the user's ID on the Yodlee platform.

[View GraphQL code for Get Multiple Accounts API](query:financialAccounts)

---

# Step 6 - Verify account linking status

Use the **Account Linking Status API** to check on the status of an attempted account link. The status of the link will guide the next steps for the user as indicated below:

- If the Account Linking Status API returns an accountID and has needAccountNumber and needRoutingNumber as false, the user’s account is successfully linked. 
- If the Account Linking Status API returns an accountID but has needAccountNumber and needRoutingNumber as true, then the account has been partially added. You will need to ask the user to input the Routing Number and Account Number for their bank account and save it to Productfy with the [Add Routing & Account Numbers API](/docs/api/accountlinking#add-routing-account-numbers). 
- If **needVerifyMicroDeposits** is true, the user was not able to authenticate, and the traditional micro-deposit verification flow must be completed. Go to [Step 7 - Traditional Micro-Deposit Verification](#step-7-traditional-microdeposit-verification).

[View GraphQL code](query:accountLinkingStatus)

---

# Step 7 - Traditional micro-deposit verification

If the user was unable to authenticate using the account linking widget, use MDV to verify that micro deposits make it to the user’s bank account. This takes 1 business day or less. After the deposit is verified, the user must return to your app to verify the amounts of the micro deposits, which do not expire. Also, we will automatically initiate withdrawals for the micro-deposit amounts to take the money back. 

### Ask for account number and routing number

The API you use for this depends on whether you're using the Yodlee integration described above, or not. If you are using the Yodlee integration above, then the account ID has already been created and associated with the Person or Organization ID and you can use the **Sensitive Financial Information** API to get the account and routing number:

[View GraphQL code](mutation:sensitiveFinancialAccountInformation)

If you are choosing not to use the Yodlee integration above and just build a micro-deposits flow only for linking accounts, then you need to call the **Save External Account API** to save the account and routing number and associate it with the correct Person ID or Organization ID:

[View Save External Account API](mutation:createManuallyEnteredExternalFinancialAccountWithOwnerIds)

### Initiate micro-deposits 

Use the **Initiate Micro-Deposits** API to initiate two micro-deposit verifications (MDV) to the account ID that was created. It will take 1 business day or less for the two amounts to show up in the bank account. 

[View GraphQL code](mutation:initiateMicroDeposits)

### Verify micro-deposits

After you've initiated micro-deposit transfers, use this API to verify the amounts. You must wait 3 hours before you can verify the micro-deposits. The micro-deposit verification is invalidated after 5 failures. Micro-deposits do not expire.

Micro-deposit verifications in test environments are valid for any amount less than $0.10.

[View GraphQL code](mutation:verifyMicroDeposits)

---

# Step 8 - Optional support for removing linked accounts

You can support deletion of a Yodlee-linked financial account using the **removeFinancialAccount** API. This will remove the account and all associated transactions from Yodlee. This is a permanent operation that cannot be reversed. NOTE: Do not use this to delete virtual accounts.

[View GraphQL code](mutation:removeFinancialAccount)

---

# Step 9 - Test Your Yodlee Integration

Below is a preset list of test credentials from Yodlee to make sure your integration works as planned. Use it for testing purposes in your development and production environments. Note that IQ Bank shows up in production but is a mock bank with fake transactions to be used for testing purposes only.

Disclaimer About Using Yodlee DAG Accounts:
1. Yodlee DAG is a simulation tool that Yodlee offers as a testing aid. The site is a Yodlee hosted site.
    - Any Yodlee DAG account's performance issues and DAG site issues are completely unique and do not in any way reflect on our real production site's behavior.
    - There are no SLAs for Yodlee DAG. Yodlee supports this testing aid on a best effort basis.
2. Yodlee DAG can be used to simulate a good selection of scenarios but does not offer the nuances and variety of actual accounts.
    - We highly recommend that Yodlee DAG is only used for development and integration testing and that actual accounts are procured and used for User Acceptance Testing.

| Name           | Username                                | Password                             | Description                                                       |
| -------------- | --------------------------------- | ------------------------------- | --------------------------------------------------- |
| IQ Bank        | test_860190                           | test@iqb                               | Transactions date back to August 31, 2021  |
| IQ Bank        | test_072854                           | test@iqb                               | Transactions date back to August 31, 2021  |
| IQ Bank        | test_mfa_token_110136       | test@iqb; Token: 1234 | Transactions date back to August 31, 2021  |
| IQ Bank        | test_mfa_qa_717510             | test@iqb; What is the name of your best friend? Alex; Which city is your high school? Texas | Transactions date back to August 31, 2021
| DAG Site      | stmttest.site16441.2              | site16441.2                         | Transactions are in 2016                                |
| DAG Site      | DagTest365Txn.site16441.2  | site16441.2                         | Transactions are in 2018                                |
| DAG OAuth | GOAuth.site19335.1              | site19335.1                         | ---                                                                      |

guides-accountlinking.svg

Account Linking

# Overview

The ACH system is a federally regulated electronic network for financial payments in the United States. You can use ACH to move money between banks using an account number and bank routing number. Common examples include transfers between accounts, and electronic payments such as direct deposit for salaries, bill pay, or tax refunds.

## ACH transaction speeds

There are two speeds for ACH, standard and same-day. You are able to set the speed in your Initiate ACH Transfer Request API call. Consult your Productfy pricing schedule to understand the differences in prices between the two. 

::alert[Note: Same-day ACH carries increased risk of an ACH return after the initial ACH request has been settled, since it can settle on the same day but any return, including those due to insufficient funds, won't show up until the next day at the earliest.]


ACH transactions are sent daily to Productfy’s partner banks for processing. The following table summarizes ACH cutoff times for requests to get to Productfy, and when they will settle. This gives Productfy enough time to generate the ACH file and get it processed by our bank partner. Files missing the cutoff time or not marked for same-day processing are processed as standard files. All times are shown in Pacific Standard Time, and files are only processed on business days (Mon.-Fri., and not on Federal Reserve holidays).

| Processing Eligibility | ACH Cutoff (business days) | When ACH Files are Settled (business days) |
|------------------------|---------------------------|----------------------------|
| Same Day               | 6:30AM PST                     | 2:00PM PST                     |
| Same Day               | 8:30AM PST                      | 3:00PM PST                     |
| Standard               | 12:30PM PST                      | Next Day                   |

## Types of money movement

Use Productfy with ACH integration to set up your own electronic transfer of funds in the following ways:

* Move money between a bank and a Productfy virtual account that holds your customers funds.
* Move money between two third-party banks.

### Move money between a bank and a Productfy virtual account

Productfy virtual accounts allow your customers to store money in an account that lives on the Productfy system and is backed by our banking partner. ACH allows you to move money into and out of the virtual account.

![Move money between a bank and a Productfy virtual account.svg](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Move_money_between_a_bank_and_a_Productfy_virtual_account_eaa5910349.svg)

### Move money between two third party banks

You can also use ACH to move money between two third party banks, as shown in the following example. This two-leg ACH transaction pulls money from one bank and pushes the funds to a second bank:

![Move money between two third party banks.svg](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Move_money_between_two_third_party_banks_7437546aeb.svg)

---

# Manage ACH

Get help from Productfy if you need it, and make sure you disclose terms and conditions for your users.

## Customer support

Send an email to [Productfy support](mailto:support@productfy.io) if you need help at any time while configuring ACH integration. 

## ACH disclosures and compliance

See our [Compliance Guide](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Productfy_Compliance_Guide_ACH_Clients_V7_1_05_13_22_2ce39a4b19.pdf) for sample disclosures and requirements for your app to be in compliance. 

## ACH transaction limits

Productfy enforces limits on ACH transfers initiated via our ACH APIs to control for risk. We do NOT enforce limits on incoming ACH transfers originated at other banks (e.g. direct deposit transactions). Here are some specifics about how these limits work:
- Consumer limits apply to ACH transfers initiated by Person IDs on Productfy, Business limits apply to ACH transfers initiated by Organization IDs on Productfy. 
- Limits apply at the customer-level (Person ID or OrganizationID) regardless of how many virtual accounts they have. 
- Limits apply to both ACH debits and credits, in other words, we look at the absolute value of all ACH activity and compare that against the limit. 
- Daily limits look at activity from 12:00 AM PST to 11:59:59 PM PST every day. 
- If a transfer puts a customer over the limit, the API will return an error in real-time. In other words, the ACH request will not even be created if it is over the limit. 

Standard ACH transaction limits are as follows:

| Account Type | Daily Limits                             | 30-day Rolling Limit |
|--------------|------------------------------------|----------------|
| Consumer     | $5k per day per Person ID | $10k per rolling 30 days |
| Business     | $100k per day per Organization ID | $1 million per rolling 30 days |

---

# Step 1 - Initiate ACH transfer

Once a user’s external bank account is linked you are ready to initiate ACH transfers. See the [Account Linking](/docs/guides/accountlinking#root) guide for account linking instructions.
 
Present the user with input boxes to enter the following information:

- Account they are transferring money from
- Account they are transferring money to
- Amount of money being transferred

**For transfers between external bank accounts and Productfy virtual accounts:**

Call the **Initiate Funds Transfer** API to submit the ACH transfer request. The API will automatically create the transaction on the virtual account, and transition it from pending to settled status. 

[View Initiate Funds Transfer API](mutation:initiateFundTransfer)

**For transfers between two external bank accounts (2-leg ACH):**

Call the **Initiate ACH Transfer** API to submit the ACH transfer request. The **fundsFlow** field will dictate whether you are creating a 2-legged ACH transfer (between two externally-linked accounts), or a 1-leg ACH (with your tenant operating account). 

::alert[Note: If same-day ACH is selected for a two-leg ACH, both legs will be sent as same-day]

[View Create ACH Transfer Request API](mutation:createAchTransferRequest)

When the form is submitted, an ACH file is created and sent to Productfy’s bank partner for processing. See [ACH transaction speeds](#ach-transaction-speeds) for information about when ACH files are generated, processed, and settled.

If you are testing in a test environment, any transfers where the last non-zero digit is an odd number (ex. 1, 2.21, 10, 20.01) will end in a failed ACH state whereas if the last non-zero digit is an even number (ex. 2, 1.02, 5.12) will succeed. This only occurs in simulation mode and only after the normal validation rules are applied.

# Step 2 - Display and Store ACH Authorization 

To abide by ACH regulations, be sure to display the following ACH/EFT disclosures on the screen where customers are initiating 1-time ACH transactions:

*By pressing the “accept and complete” button below, I hereby authorize [Fintech partner legal name] (Fintech partner name if different) to initiate an ACH transfer from the account listed above. I certify that I am authorized to initiate this transfer and that it complies with applicable laws. This authorization is to remain in full force and effect until I notify [Fintech partner name] at [Insert contact email] that I wish to revoke it. I understand that [Fintech partner name] must be provided sufficient time to have a reasonable opportunity to act upon my notice to revoke this authorization.*

If you have built the mechanism to send recurring or future-dated ACH transactions to Productfy, you’ll need to include the text below on the screen where your customers first create these transactions. Additionally, the log of the customer ‘accepting’ this text must be submitted to Productfy (see Tracking Disclosure Data for more info).  

*By pressing the “accept and complete” button below, I hereby authorize [Fintech partner legal name] (Fintech partner name if different) to initiate an ACH transfer from the account listed above. I certify that I am authorized to initiate this transfer and that it complies with applicable laws. This authorization is to remain in full force and effect until I notify [Fintech partner name] at [Insert contact email] that I wish to revoke it. I understand that [Fintech partner name] must be provided sufficient time to have a reasonable opportunity to act upon my notice to revoke this authorization. I understand that this authorization will remain in full force and effect until I notify FINTECH PARTNER NAME by email that I wish to revoke this authorization. I understand that FINTECH PARTNER NAME requires at least three (3) days prior notice in order to cancel this authorization.*

Additionally, bank auditors require that Productfy store record of customers accepting the ACH authorization language above at the time the transfer is initiated. There is a **disclosureAcceptance** object within the **Initiate Funds Transfer** or **Initiate ACH Transfer** APIs with the following fields that need to be filled out:

| Field | Value                             |
|--------------|------------------------------------|
| acceptanceTime     | The current date/time (in PST) |
| disclosureId     | Enter ‘ACH’ for the ACH authorization |
| disclosureType     | The disclosure type associated with the disclosure ID |
| ipAddress     | The IP address of the customer |
| organizationId or personId     | The ID associated with the organization or person on Productfy |

[View Initiate Funds Transfer API](mutation:initiateFundTransfer)
[View Create ACH Transfer Request API](mutation:createAchTransferRequest)
---

# Step 3 - Monitor ACH request status

Listen to Productfy's [ACH webhooks ](/docs/api/webhooks#ach-transfer-validation-failed) to stay informed on the status of an ACH transfer. 

ACH transfer requests can have the following states:

* When an ACH transfer request is first created, its status is CREATED ("C").
* The ACH transfer then goes through a series of validation checks and watchlists and is assigned a status of VALIDATION_FAILED ("VF") or VALIDATION_SUCCESSFUL ("VS") depending on the outcome of the validation checks. 
* If the ACH transfer passes the validation checks, a NACHA file is created and submitted to the originating bank for processing. At this point, the ACH transfer is assigned the status SUBMITTED_TO_FINANCIAL_INSTITUTION ("SI"). Once the ACH transfer is in the "SI" status, the window for canceling the ACH transfer is closed.
* If the transfer is not returned by the bank within 2 business days, it is automatically moved to a status of COMPLETED_SUCCESSFULLY (“S”). If the ACH transfer was returned by the bank for any reason, it is assigned the status FAILED ("F"). 

Note that in some cases, an ACH request could initially be marked as “COMPLETED_SUCCESSFULLY” but later changed to “FAILED”. For example, the ACH transfer could be returned if it was reported as unauthorized within 60 days from the initial settlement date.

For a 2-legged ACH transfer, Productfy will begin the second leg of the ACH transfer once the first leg moves to COMPLETED_SUCCESSFULLY status (usually within 2 business days). 

![ACH State Diagram.svg](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/ACH_State_Diagram_e4961d336f.svg)

**ACH Returns**

If a submitted ACH gets returned by the receiving bank, Productfy will trigger the [ACH Transfer Failed webhook](/docs/api/webhooks#ach-transfer-failed).   

For a 2-legged ACH, if the first leg is returned, Productfy will not initiate the second leg. If the second leg gets returned, a webhook will be triggered and Productfy will reverse the first leg of the transaction.  

To check on the status of a submitted ACH transaction, call the **[`Get ACH Transfer Requests`](/docs/api/ach#get-ach-transfer-requests)** API. 

To view the rules that may cause an ACH transaction to fail, pass in the parameter **`achTransferRequestIds`** and ask for **`approvalRuleEvaluationResults`** in the response returns to display all the details pertaining to the failure.

[View GraphQL code](query:achTransferRequests)

---

# Step 4 - View transfers

### View Virtual Account transactions

For clients using Productfy Virtual Accounts, you can display transactions (from step 3) on the account by using our general-purpose **Finsight Proflie** API. 

[View GraphQL code](query:finsightProfile)

### View ACH transfer requests

For clients wanting to show users a list of their ACH requests and the status, use the **Retrieve ACH Transfer Requests** API. 

[View GraphQL code](query:achTransferRequests)

---

# Step 5 - View ACH data

You can monitor your ACH activity through the **ACH Transfers Report** link on your client portal. 

![ACH Data.svg](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/ACH_Data_1a61b0c702.svg)

---

# Step 6 - ACH Certification

During your implementation project with Productfy, you will be required to go through a certification phase to ensure your app is working correctly end-to-end with the Productfy system for both successful and error scenarios. 

For each test scenario below you will need to be prepared to gather the following information and provide it to us:

- Transaction ID
- Date and time
- Descriptions of the tests being performed (i.e.. MDV, account funding (ACH), etc.)
- Documentation (screenshots should be sufficient) substantiating you can view ACH status information and ACH transfers for the end-user

## ACH Test Cases
The following test cases must be performed and verified before we can consider ACH Certification completed and move you into Alpha.

1. **Multi-Factor Authentication -** Ensure that you have implemented a MFA solution in your app. 
2. **MDV (Micro Deposit Verification) -** We need to test the function of MDV in the event IAV (Instant Account Verification) is not available or fails.
3. **Account Funding -** From your end-user perspective, an ACH transaction would be initiated to move money to the customers account from an external linked account (with funds settling in your FBO account)
4. **Account Withdrawal -** From your end-user perspective, an ACH transaction would be initiated to move money from their account to their externally linked bank account (funds movement from FBO to external account). 
5. **Returned ACH -** From your end-user perspective, you will need to initiate an ACH transfer that you know will be returned (this is similar to a check being returned or bouncing). Triggering an NSF (R01) or Stop Payment (R08) are the two best scenarios. This will ensure the end to end flow between your application, Productfy, the bank partner and the FED is working correctly, as well as to ensure you can see returns reflected in your tenant portal (ACH Return Summary) and that the metrics are reported correctly.
6. **Same-Day ACH -** If you intend to support and provide your customers with a same-day ACH, we need a test initiated to confirm the configuration within your application and verify the resulting transaction is produced within the appropriate time window.


guides-ach.svg

Move money over the ACH network between two bank accounts.

ACH Money Movement

guides-cards.svg

Issue branded debit cards to your customers

Debit Card Issuing

![disbursement 1b.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/disbursement_1b_e204210210.png)

# Overview

Productfy’s disbursement service provides an end-to-end workflow for companies or organizations to send money to recipients on a virtual or physical debit card. This service is available as a “no-code” white-label solution where Productfy provides all the user interfaces, or an API solution where you build your own UI, or a mix of both. 

# Disbursements Workflow

Here is the high-level sequence of events for a disbursement to be initiated all the way through the receiver getting the funds:

1. **Create disbursement request -** Organizations must create a request to send a money to a customer, along with a security code
2. **Notify customer -** Customers must be notified, via email by default, that they have money sent to them, with instructions on how to access it
3. **Authenticate customer -** Customers authenticate via a token and a security code and provide identity information
4. **Fund Account -** Funds can be transferred in real-time from a pre-funded funding account
5. **Provide account/card access -** Customers can receive a virtual or physical debit card to spend funds and access a website that shows their remaining balance and transaction history

# Prerequisites for API solutions

::alert[Note: If you are using our white-label solution instead of the API, Productfy will handle all the steps below for you. ]

To set up your pre-funded disbursement account (the account the money for the disbursements will come out of), your organization must set up an Organization ID on the Productfy system with a Virtual Account that is funded from a Linked Account. You will only be able to disburse funds up the balance in this pre-funded account. 

- For information on how to set up an Organization ID, please see [here](/docs/guides/gettingStarted#step-4-create-customers).
- You will need to setup a Person ID for the controller of the company. See instructions [here](/docs/guides/kyb#step-2-authorized-person-workflow).
- Contact Productfy to ensure the Organization ID has passed our KYB requirements.
- A virtual account will need to be created for the organization following instructions [here](/docs/guides/virtualAccounts#root).
- A third party bank account can be linked following instructions [here](/docs/guides/accountlinking#root).
- Finally an ACH transfer can be initiated to fund the account following instructions [here](/docs/guides/ach#root).

---

# Step 1 - Create Recipient

Before a disbursement can be created, you first need to create a Person ID for the recipient of the disbursement. The minimum required fields are first name, last name and email, but you can choose to store additional data with the Person ID if you want. Emails must be unique across recipients so it’s best to verify if the email has already been used by your customers or not using the API below. 
 
Coming soon: **Verify Email Is Unique API**

If the email has not been used yet you can proceed with creating a new Person ID for the customer using the API below. If the email has already been used, you can create a second disbursement for the existing Person ID by skipping to step 2.

[Create Person API](mutation:createPerson)

# Step 2 - Create Disbursement Request

Create the disbursement request for the PersonID from above by calling the API below. The disbursement will start out with a status of Created. This API requires the following fields:
- **Person ID -** The customer who will be receiving the disbursement
- **Security Code -** Alphanumeric code used to authenticate the customer to get access. The security is specific to your use case and should be something that the only the customer knows. For instance, if you are refunding a flight, then the security code can be the ticket id. If you are paying out an insurance claim then the security code can be the claim id. If you are refunding an expense, then the code can be the invoice id. 
- **Amount -** The amount of money you want to send
- **Funding Account ID -** The account ID where the money will come from

[Create Disbursement Request API](mutation:createConsumerDisbursementRequest)

# Step 3 - Send Disbursement Notification

Our Consumer Disbursement webhook will inform you to send out an email notification to a customer letting them know they have received a disbursement. To trigger the webhook, you must call the API below with the Disbursement ID you got in Step 2 above. 

[Send Disbursement API](mutation:generateConsumerDisbursementNotification)

The Consumer Disbursement webhook will contain the information you need to construct your customer notification. The webhook payload is [here](/docs/api/webhooks#disbursement-status).

::alert[Note: To subscribe to webhooks, see the instructions [here](/docs/guides/gettingStarted#step-6-set-up-webhooks).  ]

# Step 4 - Administer Disbursements

To help your administration and troubleshooting of disbursements, you will most likely want to query disbursement requests to view details. You can do that by calling the API below:

[Search Disbursements API](query:consumerDisbursementRequests)

If you have a need to cancel an existing disbursement you can use the Cancel Disbursement API:

[Cancel Disbursements API](mutation:cancelConsumerDisbursement) 

# Step 5 - Validate Security Code

When the customer chooses to claim their disbursement, they need to enter the security code that you entered when the disbursement was first created. You can use the Validate Security Code API for this:

[Validate Security Code API](query:verifyConsumerDisbursementRequestSecurityCode)

Note that the security code is half of the authentication mechanism; the other half is the token in the email.

# Step 6 - Customer KYC

After customers have validated their security code they need to pass the necessary level of KYC before they can get access to their funds. For non-reloadable disbursement cards, this is a watchlist check only, for reloadable cards this is full KYC. See our [KYC guide](/docs/guides/kyc#root) for more information on our KYC service. 

# Step 7 - Account opening, funding, and card issuance

Once the customer has passed KYC you are able to give them their money. The Issue Consumer Disbursement API will do 3 things automatically:
- Create a virtual account under the Person ID
- Create a real-time transfer from your designated funding account to their virtual account ID
- Issue a debit card (virtual or physical) on top of the virtual account

[Issue Disbursement API](mutation:issueConsumerDisbursement)




Disbursements.svg

Disbursements

# Overview

To issue commercial cards or make ACH transactions on behalf of a business entity, regulations require us to verify basic data about the business. We call these business verification requirements the “Know Your Business” (KYB) process. Since every business is operated by at least one individual, regulations require us to gather identifying information from at least one senior leader of the business. 

The verification process for individuals is known as the Know Your Customer ([KYC](/guides/kyc)) process. If the business is operated as a legal entity, such as a C-Corp, regulations require us to gather KYC information about certain individual owners of the business entity, as described in the [Authorized Person Requirements](#authorized-person-requirements). The federal government wants us to gather and confirm information about the people who control the business, in order to assess its fraud and money laundering risk, and we appreciate your assistance with this process. 

# KYB Information Security Standards
Clients using our KYB services must adhere to the Federal Reserve's guidance on information security outlined here: [www.federalreserve.gov/supervisionreg/interagencyguidelines.htm](https://www.federalreserve.gov/supervisionreg/interagencyguidelines.htm).

# Business Requirements
Every business end-user must:

1. Be created as an organization, this includes **sole proprietors**.

2. Have at least one authorized person associated with the organization (see below [Authorized Person Requirements](#authorized-person-requirements) section for more details)

3. Have the following fields filled out:

| Field      | Description |
| :----: | :---   |
| **Business Structure Type** | The official tax reporting structure of the business entity. Possible types are as follows: Cooperative, C-Corp, S-Corp, LLC, Partnership, Sole Proprietorship, Unincorporated Associations |
| **Doing Business As (DBA) (if applicable)**| Also known as a trade name, fictitious name, or assumed name. This field is only applicable if the business entity operates under a name different from its legal business name. |
| **Company Address**  | The primary physical address of the business’ operations or headquarters. This cannot be a PO Box. |
| **Company Name** | The official legal business name. In the case of a **sole proprietor**, this may be their full legal name.|
| **Company Phone Number** | The company's phone number or phone number of the business point of contact. |
| **Formation Date** | The official formation date of the company. |
| **Industry Classification** | A short text description of the primary business activity or industry associated with the business entity. |
| **Taxpayer Identification Number (TIN)** | The tax id for most business entities is an EIN (Employer Identification Number). A **sole proprietor** may use their personal SSN. |
| **Website URL (if applicable)** | The official website of the business entity. |

4. Attest to not engaging in high risk activities Productfy is unable to support (see Step 3 of the Organization Workflow below):
- Marijuana or cannabis related businesses (MRB or CRB)
- Casinos, internet/online gambling or other gaming establishments
- Pawnbrokers
- Dealers in precious metals, stones or jewels
- Private ATM owners

# Authorized Person Requirements
At least one authorized person must be associated with the business to pass KYB. This authorized person must go through the full KYC process for the business to pass KYB. In the case of a sole proprietorship, the sole proprietor **must** be the authorized person. All other types of businesses need **at least one** designated *Controller* and may have **zero to four** *Beneficial Owners*. 
- *Controller* is defined as an individual with significant responsibility for managing the business entity (i.e. CEO, COO, Managing Member, President, General Partner, Treasurer, President, etc.). 
- *Beneficial Owners* are defined as any individuals who, directly or indirectly, own 25% or more of the business entity. 

All of these individual entities are referred to as authorized persons and must pass KYC if they exist in the business structure. 

This is summarized in the table below:

| **Role**             | **Needs KYC?** |         **KYC Requirements**        |                                                                                    **When Does Role Apply?**        |
|----------------------|:--------------:|:-----------------------------------:|:---------------------------------------------------------------------------------------------------------------------:|
| **Sole Proprietor**  |       Yes      |               Full KYC              |  Only for a sole proprietorship and this will be the only role for that business structure type. |
| **Controller**       |       Yes      |               Full KYC              |    When a business is not a sole proprietorship, it needs a controller listed and there may only be one individual identified as a controller. |
| **Beneficial Owner** |       Yes      | Full KYC for each Beneficial Owner | When a business is not a sole proprietorship and has one or more people who directly or indirectly own 25% or more of the business. Each individual who owns 25% or more of the business entity must be listed and verified through the KYC process. |

**NOTE: The individual listed as the business entity’s Controller may also be a Beneficial Owner. See the role table in the [KYB Workflow](#kyb-workflow) for more details on the role options.**

---

# KYB Workflows
You must complete three distinct workflows to satisfy the full KYB verification process. The Organization and Authorized Person workflows can be completed simultaneously, but the final KYB workflow depends on the previous two.

# Step 1 - Organization Workflow
Complete these workflow steps before or after creating the authorized person(s).

## Create an Organization
The first step in getting the business ready for the KYB process is to create it in the Productfy system. Supply all fields, except for Company Address, to the **`Create Organization API`** call to create your business in the Productfy system. Please see the above [Business Requirements](#business-requirements) section for more information on the specific fields and their descriptions.

[Create Organization API](mutation:saveCompany)

## Add Address to Organization
Add the address of the organization via the API call below that accepts a standard street address, street name, city, and postal code. Alternatively, it also accepts a google places id, if applicable.

[Save Organization Address API](mutation:organizationAddress)

## Obtain Attestation Of Activity
Due to Productfy and our partner bank's risk tolerance, we are unable to support business customers that operate in certain high risk businesses. To manage this, you must present the customer with a screen that asks the following question:

**Does the company engage in, or operate as, any of the following (check all that apply):**
- **Marijuana or cannabis related businesses (MRB or CRB)**
- **Casinos, internet/online gambling or other gaming establishments**
- **Pawnbrokers**
- **Dealers in precious metals, stones or jewels**
- **Private ATM owners**
-  **Adult content or adult entertainment**

**I, (name of natural person opening account), hereby certify, to the best of my knowledge, that the information provided above is complete and correct.**

Positive responses to any of these industries should result in the application being declined ahead of collecting any more information. Additionally, you must maintain records of each customer that has been presented with the attestation, and when they have filled it out, in case bank auditors would need to see it. 

---

# Step 2 - Authorized Person Workflow
These workflow steps must be completed for the business’s  *Controller* and each *Beneficial Owner*, or in the case of a **sole proprietorship**, the sole proprietor will be the only authorized person.

## Create Authorized Person(s)
At a minimum each authorized person must have the following fields filled out:
- Name
- SSN
- Date of Birth
[Create Person API](mutation:createPerson)

## Add Address to Authorized Person(s)
Add the person's address via a separate API call which accepts a standard street address, street name, city, and postal code. Alternatively, it also accepts a google places id, if applicable.

[Save Person Address API](mutation:personAddress)

## Execute KYC on Authorized Person(s)
Once the above prerequisite information is saved in the system the authorized person can go through the standard KYC waterfall.
 
See the [KYC guide](https://user.stage.productfy.io/docs/guides/kyc#step-1-execute-kyc-verification) for more details on the specifics of the KYC process.

---

# Step 3 - KYB Workflow
This is the final step where we link the verified Authorized Person(s) to the organization and kick off the KYB verification.

## Associate Authorized Person(s) with Organization
At this point, we have verified all authorized person(s) through the KYC process and created an organization in the Productfy system. Now it is time to link the two. To create this link provide the organization id, person id, a CRUD mode, and a role for the associating person. Set the CRUD mode to C_F which will create the association if it does not currently exist. If it does exist an error will return indicating the link is already created.

Finally, fill the **role** field with one of the preset enum values indicating the relationship the associated person has with the business.
| Role | Description |
| :---- | :---   |
| **Beneficial Owner** | Person with a 25% or more, direct or indirect, ownership stake in the business entity. |
| **Both Beneficial Owner and Controller** | Person performs the duties of the controller while also having a 25% or more ownership stake. |
| **Controller** | Person who has significant responsibility for managing the business entity. |
| **Employee** | Person is a regular employee of the company. Use this role when an employee will be issued a card or makes ACH transactions but is not an authorized person. See the [Business Signers](#business-signers) section below for more details. |
| **Sole Proprietor** | Person is the sole owner of an unincorporated business. |

[Associate Person to Organization API](mutation:saveOrganizationPersonAssociation)

## Execute KYB on the Organization
As a final step, call the **Execute KYB API** on the Organization ID of your business customer. This API will perform 3 functions on the Organization outlined below:

### 1. Data Validation
This step ensures all the data on the Organization and associated Person IDs described in this guide above are done correctly. The API will immediately return errors if any of the data is not set up correctly. 

### 2. OFAC Watchlist Check
Per banking regulations we must verify that the business (including Sole Proprietorships) is not on a watchlist. If the Organization has a DBA name (the **dba** field is filled out), then we will send both the Organization name and Organization DBA through a watchlist check, and both must pass for the Organization to be considered passed for the watchlist check. If a watchlist check fails, it will be manually reviewed by Productfy compliance, and may result in being overridden into a pass. Any watchlist pass will trigger the KYB webhook. 

### 3. Business Identity Check
For Organizations that aren't Sole Proprietorships (e.g. LLCs, or C-corps, etc.) or for Sole Proprietorships that have a DBA (the **dba** field is filled out), we must verify that the business data is legitimate based on government records and other sources. This process will usually be completed within a day but may take longer. The result of this check will be communicated in the KYB webhook. 

[Execute KYB API](mutation:executeKyb)



guides-kyc.svg

Validate a business to meet compliance requirements

# Overview

Due to banking regulations, users must have their identity verified and checked against various watchlists before they are able to open any accounts or transact on our system.

Our KYC policy requires the following information from users:
- Name
- Date of Birth
- Address
- Social Security Number*

*Note - customers without SSNs are able to upload passport or government IDs to pass KYC

# KYC Information Security Standards
Clients using our KYC services must adhere to the Federal Reserve's guidance on information security outlined here: [www.federalreserve.gov/supervisionreg/interagencyguidelines.htm](https://www.federalreserve.gov/supervisionreg/interagencyguidelines.htm).

# Prerequisites

Before KYC can be performed, verify the following requirements must be met:
- Person exists in Productfy system
- Person has name, date of birth and social security number filled out
- Person has an address associated with them

See the [Getting Started](/docs/guides/gettingStarted#step-4-create-customers) implementation guide (step 4) for information on our APIs to create customers with the right information in the system. 

# KYC Standard Waterfall
Productfy’s standard KYC waterfall is designed to reduce friction for the customer by favoring non-documentary verification over documentary verification. Level 1 of the waterfall  validates the customer's Name, Date of Birth, Address and Social Security Number. Depending on the results of that validation, customers may pass KYC at that point or move on to Level 2 (Knowledge-based questions) or Level 3 (Document Verification Service), as shown in the diagram below. 

![KYC-Waterfall-Diagram.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/KYC_Waterfall_Diagram_cb3a4d20e5.png)

KYC starts by calling the **executeKycVerification API** and then proceeding by following instructions returned in the **`nextStep`** field until the **`identityVerified`** field returns either true or false.

Note that **`nextStep`** has the following possible return values which outline the different KYC tools that Productfy offers:
- Knowledge-Based Authentication (KBA)
- Document Verification Service (DVS)

# ACH Identity Verification
For certain use cases that are considered low-risk, a simpler version of KYC, known as “ACH Identity Verification'', can be used instead of standard KYC. To perform ACH Identity Verification, your specific use case must be reviewed and approved by Productfy before your environment can be configured to utilize ACH Identity Verification. One potential use case would be paying bills from an external payment method where the end-user is not opening a deposit account or issuing a debit card on the Productfy system.

ACH Identity Verification follows the same waterfall as standard KYC, except that it performs identity verification checks based only on the following information:
- Name
- Address

# Step 1 - Execute KYC Verification
::alert[Note: In your onboarding flow it's recommended to have an extra step for users to verify the information they entered before calling our KYC service. This will reduce the amount of typos submitted]
::alert[Note: In your onboarding flow please include guidance for your users to submit information exactly as it matches their government issued ID. This will ensure a higher pass rate through KYC]

Use the **Execute KYC Verification API** to run KYC on a specific person.

[View GraphQL code](mutation:executeKycVerification)

This step performs all required watchlist checks and attempts to verify the person’s identity. The API call will return important information on the user's KYC validation results.

Under the **watchlistsCheckResult** object, the **watchlistsCheckPassed** field which will return true if the user was not found on any of the relevant watchlists, false if a match was found, and null if this check has not yet been completed.

Under the **identityVerification** object, the **identityVerified** field will return true if the user’s identity has been verified and false if the user’s identity was determined to be invalid. If **identityVerified** is null, that means there are still additional steps that must be completed for KYC. In that case, the **nextStep** field will determine which of the following KYC steps to perform next:

- nextStep value of 'K' = Knowledge-Based Authentication (KBA)
- nextStep value of 'D' = Document Verification Service (DVS)

## Testing Execute KYC API in QA

If you are in a QA environment and want to see the different pass and fail scenarios of each of these KYC levels, the system allows you to do this based on the last letter of the first name of the Person ID you are testing with. See the chart below for which letters at the end of the first name will trigger which KYC scenario. 

| Last Letter of First Name   | KYC Scenario      | 
| ------------------------------- |:-----------:| 
| A - G  |  Automatic pass of level 1    | 
| H - I  |  Will fail when KBA answers are submitted |
| J - L |  Will pass when KBA answers are submitted |
| M - O |  Will fail if the DVS images are uploaded |
| P - R |  Will pass if the DVS images are uploaded |
| S - V |  Will take the actual DVS result from our vendor when DVS images are uploaded |

# Step 2 - Knowledge-Based Authentication (KBA)

If a user’s identity has not yet been verified, the **nextStep** field returned from the **executeKycVerification API** call might point you to use **Knowledge-Based Authentication (KBA**) to complete KYC.

In this step, you must use the **kbaQuestionnaire API** to retrieve KBA questions and present them to the user to answer. The questions are generated from various data sources and are specific to each user. Some users may be required to answer a higher percentage of KBA questions correctly in order to be verified, depending on the outcome of the previous KYC step.

[View KBA Questionnaire API](query:kbaQuestionnaire)

To submit the answers, you must use the **kbaAnswers API** and pass in the **questionnaireId** returned from the **kbaQuestionnaire API** that was used to retrieve the KBA questions. Additionally, each answer must be associated with a **questionId** that ties it to the relevant KBA question. NOTE - to view the **nextStep** and **identityVerified** fields after submitting KBA Answers, you must call the **executeKycVerification** API again. 

[View KBA Answers API](mutation:kbaAnswers)

# Step 3 - Document Verification Service (DVS)

If a user’s identity has not yet been verified, the **nextStep** field returned from the **executeKycVerification API** call might point you to use **Document Verification Service (DVS)**. In this step, the user must upload a photo ID, such as passport or driver’s license, to verify their identity. The information in the user’s identification documents are compared against the data provided at signup to verify the user. Validation checks are also performed on the photo IDs to ensure the IDs are authentic and unaltered. DVS is the final step in the KYC flow.

## Native Mobile Integrations - Integrate IDScan Web Libraries Directly
For native mobile app implementations, integrate IDScan's web libraries to your app. We will point you to specific sections of IDScan's web library documentation here: [https://docs.idscan.net/dvs/dvs-web-api/web-library-v1.html](https://docs.idscan.net/dvs/dvs-web-api/web-library-v1.html)

You will need the following additional configuration value for your IDScan setup:
- **DVS License Key** - Send your Productfy representative the URL of the page in your app (this includes native mobile apps) where you will execute the DVS web library from to obtain the License Key. You will use the License Key in your web library installation. The web library will check the URL it’s running on, obtain the domain, and validate the domain via IDScan’s license server. 
- **Verification Token** - Use this value: `pk_4c258a95-864a-478c-b153-ccd8d0ef6d51` for QA and `pk_e72417e2-4a7c-4559-8408-ca23d712322b` for Production. NOTE - IDScan may refer to this as the Secret Key in their documentation.

Here is the process to follow within IDScan's documentation:
1. Install web libraries - follow instructions [here](https://docs.idscan.net/dvs/dvs-web-api/web-library-v1-installation.html).
2. (Optional) Decide on [configuration settings](https://docs.idscan.net/dvs/dvs-web-api/web-library-v1-config-settings.html) and [style customizations](https://docs.idscan.net/dvs/dvs-web-api/web-library-v1-css-customization.html).
3. Code to [event handlers](https://docs.idscan.net/dvs/dvs-web-api/web-library-v1-event-handlers.html)
4. Integrate web libraries to your app

### Give Productfy the IDScan Request ID

After the user has submitted their images via the web libraries above, you should have the IDScan Request ID returned to you. You will need to call the **Process DVS API** to send Productfy the IDScan Request ID. Productfy will update its system with the results of the DVS scan.

[View GraphQL code](mutation:processDocumentVerificationAndLivenessTestRequest)

## Desktop Web Integrations - Implement Mobile Handoff from Desktop Web
For desktop web implementations, we need to execute a 'mobile handoff' to send the user from your desktop app to the user's mobile phone to complete drivers license and selfie photo submission. This will take advantage of the higher quality cameras on mobile phones (versus desktop/laptop computers) to increase the pass rate of your users. To do this mobile handoff, we leverage IDScan's SMS text message solution which sends users a link on their mobile phone to complete online document submission via the browser on their phone and a generic IDScan site that invokes the phone camera and collects the images. 

Your web app should present the user a page that informs them they need to enter their mobile number to get a URL texted to them for completion of their identity validation. To  initiate this process you will use IDScan's **[DVS Online Rest API](https://docs.idscan.net/dvs/dvs-online/sms.html#4-send-a-new-sms-message)** (step 4, #2) to send the user a text message.

Your web UI could look something like this:

![DVS SMS Handoff.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/DVS_SMS_Handoff_d8e45303ee.png)

NOTE - To comply with TCPA regulations, you need to display this message on the same screen where the user is providing their mobile phone number: *Consistent with the terms of your Card Agreement and to prevent fraud, you authorize us to authenticate you by sending you a text message when you attempt to log into your account. Text messaging rates may apply.*

Upon submitting, you could display a message like this:

![DVS SMS Handoff submit.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/DVS_SMS_Handoff_submit_e94982b1d7.png)

Your customer will get a text message to the number provided that looks like this:

![DVS SMS sample.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/DVS_SMS_sample_d60cd76409.png)

The link will take them to an IDScan site that invokes the phone camera to gather the images and verify identity:

![DVS Widget Photo.PNG](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/DVS_Widget_Photo_8962995432.PNG)

When the user has submitted their images, Productfy receive results from IDScan and will do 2 things:
1. Update the **identityVerified** field to true or false depending on the results of the user's submission. This is the key field the Productfy system looks at to ensure a user has passed identity validation.
2. Trigger a [KYC Status Webhook](/docs/api/webhooks#kyc-status) to your application. This will inform you the results of the user's submission from their phone.

### ID Scan API Call:
See IDScan's documentation on their DVS Online Rest API **[here](https://docs.idscan.net/dvs/dvs-online/sms.html#4-send-a-new-sms-message)** (step 4, #2). This is the API that will be used to send the user a text message to their phone, along with metadata identifiers that tell IDScan and Productfy which user on the system is using DVS.

You will need the following additional configuration value for your API call:
- **SMS API Token** - Use this value: `sk_e98e56f2-75ad-4220-8a02-5760deb00f59` for QA and `sk_e3d57c10-cc0b-4c8a-8440-984b5b4f96f6` for Prod. 

You will need to provide the following information in the header of the ID Scan API:
|   Header Field | Value |
|:------------:|:-----------------:|
|     Host    |       Your HTTP client URL or IP address that will send the request     |
| Accept |       application/json     |
| Authorization |       Bearer <your IDScan SMS API token provided above here>     |
| Content-Type |       application/json     |
|  Content-Length  |     Calculated by your HTTP client code     |

You will need to provide the following information from the user in the request body of the ID Scan API:
|   Field  | Value |
|:------------:|:-----------------:|
|     Email    |       email       |
|  First Name  |     firstName     |
|   Last Name  |      lastName     |
| Phone Number |       phone     |
| sendSms |       true     |

You will need to provide the following information from the user in the metadata section of the request body of the ID Scan API:
|   Field  | Value |
|:------------:|:-----------------:|
|     personId    |    Include the Productfy person ID (format = Pfy_P-XXXXXXXX)       |
|  tenantDeploymentEnvironmentId  |  Include your Productfy environment ID (format = Pfy_TnntDeployEnv-XXXXXXXX)     |

See the code snippet below to get started:

```markup {.collapsible collapsible=true} title="DVS Online API sample code"
POST https://api-dvsonline.idscan.net/api/ValidationRequests HTTP/1.1
Host: sampleapp.com
Accept: application/json
Authorization: Bearer <YOUR_TOKEN_HERE>
Content-Type: application/json
Content-Length: 106

Request body:
{
    "firstName": "John",
    "lastName": "Smith",
    "phone": "+12133458345",
    "email": "test@email.com",
    "sendSms": true,
    "metadata": { 
        "personId": "Pfy_P-ciUUC444G",
        "tenantDeploymentEnvironmentId": "Pfy_TnntDeployEnv-sub1M2istage"
    }
}
```

Once a POST call is made to the ID Scan API above, the user will receive a text message as outlined above. 

In IDScan's response message to the API, they will include their request ID value, which may be useful in troubleshooting. See sample response message:

```markup {.collapsible collapsible=true} title="DVS Online API response message"
{
    "requestId": "9baf71fd-979e-4a8a-a649-08da1979af1b"
}
```




Validate customer identities and riskiness to meet compliance requirements

![Tokenization_Your Logo goes here.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Tokenization_Your_Logo_goes_here_7b7ff64baa.png)


# Overview

Card Tokenization is an optional feature that enables your customers to load their debit or credit cards into Apple Pay, Google Pay, and Samsung Pay. This will enable your users to load physical and virtual payment cards into their phone for use at any physical location that accepts Apple, Google, or Samsung Pay.

Tokenization is currently available for Visa cards. We expect support for Mastercard to be forthcoming.

# Prerequisite for Tokenization
Because this is an optional feature, you must explicitly request it and it must be in your contract. You may add Tokenization to your contract by contacting your account manager or email support@productfy.io

# Enabling Tokenization
Once the contract and payment is executed for Tokenization, the servicing team will engage you to kick off the tokenization process. We do not expect for you to have to do any system integration to enable Tokenization. This process can be run in parallel while you are implementing one of our card products:
- [Debit Card Implementation Guide](/docs/guides/debit)
- [Secured Credit Card](/docs/guides/scc)

Tokenization will go live only after you are able to transact on your live card product.

## Submit Paperwork
Fill out the highlighted sections, sign, and submit the following documents to support@productfy.io:
- [AppleConfidentialityAgreement.pdf](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Apple_Confidentiality_Agreement_dd176f6773.pdf)
- [ApplePayProgramManagerClientTC.Productfy.Template.v1.0.docx](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Apple_Pay_Program_Manager_Client_TC_Productfy_Template_v1_0_c7025a2bae.docx)
- [PaymentCardNetworkTokenizationForm.ProductfyTemplate.v2.0.docx](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Payment_Card_Network_Tokenization_Form_Productfy_Template_v2_0_433a528eba.docx). For the Terms & Conditions, use the template provided in Tokenization section of the appropriate [Debit Card Compliance Guide](/docs/guides/debit#compliance) or [Secured Credit Card Compliance Guide](/docs/guides/scc#compliance). The language is the same as [Productfy's Payment Card Tokenization ToS](https://www.productfy.io/payment_card_tokenization_tos) that we use for our own cards.

## Submit Media Assets
Submit the following media assets to support@productfy.io:

### Logo
A 100x100 logo of the company in png.
It is recommended that the logo be at least 72 dpi.
Example:

![e919d252-498e-4f18-a10e-a366b2313de9.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/e919d252_498e_4f18_a10e_a366b2313de9_074220b34d.png)

### Card Art
- 1536x969 pixels
- For Mastercard debit cards, the debit identifier needs to be in Mastercard approved font: FF Mark Medium 11.5pt & Mark Regular.
- Rounded corners are not allowed
- PNG format
- RGB
- Has an alpha channel
Example:
![1ea96271-f3e2-41bb-b5d0-18fda58cb390.png](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/1ea96271_f3e2_41bb_b5d0_18fda58cb390_dfc38fb71d.png)

# Testing
It is not possible to test tokenization in a test environment.

Tokenization.svg

Load debit and credit cards into Apple Pay, Google Pay, and Samsung Pay

Card Tokenization

Secured Credit Card.svg

Secured Credit Card (Beta)

# Overview
Virtual accounts are flexible holding accounts on the Productfy system that store value for a customer. Most commonly these accounts are used to hold customer deposits of U.S. dollars, however the virtual account structure does allow them to be used to store non-monetary data (e.g. rewards, tokens, etc.). 

Virtual accounts will show balances, transactions, and can have money moved with them over ACH or spending done on them via debit cards. Just like regular bank checking accounts, virtual accounts get an account number and routing number that can be used for ACH. Additionally, virtual accounts get pass-through FDIC insurance up to $250,000. 

## Funding Virtual Accounts
There are a variety of ways to get money on to a virtual account:
- A customer can link a third party bank account and transfer money in via ACH. See our Account Linking and ACH implementation guides for more information.
- A customer or company can use the account number and routing number from the virtual account on the Productfy system to deposit money from another source (like setting up direct deposit from their employer for their paycheck, or depositing funds from a company that asks for account number and routing number to initiate an ACH transaction of their own).

## Settlement 
Virtual accounts are backed by an FBO account (For-Benefit-Of) opened at our partner bank where the aggregated funds for the virtual accounts are stored. You will also need to fund a reserve account used as buffer in the case of disputes, fraud, returns and other anomalies.

## Prerequisites
Before creating a virtual account, you need to be sure the following is in place:
- A valid Person ID or Organization ID is created (see [Getting Started Guide](/docs/guides/gettingStarted#root))
- KYC or KYB is passed, depending on whether you have a human customer or business customer (see the [KYC](/docs/guides/kyc#root) and [KYB](/docs/guides/kyb#root) guides)

# Step 1 - Create Virtual Account Product
You will need to go through a one-time setup task of creating your Virtual Account product on the Productfy system, which gives you the **financialProductId** you need in subsequent API calls. 

[View Create Virtual Account Product API](mutation:createVirtualAccountProduct)

# Step 2 - Creating Virtual Accounts
To create a virtual account, simply use the Create Virtual Account API below. Enter the financialProductID from step 1, and the person ID or Organization ID of the entity (who must have already passed KYC or KYB). Your system will most likely need to store the Virtual Account ID that gets returned. 

Virtual accounts can be associated with either a Person ID (if the owner is a human), an Organization ID (if the owner is a business), or both a Person ID and Organization ID together (if a business is granting an employee access to a subset of the business’s funds). 

Note - ACH transfer limits will get applied depending on whether the virtual account is a business account or consumer account, which is dictated by the accountUsageType field. Productfy’s standard limits are below:

| accountUsageType field | ACH Transfer Limits | 
|------------------------|---------------------------|
| P-Personal           | $10,000 per day                  | 
| B-Business            | $100,000 per day                 | 

*Note - if you are interested in raising limits beyond these defaults please talk to your Productfy representative. 

[View Create Virtual Account API](mutation:createVirtualAccount)

# Step 3 - Viewing the routing number / account number

Each virtual account automatically gets assigned an account number and routing number that can be used for ACH credits (i.e. adding money to the account), such as direct deposit of paychecks. 

::alert[Note: we currently do not support wire transfers with these account numbers]

The account number and routing number are returned to you in real-time after the [Create Virtual Account API ](/docs/api/accounts#root)call, or via the [Get Account](/docs/api/accounts#get-account) query. They can be found as follows:
- **Account Number** - use the :field[paymentAccountNumber] field as the account number that the customer can use for direct deposit. 
- **Routing Number** - use the :field[routingNumber] field within the financialServiceProvider object which is within the VirtualAccount object. 

# Step 4 - Retrieve Accounts and Details

After accounts are created, you may want to display a list of accounts and transactions to your customer. Use the **Get Multiple Accounts API** to retrieve account data for a Person ID or Organization ID. Popular fields to use are as follows:

| Data | API Field | 
|------------------------|---------------------------|
| Account Open Date | FinancialAccount.createdTs | 
| Available Balance   |  FinancialAccount.currentAvailableBalance          | 
| Transaction Date (for pending transactions)  |  FinancialTransaction.transactionTs         | 
| Transaction Date (for settled transactions)  |  FinancialTransaction.settledTs         | 
| Transaction Description  |   FinancialTransaction.description           | 

[View Get Multiple Accounts API](query:financialAccounts)

# Step 5 - Creating Transactions
In general your customers create transactions on their account through other products and features like ACH and debit cards. 

There is an API to manually create a transaction on a virtual account, which can be used for testing, and in rare cases in production (consult with your Productfy representative for more information). Note, the funds in virtual accounts must match the funds in the FBO settlement account or else there will be an out of balance situation. 

[View Create Virtual Account Transaction API](mutation:createVirtualAccountTransaction)

# Step 6 - Generating Statements
Productfy automatically generates and stores fully compliant PDF statements and triggers a [statement webhook](/docs/api/webhooks#statement-ready) when each statement is available for you to send a notification to your customers. Statements will automatically be generated at the end of every month. 

Note - in the QA environment statements will run on this same schedule. 

Use the following API to retrieve statements for a given account ID, and get the URLs necessary that will link to the PDF statement itself. 

[View Get Statements API](query:statements)


Virtual Accounts.svg

Allow customers to open accounts and store money 

Virtual Accounts

![Pay with card.jpg](https://productfy-strapi-production.s3.us-west-2.amazonaws.com/Pay_with_card_fe1e4449e3.jpg)

::alert[Note: This feature is still under development and testing and is subject to change.]
# Overview

Productfy offers the ability for you to accept credit and debit card payments in your app. The money from these payments can settle to your own account, or your customer's accounts seamlessly. Additionally, these payments can integrate with Productfy's Virtual Accounts if you want to build a real-time transfer of money between users on the platform. 

# Features
- Accept Visa, Mastercard, Discover and American Express card payments within your app
- Customizable payment form prevents your app from seeing card information and needing to be PCI compliant
- Optional integration with Productfy Virtual Accounts to facilitate real-time sender-to-receiver transfer of funds
- Optional ability to add fees to payments for an additional revenue stream
- Process refunds and view data from Productfy's Client Portal (coming soon)

# Implementation Process
1. Work with your Productfy representative to finalize contract terms
2. Submit your merchant setup request [here](https://connect.firstonboard.net/Merchant/6550e71a-8a66-ed11-a339-e4434bb7dc46)
3. Obtain your Transcenter ID and Processor ID from the GoEmerchant portal, Security Settings tab - these values will be needed for your technical integration
4. Follow the steps of the technical integration below

# Testing Card Payment Acceptance
In the test environment you can submit payments directly to our API (see Step 2), however in production you must use the hosted iFrame to retrieve cryptograms to be used in place of card numbers in the API.

# Step 1 - Integrate Hosted iFrame

You will display an iFrame in your app that generates a cryptogram for the card information that can be used in a subsequent API call to process payments. 

You will need to include the **iFrame** as well as a **script** that will initialize the iframe. Use the **URL**, **Transcenter ID**, and **Processor ID** from the portal. 

## iFrame Code

```markup
<!-- <iframe id="firstpay-iframe" 
src="https://secure-v.goemerchant.com/secure/PaymentHostedForm/v3/CreditCard" 
data-transcenter-id="[Transcenter Id Goes Here]" data-processor-id="[Processor Id Goes 
Here]" data-transaction-type="Sale" data-manual-submit="false"></iframe> 
```

## Initialization Script

```markup
<script 
src="https://secure-v.1stpaygateway.net/secure/PaymentHostedForm/Scripts/firstpay/firs
tpay.cryptogram.js"
id="firstpay-script-cryptogram" type="text/javascript" data-transcenter="[Transaction 
Center Id goes here]" data-processor="[Processor Id goes here]" 
data-type="Sale"></script> 
```

## Customizing The iFrame

The javascript code sample above will loop through all of the stylesheets in your site and look for all instances of classes with **firstpay** in them.  All the classnames inside of the iframe use selectors with **firstpay** in them so it’s possible to style the iframe content as long as you mount overriding stylesheet before the javascript initiates.

| Class                             | Class Description        | 
| ------------------------------- |:-----------:| 
| firstpay-container    |  The div element in the iFrame where the form element is loaded   | 
| firstpay-form   |  The form element   | 
| firstpay-form-row    |  The div element representing each field in the form and its label   | 
| firstpay-label    |  Label element for a form input   | 
| firstpay-input    |  Text input or select element   | 
| firstpay-validation-error   |  Div element for validation errors for each firstpay-input element  | 
| firstpay-button    |  Button element for manual form submits   | 

### Sample Stylesheet
```markup

iframe#firstpay-iframe {
  border: none;
  height: 300px;
}

.firstpay-form-row input, .firstpay-form-row select { 
  border: 1px solid #c3c3c3;
  border-radius: 4px;
  font-size: 16px;
  padding: 8px 6px;
}

.firstpay-form-row label {
  font-size: 14px;
  font-family: sans-serif;
}

.firstpay-form-row + .firstpay-form-row  {
  margin-top: 8px;
}
```
## Communicating With The Form
After a cryptogram is generated you will need to submit the cryptogram to productfy using the **Create Merchant Transaction API**. The implementation details are up to your application’s workflow but the iFrame will emit message events that you can use to capture changes to the iFrame form state.

```markup
// Add event listener for dispatched message from iframe https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage

window.addEventListener("message", (event) => {
  // Check if event data exists and it is an event from the firstpay iframe
  if (event && event.data && event.data.firstpay) {
    switch(event.data.type) {
      /*
       * These are the data types that the iframe will postMessage to 
       * the parent window. Some of these may be useful to drive the UI 
       * (e.g. loading indicators, error messages) At a minimum you will need to 
       * handle `newCryptogram` which will contain the cryptogram that needs to 
       * be sent to Productfy via [graphql mutation].
       */
      case 'formReady':
        // form loaded and ready
        break;
      case 'generatingCryptogram': 
        // form page has sent a request to generate a cryptogram
        break;
      case 'newCryptogram':
        // cryptogram successfully generated; set cryptogram in form to submit to pfy
        const { code, cryptogram, expMonth, expYear, first6, last4, success } = event.data;

        if (!success) {
          // show client error
          //setAppError('Generic error message');
        }
        
        // Store cryptogram to send to Productfy later
        // setCryptogram(cryptogram);
        break;
      case 'cryptogramFailed':
         // cryptogram failed to generate
         const { message, exception } = event.data;
        
        // Message contains user-friendly error message, show client error
        // setAppError(message);
        
        // exception contains detailed information about failure, log 
        // logAppError(exception);
        break
    }
  }
  return;
}, false);
```
# Step 2 - Create Merchant Transaction API

The **Create Merchant Transaction API** will take the cryptogram generated above by the iFrame. On top of taking the cryptogram and the transaction amount, the billing information is required.

Optional features with this API:
- Enter the **destinationAccountId** of a virtual account on Productfy for cases where the card payment is being sent to a user's virtual account that is on Productfy. This will automatically create a transaction on the virtual account. 
- Enter the **requestorPersonId** or **requestorOrganizatonId** to tie the payment to the Person or Organization in the Productfy system
- Enter **transactionFees** if you would like to add on a surcharge to the credit card payment. 

Notes:
- There is an additional version of this API for testing purposes, which would take the credit card information in the clear vs. the cryptogram.
- The ipAddress of the end user is required.

## Request parameters
| Parameter                             | Description        | 
| ------------------------------- |:-----------:| 
| ipAddress    |  the end user IP address   | 
| transactionAmount   |  the total amount of the merchant transaction, including any fees.   | 
| transactionFees    |  the transaction fees if any   | 
| transactionDescription   |  the description of the merchant transaction   | 
| crytpogram  |  the cryptogram that contains the encrypted card data  | 
| billingName   |  the name associated to the billing information  | 
| billingStreet  |  the billing street address   | 
| billingCity  |  the billing city   | 
|  billingState |   the billing state. 2-character value is recommended  | 
| billingZip  |    the billing zip code. 5-character value is recommended | 
| billingCountry  |   the billing country. US is the recommended value  | 
|  orderId |   A unique order id. If not provided by the client, this id will be auto generated.  | 
| requesterPersonId  |  the Productfy requester person ID. It is an optional field.   | 
|  requesterOrganizationId |    the Productfy requester organization ID. This is an optional field. | 
| destinationAccountId  |  the Productfy destination financial account ID if this transaction's recipient is a Productfy account.   | 

## CreateMerchantTransactionTest API (QA environment only):
This API can be used for testing purposes only and doesn't require the cryptogram from the iFrame above. This may be useful if you just want to test out basic card payment functionality while building your app. 
```markup
mutation createMerchantTransactionTest {
  createMerchantTransactionTest(
merchantTransactionWithCreditCardRequest: {
billingCity: "", 
billingCountry: "", 
billingName: "", 
billingState: "", 
billingStreet: "", 
billingZip: "", 
creditCardCVV: "", 
creditCardExpirationMonth: "", 
creditCardExpirationYear: "", 
creditCardNumber: "", 
destinationAccountId: "", 
ipAddress: "", 
requesterOrganizationId: "", 
requesterPersonId: "", 
transactionAmount: 0, 
transactionDescription: "", 
transactionFees: 0}) {
    ... on MerchantTransaction {
      orderId
      referenceNumber
      authCode
      billingCity
      billingCountry
      billingName
      billingState
      billingStreet
      billingZip
      destinationAccountId
      lastFourDigits
      refundAmount
      refundDate
      refundReferenceNumber
      refundType
      requesterOrganizationId
      requesterPersonId
      transactionAmount
      transactionDate
      transactionDescription
      transactionFees
      transactionStatus
    }
    ... on UserError {
      __typename
      errors {
        key
        message
      }
    }
  }
}
```
**CreateMerchantTransaction API:**

```markup
mutation createMerchantTransaction {
  createMerchantTransaction(
merchantTransactionRequest: {
billingCity: "", 
billingCountry: "", 
billingName: "", 
billingState: "", 
billingStreet: "", 
billingZip: "", 
crytpogram: "", 
destinationAccountId: "", 
ipAddress: "", 
orderId: "", 
requesterOrganizationId: "", 
requesterPersonId: "", 
transactionAmount: 1.5, 
transactionDescription: "", 
transactionFees: 1.5}) {
    ... on MerchantTransaction {
      orderId
      referenceNumber
      authCode
      billingCity
      billingCountry
      billingName
      billingState
      billingStreet
      billingZip
      destinationAccountId
      lastFourDigits
      refundAmount
      refundDate
      refundReferenceNumber
      refundType
      requesterOrganizationId
      requesterPersonId
      transactionAmount
      transactionDate
      transactionDescription
      transactionFees
      transactionStatus
    }
    ... on UserError {
      __typename
      errors {
        key
        message
      }
    }
  }
}

```
# Step 3 - Refund Handling
In order to submit refunds, you will have an available API  to call. You will need to pass the reference number associated with the sale transaction and the refund amount. The refundType return parameter can be ‘credit’ or ‘void’, depending if the transaction has already been settled.

## Request parameters
| Parameter                             | Description        | 
| ------------------------------- |:-----------:| 
| referenceNumber    |  the transaction reference number  | 
| transactionAmount   |  the total amount of the merchant transaction, including any fees.  |  

## Response parameters
| Parameter                             | Description        | 
| ------------------------------- |:-----------:| 
| referenceNumber    |  the unique reference number for this transaction from the merchant gateway. This is used for requesting a refund. | 
| transactionStatus   |  the transaction status should be only Declined or Refund accepted  |  
|  refundReferenceNumber  |   the reference number of the refund (if any) |  
| refundAmount   |  the refund amount if the refund was requested  |  
|  refundType  |  the refund type (Void, Refund)  |  

The GraphQL endpoint is defined as follows:
```markup
mutation refundMerchantTransaction {
  refundMerchantTransaction(referenceNumber: "", transactionAmount: "") {
    ... on UserError {
      __typename
      errors {
        key
        message
      }
    }
    ... on MerchantRefundTransaction {
      referenceNumber
      transactionStatus
      refundAmount
      refundReferenceNumber
      refundType
    }
  }
}
```
# Step 4 - Settlement Of Funds
When a sale transaction is successfully submitted, it will be in an APPROVED state. We will receive a batch for the settled transactions daily from the processor. Once we receive the batch we will automatically update the status to SETTLED or VOIDED to the corresponding transactions. The status change will be reflected in through the query API.

# Step 5 - Handling Chargebacks
Productfy will trigger a chargeback webhook to you when we are notified that a chargeback has been initiated by one of your customers. Upon receiving this webhook, you will need follow chargeback processes to supply necessary information through the portal. Contact your Productfy representative for more information. 

# Step 6 - Viewing Your Data

We are offering a query graphQL API endpoint so our client can retrieve in-flight or processed transactions as well as retrieving a transaction by reference number.

Merchant Payments.svg

Process credit and debit card payments from customers 