Create a User
To create a new user we require the following user data:
- First name
- Last name
- Email
- Country
- Mobile Phone number
Country needs to be in ISO 3166 alpha-2 format, ie. US.
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
Oops, something is missing.We could not find the original source to display this content.
Request
Response
{
"walletAddress": "0x0000000000000000000000000000000000000000",
"walletType": "EVM"
}
{
"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>",
"walletType": "EVM"
}'
- 2.Then pass back the signature alongside the wallet address
Oops, something is missing.We could not find the original source to display this content.
Request
Response
{
"walletAddress": "0x0000000000000000000000000000000000000000",
"walletType": "EVM",
"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>",
"walletType": "EVM",
"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.
Oops, something is missing.We could not find the original source to display this content.
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.
Oops, something is missing.We could not find the original source to display this content.
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
Oops, something is missing.We could not find the original source to display this content.
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 2mo ago