Users is in Beta
To enable users on your Wyre account please contact [email protected]
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:
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:
- Create User
- Get Approved
- 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:
- Filter the fields returned by either create user or get user endpoints for those which are
OPEN - Collect data for one or more of these open fields to your end user
- Submit this data to Wyre
- 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
CLOSEDif fraud/compliance problems have been detected. Wyre customer support followup is required - or the user status may transition back to
OPENif 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 | Approved transfer scope is required for access to the Swaps API. |
| ACH | Approved ACH scope is required to activate ACH direct debits for users. |
| DEBIT_CARD_L2 | Approved L2 scope is required for higher limit card purchases. *Note, Wyre always by default supports credit cards as well. |
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 required for your integration depend on the scopes you want to support.
| fieldId Value | Field Type | Description | Scope Required |
|---|---|---|---|
firstName | STRING | First name of the end user | Transfer, ACH |
lastName | STRING | Last name of the end user | Transfer, ACH, DEBIT_CARD_L2 |
cellphoneNumber | CELLPHONE | the cellphone number of the account holder | ACH, DEBIT_CARD_L2 |
email | the email address of the account holder | ACH, DEBIT_CARD_L2 | |
residenceAddress | ADDRESS | the residence address of the account holder | Transfer, ACH, DEBIT_CARD_L2 |
dateOfBirth | DATE | the date of birth of the person, e.g. 1990-01-01 | Transfer, ACH, DEBIT_CARD_L2 |
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. +15554445555 |
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 |