Guides
Start typing to search…

PayIn component

Loop Connect's "Pay In" component renders a customizable UI for users to connect their wallet, select their token, and complete the payment authorization process.

This document outlines the interface for adding a component to a React-based project. For those who wish to utilize a Javascript native web component for rendering into any project that supports them, like Vue or Svelte, use this page as a guide for usage and types, and use our Web component guide for assistance with native web component syntax.

Payment details

The following properties ("props") are added to the LoopConnectPayIn component. Setting paymentUsdAmount is required, while all of the other properties are optional and can help you reconcile payment records with your data

<LoopConnectPayIn 
    paymentUsdAmount={199} 
    // Other optional props
/>
Property nameType or exampleDescription
paymentUsdAmount (required)number, eg. 199 (for $1.99)The amount in USD that will be charged in the equivalent selected token, expressed in cents
minimumAuthorizationUsdAmountnumber, eg. 199 (for $1.99)The minimum USD equivalent the user must authorize from their wallet in the selected token to complete the payment. If no value is set, only paymentUsdAmount is required.
suggestedAuthorizationUsdAmountnumber, eg. 199 (for $1.99)The USD equivalent the user will be suggested to to authorize, only if the minimum amount is not already authorized. This value is presented to their wallet as the default authorization amount, but they are only required to authorize the minimum.
customerRefIdstring, eg. "usr_abc1234"A reference to the user making payment
subscriptionRefIdstring, eg. "sub_abc1234"A reference to the item being purchased
invoiceRefIdstring, eg. "inv_abc1234"A reference to an invoice being paid
awaitConfirmationboolean (default is true)Controls whether confirmation of the transaction on-chain is part of the payment flow. If false, the user will only wait for the PayIn to be created before the component's state is set to "complete".

PayIn events

The LoopConnectPayIn component also accepts optional event callback handlers. The callback functions take the form (detail: EventType) => void, where EventType is a placeholder to represent the individually defined type for each event, specified below.

EventCallback typesDescription
onPayInReadyPayInReadyEventThe component has received the necessary data and is ready for user interaction.
onPayInReadyFailedPayInReadyFailedEventThe component failed to initialize.
onPayInTokenChangePayInTokenChangeEventThe user has changed the selected token they wish to pay with from the component UI
onPayInStateChangePayInStateChangeEventOnce a user initiates a payment, this component calls back with each step to allow you to provide detailed notifications for your users. Note that you can optionally enable a state notification message to be provided to the user within the component UI using the stateNotification property detailed below. Details on the payment states is provided below.
onPayInAuthorizationUpdatedPayInAuthorizationUpdatedEventThe user has updated their wallet's authorization to transfer the selected token to our contract
onPayInCustomerCreatedPayInCustomerCreatedEventA record was created for this user and their selected payment method
onPayInCreatedPayInCreatedEventThe PayIn has been received and the transaction has been sent for processing
onPayInConfirmedPayInConfirmedEventThe PayIn's transaction has been confirmed to have been written on-chain
onPayInFailedPayInFailedEventThe payment was not created because a require step failed or was canceled by the user. Note that you can optionally enable a failure notification message to be provided to the user within the component UI using the failureNotification property detailed below. Details on the failure types is provided below.

💡

Both onWalletChange and onNetworkChange (defined above as initLoopConnect properties) can be provided in the same format to the LoopConnectPayIn component for your convenience. Just note that each individual component will trigger their own provided callback for the same event occurrence, as these events are tied to the user's wallet which is a single connection shared application wide.

Callback prop types

The PayIn event callback functions receive data about the event through a single property, where each event receives an object with a different type. The following types correspond to the types specified in the "PayIn events" table above.

