Using Users API

📘

Contents:

  1. Definitions
  2. Overview
  3. Scopes
  4. User Statuses
  5. Fields
  6. Field IDs
  7. Field 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

Scope

Meaning

TRANSFER

General access to the Transfers API. Access to this scope is required for all transfers.

ACH

Access to create payment methods (attach bank accounts) to Users

DEBIT_CARD_L2

Higher Limits Card Processing

User Statuses

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

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

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:

{
    "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