Agio SDK

Appearance

Return to top
On this page

Widget Integration Guide ​

This document will provide you with a comprehensive overview of integrating our widget seamlessly into your application. Leveraging URL query parameters, you can customize the widget to suit your application's needs.

Table of Contents ​

  1. High-Level Overview
  2. Token Flow Chart
  3. Available Query Parameters
  4. Integration Example
  5. Live Example
  6. Handling Errors
  7. Customizing the Widget
  8. Further Assistance

High-Level Overview ​

The integration process consists of embedding the Iframe widget into your application. This can be done by using an <iframe> tag with various query parameters that allow customization. The key aspect is the token parameter, which authorizes access to the widget functionalities.

Token Flow Chart ​

txt
+--------------------------------------------------------------------+
|                       ** Step 1: Initiate **                       |
|       Widget Integrator server sends API key to Agio API           |
+--------------------------------------------------------------------+
                                  ⬇️
+--------------------------------------------------------------------+
|                   ** Step 2: Token Generation **                   |
|            Agio API generates JWT Init Token in response           |
+--------------------------------------------------------------------+
                                  ⬇️
+--------------------------------------------------------------------+
|                ** Step 3: Iframe Initialization **                 |
|    Widget Integrator initializes Iframe with JWT Token as query    |
+--------------------------------------------------------------------+
                                  ⬇️
+--------------------------------------------------------------------+
|                   ** Step 4: Token Exchange **                     |
|       Iframe Widget exchanges JWT Init Token for a User Token      |
+--------------------------------------------------------------------+
                                  ⬇️
+--------------------------------------------------------------------+
|                 ** Step 5: User Authorization **                   |
|   Iframe Widget authorizes client user's requests with User Token  |
+--------------------------------------------------------------------+
+--------------------------------------------------------------------+
|                       ** Step 1: Initiate **                       |
|       Widget Integrator server sends API key to Agio API           |
+--------------------------------------------------------------------+
                                  ⬇️
+--------------------------------------------------------------------+
|                   ** Step 2: Token Generation **                   |
|            Agio API generates JWT Init Token in response           |
+--------------------------------------------------------------------+
                                  ⬇️
+--------------------------------------------------------------------+
|                ** Step 3: Iframe Initialization **                 |
|    Widget Integrator initializes Iframe with JWT Token as query    |
+--------------------------------------------------------------------+
                                  ⬇️
+--------------------------------------------------------------------+
|                   ** Step 4: Token Exchange **                     |
|       Iframe Widget exchanges JWT Init Token for a User Token      |
+--------------------------------------------------------------------+
                                  ⬇️
+--------------------------------------------------------------------+
|                 ** Step 5: User Authorization **                   |
|   Iframe Widget authorizes client user's requests with User Token  |
+--------------------------------------------------------------------+

Getting the Init Token ​

To get the initiation token for the KYC SDK, you need to execute the generateKycSdkInitToken GraphQL mutation.

🚨 Note 🚨: This mutation should be called from a backend service.

Always call this mutation from a backend service. Never call this mutation from the frontend. If you call this mutation from the frontend, you will expose your API token to the public. This will allow anyone to generate initiation tokens for your API token.

Base URL: ​

  • production: https://hasura.agiodigital.com/v1/graphql
  • development: https://dev.hasura.agiodigital.com/v1/graphql

GraphQL Mutation: ​

graphql
mutation {
  generateKycSdkInitToken(
    input: {
      apiToken: "a66bdfbe-ba27-4741-9365-3ee7b3b5c0e2"
      externalUserId: "john_doe_01"
      amount: 100
      ttl: 5400
      externalUserFirstName: "John"
      externalUserLastName: "Doe"
      externalUserEmail: "example@email.com"
      currency: "USD"
    }
  )
}
mutation {
  generateKycSdkInitToken(
    input: {
      apiToken: "a66bdfbe-ba27-4741-9365-3ee7b3b5c0e2"
      externalUserId: "john_doe_01"
      amount: 100
      ttl: 5400
      externalUserFirstName: "John"
      externalUserLastName: "Doe"
      externalUserEmail: "example@email.com"
      currency: "USD"
    }
  )
}

