Integration Guide

A guide for merchants on how to quickly integrate their service with Small Transfers. We're happy to help - simply contact us!

Sign in

Customer signs in with Small Transfers

Show the "Sign In with Small Transfers" button when you don't have the permission to charge the customer visiting your service.

We use the following MUI code to display the button above:


    import Button from "@mui/material/Button";
    import CurrencyExchangeIcon from "@mui/icons-material/CurrencyExchange";

    <Button startIcon={<CurrencyExchangeIcon />} variant="contained" size="large">
        Sign In with Small Transfers
    </Button>

The button should point to the following URL:

You can obtain the PUBLISHABLE_KEY and configure the REDIRECT_URL on your merchant dashboard page.

Permissions

Obtain the access token

Once the customer has signed in with Small Transfers, they will be redirected to the REDIRECT_URL you provided above.

The URL will contain the code query parameter:

Redirect URL Schema

If the customer cancels the sign-in process, they will be redirected to the REDIRECT_URL with an error query parameter instead.

You exchange this authorization code for an access token:


    const response = await fetch("https://smalltransfers.com/api/v1/oauth/tokens", {
        method: "POST",
        headers: { Accept: "application/json", "Content-Type": "application/json" },
        body: JSON.stringify({
            grantType: "authorization_code",
            publishableKey: "<your publishable key>",
            secretKey: "<your secret key>",
            authorizationCode: "<authorization code>",
        }),
    });
    if (response.ok) {
        const { accessToken, customer } = await response.json();
        const { id, firstName, lastName, email, live } = customer;
    } else {
        const { message } = await response.json();
        throw new Error(`Failed to obtain authentication tokens: ${message}`);
    }

The above API call must be done on the server side, so that the secretKey and the accessToken are not exposed to the client.

Store the returned data within your session or database. To store the data in your session, you can use an encrypted HTTP-only cookie, such as iron-session.

Transactions

Charge for usage

Each time a customer makes a request to your service, charge them in Small Transfers Credits (STC).


    const response = await fetch("https://smalltransfers.com/api/v1/transactions", {
        method: "POST",
        headers: {"Content-Type": "application/json"},
        body: JSON.stringify({
            publishableKey: "<your publishable key>",
            secretKey: "<your secret key>",
            accessToken: "<access token>",
            amountMicros: <STC amount in micros>, // e.g. 3000 for 0.003 STC (where 1 STC costs 1 USD)
        }),
    });
    if (response.ok) {
        // Run your service here.
    } else {
        const { message } = await response.json();
        throw new Error(`Failed to charge the account: ${message}`);
    }

The above API call must be done on the server side, so that the secretKey and the accessToken are not exposed to the client.

If the customer has insufficient Small Transfers Credits (STC), the API call will fail with the HTTP 402 (Payment Required) status code.

If you need to obtain a new access token, the API call will fail with the HTTP 403 (Forbidden) status code.

And that's it - you have successfully integrated your service with Small Transfers! Please contact us if you have any questions.