NFT Checkout with Crypto Payout

This is best suited for quick integrations where the developer does not want to build their own UI. The Sardine Risk SDK is natively integrated into the checkout form.

Example URL

Goal By the end of this guide, you should be able to open a new window with Sardine NFT Checkout, either in a new tab or in a new browser window, and receive payout to a wallet of your choice.

Implementing NFT Checkout

Before we start, you’ll need the following parameters

jsonSchema
{
  "title": "Authorization Parameters",
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "A unique Client Identifier issued by Sardine for an integration. This is safe to be exposed to the public internet. This is needed for client side JS"
    },
    "clientSecret": {
      "type": "number",
      "description": "The Secret Key is associated with a specific Client ID. It must be kept secret."
    },
  },
  "required": ["clientId", "clientSecret"]
}

1. Obtain authorization token

The next step is to obtain the clientToken, which is a unique identifier for each session and user.

Make a POST request to /v1/auth/client-tokens using Basic Auth by passing base64 encoding of <clientId>:<clientSecret>

The body of this request is used to send information about the NFT and the user to Sardine. More information about this endpoint can be found here

jsonSchema
{
  "title": "clientToken Request",
  "type": "object",
  "properties": {
    "customerId": {
      "type": "string",
      "description": "ID of Customer that can be passed, in lieu of Sardine creating one"
    },
    "referenceId": {
      "type": "string",
      "description": "Unique ID that should be passed to refer to this transaction. Status of this transaction will be fetched using this field as the key"
    },
     "expiresIn" : {
          "type" : "string",
          "description" : "Time in seconds until the NFT will expire"
        },
    "nft" : {
      "type" : "object",
      "description": "Metadata about NFT that needs to be passed",
      "properties": {
        "name": {
          "type" : "string",
          "description" : "Name of the NFT"
        },
        "collection": {
          "type" : "string",
          "description" : "Collection the NFT belongs to"
        },
        "price" : {
          "type" : "number",
          "description" : "Cost of the NFT in `currencyCode`"
        },
        "currencyCode" : {
          "type" : "string",
          "description" : "Fiat currency payment happens in",
          "example" : "usd"
        },
        "imageUrl" : {
          "type" : "string",
          "description" : "Url which is hosting the image of the NFT"
        },
      },
      "required" : ["name","price","currencyCode","imageUrl","expiration"]
    },
    "taxRates": {
                    "type": "object",
                    "description": "Which contains rates for countries/regions in ISO3166-2 format.",
                    "properties": {
                      "US": {
                        "type": "string",
                        "description": "Countrycode like US. It's percentage, US: 10 means 10% tax for all US",
                        "example": "US = 10"
                      },
                      "US-NY": {
                        "type": "string",
                        "description": "countrycode-subdivisions like US-NY. \"US-NY\": 13 means 13% for NY state.",
                        "example": "US-NY = 13"
                      },
                      "US-CA": {
                        "type": "string",
                        "example": "US-CA = 20",
                        "description": "countrycode-subdivisions like US-CA. \"US-CA\": 20 means 20% for CA state."
                      }
                    }
                  },
    "identityPrefill" : {
      "type" : "object",
      "description" : "User information that can be prefilled into the Checkout UI",
      "properties" : {
        "firstName" : {
          "type" : "string",
          "description" : "First name of buyer"
        },
        "lastName" : {
          "type" : "string",
          "description" : "Last name of buyer"
        },
        "dateOfBirth" : {
          "type" : "string",
          "description" : "Date of Birth of buyer in YYYY-MM-DD format"
        },
        "emailAddress" : {
          "type" : "string",
          "description" : "Verified email address of buyer"
        },
        "phone" : {
          "type" : "string",
          "description" : "Verified phone number of buyer"
        },
        "address" : {
          "type" : "object",
          "properties" : {
            "street1" : {
              "type" : "string",
              "description" : "Street address"
            },
            "street2" : {
              "type" : "string",
              "description" : "Suite, Apartment number etc"
            },
            "city" : {
              "type" : "string",
              "description" : "City in address"
            },
            "regionCode" : {
              "type" : "string",
              "description" : "2 letter state code"
            },
            "postalCode" : {
              "type" : "string",
              "description" : "Zip code or equivalent"
            },
            "countryCode" : {
              "type" : "string",
              "description" : "2 letter ISO country code"
            }
          }
        }
      }
    }
    },
  "required": ["referenceId"]
}