Using CURL: ​

For Production:

bash
curl -X POST \
     -H "Content-Type: application/json" \
     --data '{"query":"mutation { generateKycSdkInitToken(input: { apiToken: \"a66bdfbe-ba27-4741-9365-3ee7b3b5c0e2\", externalUserId: \"john_doe_01\", amount: 100, ttl: 5400, externalUserFirstName: \"John\", externalUserLastName: \"Doe\", externalUserEmail: \"example@email.com\", currency: \"USD\", }) }"}' \
     https://hasura.agiodigital.com/v1/graphql
curl -X POST \
     -H "Content-Type: application/json" \
     --data '{"query":"mutation { generateKycSdkInitToken(input: { apiToken: \"a66bdfbe-ba27-4741-9365-3ee7b3b5c0e2\", externalUserId: \"john_doe_01\", amount: 100, ttl: 5400, externalUserFirstName: \"John\", externalUserLastName: \"Doe\", externalUserEmail: \"example@email.com\", currency: \"USD\", }) }"}' \
     https://hasura.agiodigital.com/v1/graphql

For Development:

bash
curl -X POST \
     -H "Content-Type: application/json" \
     --data '{"query":"mutation { generateKycSdkInitToken(input: { apiToken: \"a66bdfbe-ba27-4741-9365-3ee7b3b5c0e2\", externalUserId: \"john_doe_01\", amount: 100, ttl: 5400, externalUserFirstName: \"John\", externalUserLastName: \"Doe\", externalUserEmail: \"example@email.com\", currency: \"USD\", }) }"}' \
     https://dev.hasura.agiodigital.com/v1/graphql
curl -X POST \
     -H "Content-Type: application/json" \
     --data '{"query":"mutation { generateKycSdkInitToken(input: { apiToken: \"a66bdfbe-ba27-4741-9365-3ee7b3b5c0e2\", externalUserId: \"john_doe_01\", amount: 100, ttl: 5400, externalUserFirstName: \"John\", externalUserLastName: \"Doe\", externalUserEmail: \"example@email.com\", currency: \"USD\", }) }"}' \
     https://dev.hasura.agiodigital.com/v1/graphql

Using Axios: ​

ts
import axios from "axios";

const BASE_URL = "https://hasura.agiodigital.com/v1/graphql";
// For development use:
// BASE_URL="https://dev.hasura.agiodigital.com/v1/graphql";

axios
  .post(BASE_URL, {
    query: `
    mutation {
      token: generateKycSdkInitToken(input: {
        apiToken: "a66bdfbe-ba27-4741-9365-3ee7b3b5c0e2",
        externalUserId: "john_doe_01",
        amount: 100,
        ttl: 5400,
        externalUserFirstName: "John",
        externalUserLastName: "Doe",
        externalUserEmail: "example@email.com",
        currency: "USD",
      })
    }
  `
  })
  .then((response) => {
    const token = response.data.data.token;
    console.log("Token:", token);
  })
  .catch((error) => {
    console.error("Error:", error);
  });
import axios from "axios";

const BASE_URL = "https://hasura.agiodigital.com/v1/graphql";
// For development use:
// BASE_URL="https://dev.hasura.agiodigital.com/v1/graphql";

axios
  .post(BASE_URL, {
    query: `
    mutation {
      token: generateKycSdkInitToken(input: {
        apiToken: "a66bdfbe-ba27-4741-9365-3ee7b3b5c0e2",
        externalUserId: "john_doe_01",
        amount: 100,
        ttl: 5400,
        externalUserFirstName: "John",
        externalUserLastName: "Doe",
        externalUserEmail: "example@email.com",
        currency: "USD",
      })
    }
  `
  })
  .then((response) => {
    const token = response.data.data.token;
    console.log("Token:", token);
  })
  .catch((error) => {
    console.error("Error:", error);
  });

Available Query Parameters ​

token ​

  • Type: String
  • Description: Your API token to authorize access to the widget.
  • Constraints:
    • Minimum length of 1.
    • Must be a valid JWT format with a valid sub claim.
  • Errors: invalid_token_message