interface PayInReadyEvent {
    entityId: string;
}
interface PayInReadyFailedEvent {
    type: "payinReadyFailed";
    message: string;
    data: Record<string, any>;
}
interface PayInTokenChangeEvent {
    address: string;
    networkId: number;
    name: string;
    symbol: string;
    decimals: number;
    logoUrl: string;
    exchange: ExchangeRateDetails;
}
interface PayInStateChangeEvent {
    state: 
        | "idle" 
        | "confirmingBalance" 
        | "confirmingAuthorization" 
        | "updatingAuthorization" 
        | "signingMessage" 
        | "creatingCustomer" 
        | "creatingPayment" 
        | "confirmingPayment" 
        | "complete";
    message: string;
    data: /* see "onPayInStateChange states" for types */;
}
interface PayInAuthorizationUpdatedEvent {
    authorizationAmount: string;
    suggestedAuthorizationTokenAmount: string | undefined;
    minimumAuthorizationTokenAmount: string | undefined;
    tokenAddress: string;
    tokenSymbol: string;
    networkId: number;
}
interface PayInCustomerCreatedEvent {
    customerId: string;
    customerRefId: string | null;
    subscriptionRefId: string | null;
    dateCreated: number;
    merchant: {
        merchantId: string;
        merchantName: string;
        merchantRefId: string | null;
    };
    paymentMethods: {
        paymentMethodId: string;
        paymentMethodName: string;
        networkId: number;
        walletAddress: string;
        isDefault: boolean;
        token: {
            tokenId: string;
            symbol: string;
            address: string;
            decimals: number;
            exchangeRates: {
                currency: string;
                price: string;
                timestamp: number;
            }[];
        };
        preAuthorization: {
            balance: string;
            authorization: string;
        };
    }[];
}
interface PayInCreatedEvent {
    payinId: string;
    merchantId: string;
    amount: string;
    amountType: "fiat" | "token";
    billDate: number;
    invoiceId: string;
    description: string | null;
    externalInvoiceRef: string | null;
    payinType: "subscription" | "invoice";
    payinStatus:
        | "scheduled"
        | "pending"
        | "completed"
        | "failed"
        | "canceled"
        | "uncollectible"
        | "draft";
    transaction: {
        transactionId: string;
        transactionUrl: string;
        amountTransferred: string | null;
        exchangeRate: {
            currency: string;
            price: string;
            timestamp: number;
        } | null; 
    } | null;
    paymentMethod: {
        paymentMethodId: string;
        paymentMethodName: string;
        customer: {
            customerId: string;
            customerRefId: string | null;
        }
        networkId: number;
        walletAddress: string;
        isDefault: boolean;
        status: string;
        token: {
            tokenId: string;
            symbol: string;
            address: string;
            decimals: number;
            exchangeRates: {
                currency: string;
                price: string;
                timestamp: number;
            }[];
        };
        preAuthorization: {
            balance: string;
            authorization: string;
        };
    };
    payoutDestination: {
        payoutDestinationId: string;
        networkId: number;
        walletAddress: string;
    };
    dateCreated: number;
}
interface PayInConfirmedEvent<T extends "EVM" | "SOL"> {
    transaction: {
        transactionId: string;
        transactionUrl: string;
        amountTransferred: string | null;
        exchangeRate: {
            currency: string;
            price: string;
            timestamp: number;
        } | null; 
    };
    walletAddress: string;
    networkId: number;
    rpcUrl: string;
    chain: T;
    receipt: T extends "EVM" ? ethers.TransactionReceipt : number;
}
interface PayInFailedEvent {
	type:
        | "insufficientBalance"
        | "insufficientAuthorization"
  	    | "signedMessageRequired"
  	    | "customerCreationFailed"
  	    | "paymentFailed"
        | "transactionFailed";
	message: string;
	data: {
		error: Record<string, any> | undefined;
	};
}

onPayInStateChange

The onPayInStateChange event handler will receive an object which contains the state property set to one of the following string values indicating the component's current state of payment.

<LoopConnectPayIn 
    // other props
    onPayInStateChange={
        ({ state, message, data }) => console.log(`${state}: ${message}`, data);
    } 
/>
StateEvent data object typeDescription
idlePayInStateChangeEventIdleThe initial state of the component prior to initiating the payment process, as well as the state set after a payment failure
confirmingBalancePayInStateChangeEventConfirmingBalanceAwaiting a response back from the blockchain to confirm the wallet's balance is sufficient in the selected token on the wallet's current network
confirmingAuthorizationPayInStateChangeEventConfirmingAuthorizationAwaiting a response back from the blockchain to confirm the wallet's authorization is sufficient in the selected token on the wallet's current network for the contract required
updatingAuthorizationPayInStateChangeEventUpdatingAuthorizationThe wallet's authorization was insufficient and is now awaiting confirmation that the user has completed their wallet's prompt to update the amount
signingMessagePayInStateChangeEventSigningMessageAwaiting a signed message from the user's wallet which has prompted them to authorize Loop Crypto to process the payment
creatingCustomerPayInStateChangeEventCreatingCustomerAwaiting confirmation that a customer record was created, storing the user's payment method and signed message
creatingPaymentPayInStateChangeEventCreatingPaymentAll of the required checks have been confirmed and the payment is being sent for processing
confirmingPaymentPayInStateChangeEventConfirmingPaymentIf the transactions is being processed synchronously, this state indicates that the component is awaiting confirmation of the transaction on-chain
completePayInStateChangeEventCompleteThe component remains in this state once the payment data has been received and confirmed to be sufficient to process the payment

State data object types

In addition to supplying the state and a human-readable message describing the event, a unique data object containing information about the state is provided. The following types correspond to the types specified in the "onPayInStateChange states" table above.

