Introduction

Safello offers a simple API that lets new users buy bitcoin within 30 seconds, using modern authentication och localized purchase methods.

Overview

Each app connected to the API needs to have:

The flow is as follows:

  1. The user asks to authenticate through the app using the suitable authentication method for their country.
  2. The app asks the API to initiate the authentication and gets a “redirect_url” as well as a “polling_url”.
  3. The app redirects to this “redirect_url” (e.g. ://bankid/xxx) while polling the “polling_url” to see whether the user has proceeded with the authentication.
  4. Once they’re authenticated, the response from the polling will be an “access_token” that can be used to place orders.
  5. The users asks to place an order through the app using their localized payment method.
  6. The app sends the “access_token” to the API together with the payment method and the desired purchase amount. The API again returns a “redirect_url” and a “polling_url”.
  7. The app redirects to the “redirect_url” (e.g. ://swish/xxx) while polling the “polling_url” to see whether the payment has been sent.
  8. Once the payment is sent, the “polling_url” will eventually return a message telling the app that the purchase was successful.

EXAMPLE-START

API endpoint:

https://api.safello.com

EXAMPLE-END

Initialize authorization

The first thing we want to do is to authenticate our user in order to receive an access_token. For this to work, we need to send a request to the /auth endpoint, specifying what authentication method we want out user to use, as well as our APP_SECRET

For now, the only supported authentication method is bankid – short for the Swedish BankID system.

This will trigger a request in the user’s installed authentication app.

EXAMPLE-START

Example Request:

curl https://api.safello.com/v1/auth/bankid \
  -H "app-secret: APP_SECRET"
fetch('https://api.safello.com/v1/auth/bankid', {
  headers: {
    'app-secret': APP_SECRET,
  }
})

Example Response:

{
  redirect_url: "://bankid?autostarttoken={BANKID_TOKEN}&redirect={REDIRECT_URL}",
  polling_url: "https://api.safello.com/v1/auth/bankid/status?ref={BANKID_TOKEN}"
}

EXAMPLE-END

Verify authorization

Using the polling_url returned from the previous request, we can poll the Safello API to know whether the user has approved the authentication or not in their app.

Again, we’ll need to provide the APP_SECRET to prove that we initialized the request.

EXAMPLE-START

Example Request:

curl https://api.safello.com/v1/bankid/status?ref=9c86ae20-86e3-401b-b756-a9f39349815c
  -H "app-secret: APP_SECRET"
fetch('https://api.safello.com/v1/bankid/status?ref=9c86ae20-86e3-401b-b756-a9f39349815c', {
  headers: {
    'app-secret': APP_SECRET,
  }
})

Example Response:

{
  access_token: {ACCESS_TOKEN}
}

EXAMPLE-END

Create order

Now that you have an access_token, you can create orders on behalf of the logged-in Safello user.

An order request must contain 4 parameters:

For now, the only payment method supported is the Swedish Swish system (swish) and the only cryptoCurrency available for purchase is btc.

EXAMPLE-START

Example Request:

curl https://api.safello.com/v1/order
  -H "Content-Type: application/json"
  -H "access-token: ACCESS_TOKEN"
  -d '{"fiatAmount": 3, "fiatCurrency": "sek", "cryptoCurrency": "btc", "receivingAddress": "1Podd5C1jFpVditRv1qpXkXX5PQFjC1XF5", "method": "swish"}'
fetch('https://api.safello.com/v1/order', {
  method: "POST",
  headers: {
    'access-token': ACCESS_TOKEN,
  },
  body: {
    fiatAmount: 3, 
    fiatCurrency: "sek", 
    cryptoCurrency: "btc",
    receivingAddress: "1Podd5C1jFpVditRv1qpXkXX5PQFjC1XF5",
    method: "swish",
  },
})

Example Response:

{
  redirect_url: "://swish?ref={SWISH_ID}",
  polling_url: "https://api.safello.com/v1/order/{ORDER_ID}"
}

EXAMPLE-END

Verify order

Finally, we use the returned polling_url to check whether the user has confirmed the payment in their app.

Once the response status returns paid, you can be sure that the payment has successfully been received and that the user’s requested cryptocurrency amount will soon be sent to their wallet.

EXAMPLE-START

Example Request:

curl https://api.safello.com/v1/order/GEQ445I
  -H "access-token: ACCESS_TOKEN"
fetch('https://api.safello.com/v1/GEQ445I', {
  headers: {
    'access-token': ACCESS_TOKEN,
  },
})

Example Response:

{
  status: "paid"
}

EXAMPLE-END