Settings API Calls

Add a UID

POST /wallet/add-uid

Begin adding a UID (email address or SMS phone number) to the wallet. WingCash will send a random code through the specified communication channel. After your app receives a response from this API call, it should prompt the user to enter the received code. Once the user inputs the code, your app should call POST /wallet/add-uid-confirm to finish adding the UID.

Permission Required:
 

change_settings. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Request JSON Object:
 
  • login (string) – The email address or phone number to add. The formatting is flexible: email addresses may be capitalized and phone numbers may contain dashes and parentheses, depending on the country.
  • uid_type (string) – Optional. If provided, must be either email or phone.
  • countries (array) – If the login value is a phone number, this field is required. It is a list of capitalized two letter country codes. WingCash will try to parse the phone number using the formatting conventions of each of the listed countries. If more than one country is listed, and more than one of those countries matches the number, WingCash will send a different code to each matched phone number.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object with these attributes:

    attempt_id
    A string that identifies this attempt to add a UID.
    secret
    A string that authenticates the user’s device for the duration of the attempt to add a UID.
    code_length
    The length of the code the user should enter. The length is currently either 6 or 9 digits depending on the authentication flow type, but WingCash may expand the code length if necessary.
    unauthenticated
    A mapping of the UID strings the user is currently attempting to authenticate. Maps the UID to original and country. original is the UID in a human format, such as a formatted phone number or an email address with capitalization.
    revealed_codes
    In WingCash development sandboxes and testing environments, this is a list of human-readable strings that reveal the authentication codes sent to the user through email, SMS, or another channel. This allows testers to skip the communication channel. In production, this attribute does not exist.
  • 400 Bad Request – The parameters are not valid. The response body contains an InvalidRequest object.
  • 401 Unauthorized – The access token is missing or not valid. See Unauthorized Response.
  • 403 Forbidden – The access token is valid but the app is not authorized to access this function.

Finish Adding a UID

POST /wallet/add-uid-confirm

Finish adding a UID (email address or SMS phone number) to the wallet. The app calls this after POST /wallet/add-uid.

Permission Required:
 

change_settings. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Request JSON Object:
 
  • attempt_id (string) – Required. The attempt_id received from WingCash through POST /wallet/add-uid.
  • secret (string) – Required. The secret received from WingCash through POST /wallet/add-uid.
  • code (string) – Required. The code entered by the user.
  • replace_uid (string) – Optional. If provided, and the code entry is successful, WingCash will remove the specified UID from the wallet while adding the new UID. This is a way to let users “edit” their email address or phone number.
  • g-recaptcha-response (string) – Conveys the response provided by the invisible ReCAPTCHA widget. This field is required when WingCash detects excessive attempts to guess passwords or authentication codes.
Status Codes:

Remove a UID

POST /wallet/remove-uid

Remove a UID from the wallet.

WingCash requires users to have at two factors (of different types) for authentication. This API call will respond with an InvalidRequest if the user attempts to remove too many factors.

Permission Required:
 

change_settings. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Request JSON Object:
 
  • uid (string) – Required. The UID to remove.
Status Codes:

Change Password

POST /wallet/change-password

Change the user’s authentication password.

Permission Required:
 

change_settings. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Request JSON Object:
 
  • current_password (string) – Required. Must match the user’s current password.
  • new_password (string) – Required. Must be at least 8 characters long. Up to 100 characters are accepted.
  • g-recaptcha-response (string) – Conveys the response provided by the invisible ReCAPTCHA widget. This field is required when WingCash detects excessive attempts to guess passwords or authentication codes.
Status Codes:

Set a Device Password

POST /wallet/set-device-password

Set a device-specific password intended for biometric authentication. The password must be stored on the device using a secure, user-initiated mechanism such as Apple Touch ID or Android Keystore. Once a device-specific password is set, the device can use that password to refresh access tokens (see POST /token/refresh) or sign in using direct authentication (see POST /aa/signin).

To call this API, you must prompt the user to enter their password. WingCash will generate and return a device-specific password. WingCash stores only a hash of the device-specific password.

The device-specific password is accepted from one device only. If the user removes the device from their wallet, the device-specific password will no longer be accepted.

A device can have more than one device-specific password by varying the access_method field. For example, if the device supports authentication with both a fingerprint and facial recognition, you can store a different password for each method.

Calling this API call more than once with the same device and same access_method causes the device-specific password to be replaced with a new password. The old password will no longer be accepted.

Use POST /wallet/remove-device-password to remove the password.

Permission Required:
 

change_settings. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Request JSON Object:
 
  • current_password (string) – Required. Must match the user’s current password. (Must be the user’s main password; device-specific passwords are not accepted for this field.)
  • g-recaptcha-response (string) – Conveys the response provided by the invisible ReCAPTCHA widget. This field is required when WingCash detects excessive attempts to guess passwords or authentication codes.
  • access_method (string) – Required. Provide a string that describes the type of authentication to be used with the device-specific password, such as fingerprint or face. Must contain only ASCII letters, digits, and underscores. Up to 100 characters are accepted.
Status Codes:

Remove a Device Password

POST /wallet/remove-device-password

Remove a device-specific password. After calling this, the user will no longer be able to use the device-specific password for authentication, but the user’s wallet will still be connected to the device and access tokens related to the device will still work.

Permission Required:
 

change_settings. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Request JSON Object:
 
  • access_method (string) – Required. Provide the same access_method your app provided when setting the device-specific password.
Status Codes:

Change Name

POST /wallet/change-name

Change the name of the individual or business profile connected with the wallet.

Permission Required:
 

change_settings. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Request JSON Object:
 
  • first_name (string) – Required for individual profiles. Maximum 50 characters.
  • last_name (string) – Required for individual profiles. Maximum 50 characters.
  • title (string) – Required for business profiles. Maximum 100 characters.
  • dba (string) – Optional for business profiles. Configures the business DBA (Doing Business As) name. Maximum 100 characters.
Status Codes: