Users Overview

❗️

Closed Beta API

This API is in closed beta.

It contains overlapping functionality with the Accounts APIs. It is designed to eventually supersede the Accounts API eventually (for the case of individual end-users). Presently only a limited subset of functionality is available.

Be aware that it is similar but not identical to the Accounts V3 API. Be careful to use the correct documentation when integrating.

The Users API is a simple, versatile KYC system used for controlling access to the Wyre platform network. It combines requirements and user data into a single view making it easy for you to understand the next steps for a particular user across a variety of usecases and workflows.

📘

Contents:

1. Definitions
2. Overview
3. Scopes
4. User Statuses
5. Fields
6. Field IDs
7. Field Types
8. Integration Types

Definitions

• User: the end-user originating the request
• Partner: You, the Wyre integrator!
• Field: A bucket for a specific piece of user data
• Scope: A specific segment of functionality on the Wyre platform

Overview

The basic process looks like this:

1. Create User
2. Get Approved
3. Transfer!

Step 1: Creating the User

Call the create user API endpoint to create the user. This call will return a set of fields contextualized by the scopes parameter provided. User creation also may include blockchain address generation if desired.

Step 2: Get Approved

After the user is created, all user API calls require you to use masquerading on your requests. This simple pattern helps to firewall permission boundaries between users and your partner-level API credentials.

Approvals in the users system exist only in the context of scopes. The specific user requirements enforced for a given scope are determined by your partner agreement with Wyre. Because end-user requirements differ across available Wyre functionality, scopes are used to constrain the API based on the specific intent of a single user.

Broadly, to achieve user approval:

1. Filter the fields returned by either create user or get user endpoints for those which are OPEN
2. Collect data for one or more of these open fields to your end user
3. Submit this data to Wyre
4. Repeat

When there are no longer any OPEN fields, the end user is done with their turn. Our system is diligently processing their information. After this stage:

• the user status may transition to APPROVED
• or the user status may transition to CLOSED if fraud/compliance problems have been detected. Wyre customer support followup is required
• or the user status may transition back to OPEN if correctable problems were detected

Step 3: Transfer!

Now that your user is approved, you may use the transfer API on their behalf! Remember to use masquerading for requests made on behalf of your users.

Users each have their own set of custodialized balances (including all our supported fiat and crypto). This is where funds are reflected which is sent to the blockchain addresses tied to the user. Users may be used as the source or destination via the transfer API to move and exchange these funds.

Scopes

A scope is an identifier for a specific segment of functionality within the Wyre platform. In some contexts, multiple scopes can apply.

Scope	Meaning
TRANSFER	General access to the Transfers API. Access to this scope is required for all transfers.
ACH, WIRE, SAVINGS, DEBIT_CARD, CREDIT_CARD, HIGH_LIMITS, ?	coming soon

User Statuses

Users can have one of 4 statuses. These apply only within the context of a set of scopes.

Status	Description
OPEN	Waiting on data to be submitted to one or more fields. This is the initial state before any information has been submitted, or if there were correctable problems with a previous submission.
PENDING	Information has been fully submitted and is waiting on review from Wyre.
APPROVED	Information has been reviewed and accepted by Wyre
CLOSED	The Account has been closed and may not transact. Customer service followup is necessary for further actions.

Fields

All fields present on a User object are required in context of the currently specified scope(s). Each field has the following parameters:

Field Parameter	Description
value	A representation of the underlying KYC data. Actual format depends on the type of field
error	A message indicating the nature of a correctable problem. Accompanied by an OPEN status.
status	One of: OPEN: The field is awaiting user data. This is the initial state before any information has been submitted, or if there were correctable problems with a previous submission. SUBMITTED: The field value has been uploaded and accepted.

Field IDs

The field IDs your specific integration has to support depend on your integration type.

fieldId Value	Field Type	Description
firstName	STRING	First name of the end user
lastName	STRING	Last name of the end user
cellphone	CELLPHONE	the cellphone number of the account holder
email	EMAIL	the email address of the account holder
residenceAddress	ADDRESS	the residence address of the account holder
dateOfBirth	DATE	the date of birth of the person, e.g. 1990-01-01

Field Types

The field type is hard-coded to each field ID and determines the JSON format and upfront validation rules on it.

fieldType value	Description
STRING
CELLPHONE	A full cellphone number including country code e.g. [phone]
EMAIL	A correctly formatted email address
ADDRESS	An address object. Address format is: json { "street1": "1 Market St", "street2": "Suite 402", "city": "San Francisco", "state": "CA", "postalCode": "94105", "country": "US" }
DATE	Specifies a particular day. Format is YYYY-MM-DD, e.g. 1992-12-15

Integration Types

Your integration type determines the fields your system may encounter when working with users.

Name	Revision	Field IDs
OFAC Only	2	firstName, lastName, residenceAddress, dateOfBirth
tbd