interface PayInStateChangeEventIdle {
    /* no additional data is provided for the idle state */
}
interface PayInStateChangeEventConfirmingBalance {
    amount: string;
    walletAddress: string;
    chain: BlockchainNetwork;
    networkName: string;
    token: {
        name: string;
        logoUrl: string;
        symbol: string;
        decimals: number;
        address: string;
        networkId: number;
        exchange: {
            currency: string;
            rate: number;
            updated: number;
            provider: string;
        };
    }
}
interface PayInStateChangeEventConfirmingAuthorization {
    minimumAuthorization: string | undefined;
    contractAddress: string;
    walletAddress: string;
    chain: BlockchainNetwork;
    networkName: string;
    token: {
        name: string;
        logoUrl: string;
        symbol: string;
        decimals: number;
        address: string;
        networkId: number;
        exchange: {
            currency: string;
            rate: number;
            updated: number;
            provider: string;
        };
    }
}
interface PayInStateChangeEventUpdatingAuthorization {
    suggestedAuthorization: string | undefined;
    contractAddress: string;
    walletAddress: string;
    chain: BlockchainNetwork;
    networkName: string;
    token: {
        name: string;
        logoUrl: string;
        symbol: string;
        decimals: number;
        address: string;
        networkId: number;
        exchange: {
            currency: string;
            rate: number;
            updated: number;
            provider: string;
        };
    }
}
interface PayInStateChangeEventSigningMessage {
    walletAddress: string;
    chain: BlockchainNetwork;
    networkName: string;
    networkId: number;
}
interface PayInStateChangeEventCreatingCustomer {
    walletAddress: string;
    chain: BlockchainNetwork;
    networkName: string;
    token: {
        name: string;
        logoUrl: string;
        symbol: string;
        decimals: number;
        address: string;
        networkId: number;
        exchange: {
            currency: string;
            rate: number;
            updated: number;
            provider: string;
        };
    }
}
interface PayInStateChangeEventCreatingPayment {
    token: {
        name: string;
        logoUrl: string;
        symbol: string;
        decimals: number;
        address: string;
        networkId: number;
        exchange: {
            currency: string;
            rate: number;
            updated: number;
            provider: string;
        };
    }
    amount: string;
    walletAddress: string;
    chain: BlockchainNetwork;
    networkName: string;
    customerId: string;
    paymentMethodId: string;
}
interface PayInStateChangeEventConfirmingPayment {
    payinId: string;
    merchantId: string;
    amount: string;
    amountType: "fiat" | "token";
    billDate: number;
    invoiceId: string;
    description: string | null;
    externalInvoiceRef: string | null;
    payinType: "subscription" | "invoice";
    payinStatus:
        | "scheduled"
        | "pending"
        | "completed"
        | "failed"
        | "canceled"
        | "uncollectible"
        | "draft";
    transaction: {
        transactionId: string;
        transactionUrl: string;
        amountTransferred: string | null;
        exchangeRate: {
            currency: string;
            price: string;
            timestamp: number;
        } | null; 
    } | null;
    paymentMethod: {
        paymentMethodId: string;
        paymentMethodName: string;
        customer: {
            customerId: string;
            customerRefId: string | null;
        }
        networkId: number;
        walletAddress: string;
        isDefault: boolean;
        status: string;
        token: {
            tokenId: string;
            symbol: string;
            address: string;
            decimals: number;
            exchangeRates: {
                currency: string;
                price: string;
                timestamp: number;
            }[];
        };
        preAuthorization: {
            balance: string;
            authorization: string;
        };
    };
    payoutDestination: {
        payoutDestinationId: string;
        networkId: number;
        walletAddress: string;
    };
    dateCreated: number;
}
interface PayInStateChangeEventComplete {
    payinId: string;
    merchantId: string;
    amount: string;
    amountType: "fiat" | "token";
    billDate: number;
    invoiceId: string;
    description: string | null;
    externalInvoiceRef: string | null;
    payinType: "subscription" | "invoice";
    payinStatus: "completed";
    transaction: {
        transactionId: string;
        transactionUrl: string;
        amountTransferred: string | null;
        exchangeRate: {
            currency: string;
            price: string;
            timestamp: number;
        } | null; 
    } | null;
    paymentMethod: {
        paymentMethodId: string;
        paymentMethodName: string;
        customer: {
            customerId: string;
            customerRefId: string | null;
        }
        networkId: number;
        walletAddress: string;
        isDefault: boolean;
        status: string;
        token: {
            tokenId: string;
            symbol: string;
            address: string;
            decimals: number;
            exchangeRates: {
                currency: string;
                price: string;
                timestamp: number;
            }[];
        };
        preAuthorization: {
            balance: string;
            authorization: string;
        };
    };
    payoutDestination: {
        payoutDestinationId: string;
        networkId: number;
        walletAddress: string;
    };
    dateCreated: number;
}