lang ​

  • Type: String (optional, nullable)
  • Description: Specifies the language of the widget interface.
  • Accepted values:
    • pt, pt-br, br → Transforms to pt-BR
    • us, usa, gb, en-gb → Transforms to en
    • Values must be within the supported language codes.
  • Errors: invalid_lang_message

step ​

  • Type: String (optional, nullable)
  • Description: Determines the step or phase the widget should load.

kyb ​

  • Type: Boolean (optional, nullable)
  • Description: Enables or disables the "Know Your Business" feature.
  • Default: false

useAlternativeKycLevel ​

  • Type: Boolean (optional, nullable)
  • Description: Switch between primary and alternative KYC levels.
  • Default: false

cleanWallet ​

  • Type: Boolean (optional, nullable)
  • Description: Option to mark the wallet address as clean. This will skip the KYT check.
  • Default: false

walletAddress ​

  • Type: String (optional, nullable)
  • Description: Specify a default wallet address.
  • Default: Empty string.

walletAddressDisabled ​

  • Type: Boolean (optional, nullable)
  • Description: Disables the modification of the wallet address.
  • Default: false

paymentsDisabled ​

  • Type: Boolean (optional, nullable)
  • Description: Disables the payment functionalities.
  • Default: true

kytDisabled ​

  • Type: Boolean (optional, nullable)
  • Description: Disables the "Know Your Transaction" feature.
  • Default: false

kycDisabled ​

  • Type: Boolean (optional, nullable)
  • Description: Disables the "Know Your Customer" feature.
  • Default: false

debug ​

  • Type: Boolean (optional, nullable)
  • Description: Activates debug mode to assist in troubleshooting.
  • Default: false

currency ​

  • Type: String (optional, nullable)
  • Description: Specifies the default currency to be used.
  • Accepted values: Must be among the supported currencies.
  • Transform: Values are converted to uppercase.
  • Default: USD
  • Errors: not_supported

amount ​

  • Type: Number (optional, nullable)
  • Description: Specifies the default amount.
  • Constraints: Must be non-negative.
  • Default: 0

amountEditable ​

  • Type: Boolean (optional, nullable)
  • Description: Enables the modification of the amount by the user.
  • Default: false

Integration Example ​

html
<iframe
  src="https://develop.agiodigital.com/#/widget?token=INIT_TOKEN&lang=en&step=1&kyb=true&useAlternativeKycLevel=false&cleanWallet=true&walletAddress=YOUR_WALLET_ADDRESS&walletAddressDisabled=false&paymentsDisabled=true&kytDisabled=false&kycDisabled=false&debug=true&currency=USD&amount=1000"
  height="600"
  frameborder="0"
  style="width: 100%;"
></iframe>
<iframe
  src="https://develop.agiodigital.com/#/widget?token=INIT_TOKEN&lang=en&step=1&kyb=true&useAlternativeKycLevel=false&cleanWallet=true&walletAddress=YOUR_WALLET_ADDRESS&walletAddressDisabled=false&paymentsDisabled=true&kytDisabled=false&kycDisabled=false&debug=true&currency=USD&amount=1000"
  height="600"
  frameborder="0"
  style="width: 100%;"
></iframe>

Live Example ​

🔗 Open in new tab

Query Parameters ​

json
{}
{}

Notes: ​

  1. Replace INIT_TOKEN and YOUR_WALLET_ADDRESS with appropriate values.
  2. You can adjust the width and height attributes of the <iframe> to better fit the widget within your application.
  3. Always ensure that the token is securely generated and passed to the widget to prevent unauthorized access.
  4. You can remove or add any optional parameters based on your application's requirements.

Handling Errors ​

When a parameter is not valid or encounters an issue, the widget will handle errors internally and display the corresponding message, e.g., invalid_token_message or invalid_lang_message. Ensure your backend handles token generation and validation appropriately to prevent errors when accessing the widget.

Customizing the Widget ​

URL query parameters are a convenient way to customize the behavior and appearance of the widget based on your application's needs. By understanding and using the available parameters, you can provide a seamless experience for your users.

Need Further Assistance? ​

For any questions or concerns, please reach out to our support team.