A sample request would look like below

http
{
  "method": "POST",
  "url": "https://api.sandbox.sardine.ai/v1/auth/client-tokens",
  "headers" : {
    "Authorization" : "Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0",
  },
  "body" : {
  "referenceId": "42eadcb0-4a93-45af-9c8c-d295db5aeb6c",
  "customerId": "adf02ae2-f633-11ec-b939-0242ac120002",
  "expiresIn" : 600,
  "nft": {
    "name": "NFT #1",
    "price": 100,
    "currencyCode": "USD",
    "contractAddress": "0x7fC0344254E1663C2eF24e3c063cbec231525C20",
    "imageUrl": "https://gateway.nftcompany.io/ipfsQmSAQm4gbhjSeUk7fuYppHd7Z8dfWpBvnFmqFSKqkrUJPM",
    "network" : "ethereum"
  },
  "identityPrefill": {
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "2000-01-01",
    "emailAddress": "foobar@gmail.com",
    "phone": "+19254485826",
    "address": {
      "street1": "123 Main st",
      "street2": "",
      "city": "irvine",
      "regionCode": "CA",
      "postalCode": "02747",
      "countryCode": "US"
    }
  }
  }
}

If the request is successful, you should receive a response that contains the clientToken, which is needed to create the Checkout

Use your base64 encode( clientId:clientSecret ) to make a call

Constraints

referenceId - unique
expiresIn - 300 to 3600 ( 5min - 1hr)

Success Response:

{
  "clientToken": "<client_token>",
  "expiresAt": "2022-07-07T21:32:29Z"
}

Error Response:

{
  "message": "Duplicate referenceId",
  "code": "INVALID_PARAMS"
}

A fully complete URL will look like this:

2. User goes through Sardine Checkout

Once the Checkout URL is opened, the Sardine flow takes over and guides the user through the Checkout

3. Embed NFT checkout

Once the checkout URL has been generated, it can be embedded into your web app as an iframe, with event handlers to catch events sent by the iframe.

Sample code to embed NFT checkout

Recommended size is width=500, height=700 for new window

<head>
<script>
/*
  The widget and begins its flow after this line,
  and will update the parent about its state via postMessage events.
*/
function attachListener() {
  document.addEventListener("message", (data) => console.log("Event is", data))     }
</script>
  </head>
  <body>
  <div class="center">
    <iframe src="https://crypto.sandbox.sardine.ai/?address=0x10b195F7Be9B120efd05C58f16650A13f533eA33&clientToken=123-asd-456&show_features=true" onload="attachListener()" id="sardine_iframe" />
  </div>
</body>

Recommended size is width=500, height=700 for new window

<head>
<script>
/*
  The widget and begins its flow after this line,
  and will update the parent about its state via postMessage events.
*/
function attachListener() {
  document.addEventListener("message", (data) => console.log("Event is", data))     }
</script>
  </head>
  <body>
  <div class="center">
    <iframe src="https://crypto.sandbox.sardine.ai/?address=0x10b195F7Be9B120efd05C58f16650A13f533eA33&clientToken=123-asd-456&show_features=true" onload="attachListener()" id="sardine_iframe" />
  </div>
</body>

import { useRef, useEffect, useCallback } from 'react'


SardineIframe = ({ eventHandler }) => {
const iframeRef = useRef(null)
const postMessageListener = useCallback((event) => {
if(event.source !== iframeRef?.current?.contentWindow) {
  return;
}
eventHandler(event.data)
})

useEffect(() => {
	window.addEventListener('message', postMessageListener)
return () => {
  window.removeEventListener('message', postMessageListener)
}
},
[iframeRef])

return <iframe src="https://crypto.sandbox.sardine.ai" ref={iframeRef}/>
}

4. Get Confirmation of Trade Status

When the user presses Confirm, Sardine will fire a order.confirmed webhook, along with the frontend events which can be caught with event handlers.

Sardine will emit events which can be handled to understand user action

There are three events that can be caught using event handlers.

Expired - The user didn’t complete the transaction within the expiration paramter

{
  "status" : "Expired",
  "data" : {
    "referenceId" : "42eadcb0-4a93-45af-9c8c-d295db5aeb6c"
  }
}

