Create a User
To create a new user we require the following user data:
- First name
- Last name
- Email
- Country
- Mobile Phone number
Phone numbers need to be in E.164 format, ie. +14165551234. If they are not, you will receive a 400 error when making an SMS Send call.
We only support US mobile phone numbers. Number associated to any other country or line type will be rejected and you will receive a 400 error.
- We also require that each user agree to our terms of use. The user must explicitly select a checkbox with the following label and link: “I agree to the Ratio terms of use.”
While we do not recommend capturing additional data before creating a user, there are additional user data fields required to submit a request for KYC approval. In most cases, KYC will be the next step in your user journey after creating the user, and in most cases, you will want to collect this information after the user account is created. The required fields for submitting a request for KYC approval are:
- Date of Birth
- ID type: *SSN
- ID Number
- Address Line 1
- Address Line 2
- City
- State
- Postal Code
User authentication is required to create a session. A JWT will be provided after the user authenticates, and must be included in the header of all API calls.
Any one of the three authentication factors below can be used to obtain a session token:
- Wallet (aka. Sign in With Ethereum / Connect Wallet)
- SMS One-time Passcode*
- Email One-time Passcode
You can use any combination of SMS + Email or SMS + Wallet to provide multi-factor authentication. You cannot use Email + Wallet in this scenario. Go here for more information. If you would like to propose additional authentication methods please contact us.
If you already let users connect a wallet to your application, you will be able to obtain a user session token within the scope of that same user experience. This will be especially useful for returning users; wallet auth would allow you to retrieve information about the user's account, such as their linked bank account or transaction limits, so that you can delay the second authentication factor (SMS OTP) until the moment of transaction.
Wallet authentication includes two steps:
- 1.Retrieve a challenge to be signed by the user's wallet
post
https://api.ratio.me
/v1/auth/cryptoWallet:start
Start a crypto wallet authentication flow
Request
Response
{
"walletAddress": "0x0000000000000000000000000000000000000000",
"walletNetwork": "ETHEREUM"
}
{
"challenge": "Signing in with Ratio: pUQikKqqBq1brTwt1oHhUJwlOTfshzfMEAsJaH7x1MOdN7QMOooFfj-Aujmi7sb0wJnvYqtmZtlszKdH"
}
cURL
curl --location -g --request POST 'https://api.ratio.me/v1/auth/cryptoWallet:start' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"walletAddress": "<WALLET_ADDRESS>",
"walletNetwork": "<ETHEREUM_OR_POLYGON>"
}'
- 2.Then pass back the signature alongside the wallet address
post
https://api.ratio.me
/v1/auth/cryptoWallet:authenticate
Authenticate a user's crypto wallet
Request
Response
{
"walletAddress": "0x0000000000000000000000000000000000000000",
"walletNetwork": "ETHEREUM",
"signature": "2djd2cFZ9VU2zDWvUGqeHwvbiJZfTt3BMzDctDsEW7vM2QUTgTHjeM2rpFX9ZULeic3KptUh5ehipXDFcK5ecYiX"
}
{
"sessionJwt": "eyJhbG.....",
"userMask": {
"id": "00000000-0000-0000-0000-000000000000",
"createTime": "2022-01-01T00:00:00.000Z",
"updateTime": "2022-01-01T23:59:59.999Z",
"phoneMask": "0000",
"preferredMfaMethod": "OTP_SMS"
}
}
cURL
curl --location -g --request POST 'https://api.ratio.me/v1/auth/cryptoWallet:authenticate' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"walletAddress": "<WALLET_ADDRESS>",
"walletNetwork": "<ETHEREUM_OR_POLYGON>",
"signature": "<SIGNED_CHALLENGE_STRING>"
}'
After authenticating the user, you will receive a JWT that must be provided in the Authorization header for all subsequent requests within that user session.
First, we need to send a one-time code to the user using the phone number they provided during sign-up.
post
https://api.ratio.me
/v1/auth/otp/sms:send
Send an SMS OTP to the user
Request
Response
{
"phoneNumber": "+14165551234",
}
{
"phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789",
"phoneMask": "1234"
}
cURL
curl --location --request POST 'https://api.ratio.me/v1/auth/otp/sms:send' \
--header 'Authorization: Bearer eyJ......' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"phoneNumber": "+14165551234"
}'
Once you receive the one-time code send it (with the phone id received in the first response) to the sms:authenticate endpoint to obtain a JWT.
post
https://api.ratio.me
/v1/auth/otp/sms:authenticate
Authenticate a user with an SMS OTP
Request
Response
{
"phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789",
"otp": "123456",
}
{
"sessionJwt": "eyJ............"
}
cURL
curl --location --request POST 'https://api.ratio.me/v1/auth/otp/sms:authenticate' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Authorization: Bearer eyJ......' \
--header 'Content-Type: application/json' \
--data-raw '{
"otp": "123456",
"phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789"
}'
At this point, you can create a user
post
https://api.ratio.me
/v1/users
This creates a new user
After creating a user there are three additional requirements before you can initiate payments:
You are free to complete the remaining tasks in any order, however, we recommend the sequence above.
Last modified 15d ago