Getting Started

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 and API docs 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 provide step-by-step walkthroughs of what to know and how to build our major features. Our API documentation 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.

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:

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:

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:

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:

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:

Note: the Social Security Number must be unique amongst Person IDs in QA and Production

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

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

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:

Finally, you may want to save custom data fields for your Persons or Organizations. The Productfy system allows that through the following APIs:

Custom data can later be retrieved using the following APIs:

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

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.

To set up webhooks, navigate to the Webhooks menu on your Client Portal URL. Next, click on the Edit Webhook button.

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.

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