Processed - The payment is complete, and the NFT can now be transferred the user.

{
  "status" : "Processed",
  "data" : {
    "price": 100,
    "orderId": "123e4567-e89b-12d3-a456-426614174001",
    "transactionFee": 2,
    "networkfee": "0.35"
    "currencyCode": "usd",
    "paymentMethod": "card",
    "createdAt": 12312321312,
    "contractAddress": "0x10b195F7Be9B120efd05C58f16650A13f533eA33",
    "referenceId" : "42eadcb0-4a93-45af-9c8c-d295db5aeb6c"
  }

}

Declined - The transaction was declined due to issues with their payment method or risk profile.

{
  "status" : "Declined",
  "data" : {
    "referenceId" : "42eadcb0-4a93-45af-9c8c-d295db5aeb6c"
  }
}

There are three events that can be caught using event handlers.

Expired - The user didn’t complete the transaction within the expiration paramter

{
  "status" : "Expired",
  "data" : {
    "referenceId" : "42eadcb0-4a93-45af-9c8c-d295db5aeb6c"
  }
}

Processed - The payment is complete, and the NFT can now be transferred the user.

{
  "status" : "Processed",
  "data" : {
    "price": 100,
    "orderId": "123e4567-e89b-12d3-a456-426614174001",
    "transactionFee": 2,
    "networkfee": "0.35"
    "currencyCode": "usd",
    "paymentMethod": "card",
    "createdAt": 12312321312,
    "contractAddress": "0x10b195F7Be9B120efd05C58f16650A13f533eA33",
    "referenceId" : "42eadcb0-4a93-45af-9c8c-d295db5aeb6c"
  }

}

Declined - The transaction was declined due to issues with their payment method or risk profile.

{
  "status" : "Declined",
  "data" : {
    "referenceId" : "42eadcb0-4a93-45af-9c8c-d295db5aeb6c"
  }
}

Sardine also initiates webhooks which can be used to determine the state of the Checkout. Check Webhook for full details.

5. Initiate Payout

Sardine allows for payments to be settled in cryptocurrency. Once an Order has been created, it can be used to trigger a Payout. Sardine can accept multiple recipients which receive different percentages of the entire Order. Check Create Payouts API for full request and responses.

The amount is determined based on the orderId that is passed.

http
{
  "method": "POST",
  "url": "https://api.sandbox.sardine.ai/v1/payouts",
  "body" : {
    "referenceId" : "7ce511d0-c973-4744-b819-d933a248ae51",
    "orderId" : "324e02055-8235-4405-bc22-1dd06ac87d4e",
    "payoutConfiguration" : {
      "recipients" : [
        {
          "payoutType" : "crypto",
          "walletAddress" : "0x18739187238123123123",
          "tokenAddress" : "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "network" : "ethereum",
          "percentage" : "100"
        }
      ]
    }
  },
  "headers" : {
    "Authorization" : "Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0",
  }
}

Once a Payout has been created, webhooks are sent to confirm the different states of the payout. Check Webhooks for more information on which webhooks will be triggered. The state of each Payout can also be queried through the Fetch Payout API

6 . Testing and Verification

Once the defined URL has been set and triggered, it should open an iframe that goes through the user flows for Sardine’s NFT checkout. This should match the screen show on the [User Flows Page]

theme: success

You should now be able to route users to the Sardine Checkout Widget via your defined URL where they can instantly buy NFTs!

Onboarding and Testing

On/Off Ramps

NFT Checkout

NFT Checkout with Crypto Payout

Implementing NFT Checkout

1. Obtain authorization token

2. User goes through Sardine Checkout

3. Embed NFT checkout

4. Get Confirmation of Trade Status

5. Initiate Payout

6 . Testing and Verification

Onboarding and Testing

On/Off Ramps

NFT Checkout

​Implementing NFT Checkout

​1. Obtain authorization token

​2. User goes through Sardine Checkout

​3. Embed NFT checkout

​4. Get Confirmation of Trade Status

​5. Initiate Payout

​6 . Testing and Verification

Implementing NFT Checkout

1. Obtain authorization token

2. User goes through Sardine Checkout

3. Embed NFT checkout

4. Get Confirmation of Trade Status

5. Initiate Payout

6 . Testing and Verification