Transactions

Transactions Overview

Once you've integrated String into your Game and logged-in a Player, your Game can execute a transaction. String enables many types of transactions for Web3 games including NFT purchases, fiat on/off ramps, cross-chain payments, and more.

Transactions are an asset exchange between String and the Player that consists of at least two transfers. The Player sends fiat currency to String on traditional rails, and in exchange String sends Digital Asset(s) to the Player on the blockchain. (Or the reverse, for a fiat off-ramp). String acts as the counterparty and "merchant of record" for all fiat payments. Digital Asset transfers depend on the transaction type, but generally involve either (1) String interacting with the Game's smart contract to send an NFT to the Player (I.e. NFT purchase); or (2) String sending a cryptocurrency token from its internal treasury directly to the Player's wallet (i.e. fiat on-ramp).

Executing a transaction generally consists of four main steps:

1. Login the Player
2. Request a quote
3. Submit payment information
4. Execute the transaction

String sends a receipt to the Player's email address once the transaction is executed.

📘

String SDKs

Each of String's products - String Checkout, String Direct, String Unity - utilizes an SDK that wraps String's capabilities into just a few API calls. Follow our implementation guides to start using the SDKs.

However, Games can directly access String's API to make specific calls, retrieve information, or test certain aspects of their integration. See our API Reference for endpoint information.

Transaction Types

🚧

Smart Contract Functions

Note that the transaction type for most NFT purchases requires the Game to onboard the smart contract that controls the asset, and will determine the transaction type (I.e. NFT Purchase vs. Swap vs. Transfer. Make sure you register your smart contract and associated functions prior to requesting a quote and/or executing a transaction.

NFT Purchase (Primary sale)

1. String charges the Player's fiat payment method (credit/debit card or bank account);
2. String sends the NFT to the Player's wallet (via smart contract function or purchasing the NFT and transferring).

NFT Swap (Secondary marketplace):

1. String charges Player 1's (NFT buyer) fiat payment method;
2. String executes a function on the Game's marketplace swap contract (i.e. Atomic_Match) to transfer the NFT from Player 2 (NFT seller) to Player 1. To call the swap contract, String sends the purchase price of the NFT in native currency (i.e. ETH) to the contract, which sends the sale amount to Player 2 as part of the swap.

Fiat On-Ramp

1. String charges Player's fiat payment method;
2. String sends cryptocurrency to the Player from String's treasury.

Fiat Off-Ramp:

1. The Player transfers cryptocurrency to String's wallet;
2. String sends USD to Player's bank account.

Cross-Chain Payment

1. The Player transfers cryptocurrency to String's wallet;
2. String sends cryptocurrency on a different chain to the Player or to the Game's smart contract.

🚧

Verified Players Only

Remember, String can only execute Transactions for verified Identities. Ensure Players are logged-in before requesting a quote or executing a transaction.

Requesting a Quote

Prior to executing a Transaction, Platforms must provide Players a "Quote," or an estimate of the cost of the transaction that accurately reflects the USD (or local currency) price of the asset being purchased and the associated fees. Quotes are valid for 15 seconds.

For all String products, requesting a quote involves sending a transaction payload object to String's API or the relevant SDK. The payload contains the relevant transaction details including the asset being transferred, the price of the asset, the relevant blockchain the smart contract details, the Player's wallet address, and any other relevant information required to estimate the cost of the transaction.

An example payload may look like the following to request a quote for String Checkout:

{
	assetName: "AeroAce #123",
	collection: "String Racers",
	imageSrc: "https://gateway.pinata.cloud/ipfs/RacerAce.png",
	imageAlt: "AeroAceNFT",
	currency: "ETH",
	price: 1.110,
	chainID: 1,
	userAddress: userAddr,
	contractAddress: "0x41e11fF9F71f51800F67cb913eA6Bc59d3F126Aa",
	contractFunction: "mintTo(address)",
	contractReturn: "uint256",
	contractParameters: [userAddr],
	txValue: "1.110 eth",
}

Which would load a transaction in the String Checkout iframe, displayed to the Player, as follows:

See the specific product implementation guides for requesting a quote with String Director String Unity.

Collect and Submit Payment Information

After you request a quote, you will need to present the Player with an option to add a payment method, or you can immediately provide payment fields for them to enter their credentials.

All String products use PCI-compliant payment systems to securely collect, store, and retrieve Player's payment information. Your Game never needs to handle, store, or otherwise be responsible for Player's sensitive payment credentials.

📘

PCI Compliance

String Checkout handles payment credentials within our secure iframe and pre-built UI. String Direct leverages individual iframes to seamlessly embed PCI-compliant payment fields in your game environment. String Unity uses a transparent credit card prefab blended into your game to accept card credentials.

In all cases, payment information is received directly by String's payment processing partners, encrypted, tokenized, and securely stored. String does not store sensitive payment credentials in our system, and thanks to our secure payment fields neither will you.

Prior to executing a transaction, the Player must submit their card details into String's secure payment fields. The Player must enter their name, card number, expiration date, and cvv number.

The Player's credentials are sent directly to String's processing partner who creates a payment token that String associates with the Player's UID. This allows String to save the Player's payment method for future use. When the Game logs-in a returning player, String will recall any previously saved payment methods.

📘

Payment Method Frontend Design

For any Games using String Direct or Unity, String's API returns the last 4 digits of the Player's card number as well as the card brand (i.e. Visa or Mastercard) when you log-in a returning Player. Display this information to show the Player which saved payment methods they have available.

Additionally, your Game should include a checkbox for the Player to indicate whether they would like to save any added payment methods for future use.

Once a payment method has been added, you can move forward to execute the transaction.

Executing a Transaction

Once the Player has accepted a valid quote, the Game can execute the transaction based on that quote.

Executing the transaction initiates all associated asset transfers. If any step fails, String will cancel the entire transaction.

For example, for a credit card NFT purchase, String will take the following steps to execute the transaction:

1. Authorize the Player's card payment
2. Call the Platform's smart contract function (I.e. mintTo(address)) to send the NFT to the Player's wallet
3. Charge the Player's card and finalize the transaction.

These steps should all take just a few seconds.

Once the Transaction is confirmed, String will return all of the relevant details, including the purchase price, a timestamp, and a transaction hash for the relevant block explorer.

Sending a Receipt

String sends an itemized email receipt to the player after each transaction, customizable with your Platform's branding, look, and feel.