onPayInFailed

The onPayInFailed event handler will receive an object which contains the type property set to one of the following string values indicating the reason the payment was not sent for processing successfully.

<LoopConnectPayIn 
    // other props
    onPayInFailed={
        ({ type, message, data }) => console.log(`${type}: ${message}`, data);
    } 
/>
Failure typeDescription
insufficientBalanceThe wallet connected does not have the sufficient amount of token equivalent to the amount of USD specified by paymentUsdAmount on the current network
insufficientAuthorizationThe user has not granted sufficient USD equivalent authorization for this token to meet the minimumAuthorizationUsdAmount (if not specified, uses paymentUsdAmount) on the wallet's current network
signedMessageRequiredThe wallet failed to sign a message to approve the transfer of the payment token
customerCreationFailedThere was a problem storing the customer's payment details
paymentFailedThere was a problem obtaining approval of the payment details having been sent for processing
transactionFailedThere was a problem while attempting to confirm a payment on-chain

State data object types

For onPayInFailed events, the data object contains an error object of the type Record<string, any>, which returns details about the error, and in most cases is a native Javascript Event object.

User interface

You can provide optional properties to allow for customization of the UI to more seamlessly match your application's look and feel.

Notifications

Property nameOptions and defaultDescription
stateNotification"eventOnly" or "embedded" (default is "eventOnly")When set to "embedded", the component will displays messaging above the payment button to provide details to the user about the current state of the payment process. No message is shown for the "idle" state.
failureNotification"eventOnly" or "embedded" (default is "eventOnly")When set to "embedded", the component will displays messaging above the payment button to provide details to the user about failures that occurred during the payment process.
confirmingNotification"eventOnly" or "embedded" (default is "eventOnly")When set to "embedded", the component will replace the payment button with details about the payment awaiting confirmation on chain when the component state is "confirmingPayment"
completeNotification"eventOnly" or "embedded" (default is "eventOnly")When set to "embedded", the component will replace the payment button with details about the payment once confirmed and the component state is "complete"

Styling

The component's UI can be customized by providing a string of CSS custom properties and values. The values assigned to the property must be valid CSS for that type of property, which corresponds to a CSS declaration. In the table below, each custom property is linked to the corresponding CSS property it represents to ensure clarity.

<LoopConnectPayIn 
    // other props
    customStyles={`
        --loop-connect-font: italic 700 1rem 'Poppins', sans-serif;
        --loop-connect-widget-shadow: 0 0 0.5rem rgba(99,99,99,0.3);
    `} 
/>
PropertyCSS property or typeDescription
--loop-connect-color-primary<color>Used as an accent color, primarily for button background, but not exclusively backgrounds
--loop-connect-color-on-primarycolorUsed as the text or accent color when shown within subcomponents colored with the primary color
--loop-connect-radiusborder-radiusDefines the roundness of box corners. Also applies to the entire widget, unless ``--loop-connect-widget-radius` overrides it
--loop-connect-color-textcolorDefines the color of text
--loop-connect-fontfontAssigns the size, weight, style and family for the font used as the main copy within the component
--loop-connect-widget-borderborderDefines the border around the entire widget
--loop-connect-widget-radiusborder-radiusDefines the roundness of the corners of the widget. Will override --loop-connect-radius if set
--loop-connect-widget-paddingpaddingSpecifies the padding around the outside of the component
--loop-connect-widget-shadowbox-shadowSpecifies the styling of the outer shadow around the component
--loop-connect-widget-backgroundbackgroundSets the background color of the component
--loop-connect-input-borderborderOverrides the default border style of input and select subcomponents
--loop-connect-input-backgroundbackgroundAssigns a background color to input and select subcomponents

💡

Note that the customStyles property can also be provided to the initLoopConnect as a property and will apply the styles to all Loop Connect components application-wide. Properties then applied to individual components will override those app-wide values, creating a cascade effect.

Quickstart example

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";

// 1. Import the package
import { initLoopConnect, LoopConnectPayIn } from "@loop-crypto/connect";

// 2. Initialize is outside of the application
initLoopConnect({
    apiKey: "your-apiKey-here",
    entityId: "your-entityId-here",
    merchantId: "your-merchantId-here",
});

// 3. Add the PayIn component to the React application
createRoot(document.getElementById("root")!).render(
    <StrictMode>
        <LoopConnectPayIn
            paymentUsdAmount={100}
        />
    </StrictMode>
);

Updated 22 days ago