Quickstart

Paygrid SDK Quickstart guide

The SDK is currently in BETA version. Feel free to report any issues or feedback you might have here.

GitHub - paygrid-tech/paygrid-sdk: Chain-abstracted payment stack for developers to build and orchestrate payment workflows.GitHub

npm: @paygrid-network/sdknpm

Overview

The Paygrid Network SDK provides developers with a chain-abstracted payment stack to build and orchestrate payment workflows. This guide will walk you through the essential steps to send your first payment intent using the SDK capabilities.

Key features:

• Chain-abstracted payment processing

• Cross-chain payment routing and settlement

• Multi-level authorization mechanism. Approval for payments can be time-bound and scope-specific, eliminating unauthorized fund transfers and fraud.

• Real-time payment status tracking

1. Install SDK & Configuration

Installation

npm install @paygrid-network/sdk

or

yarn add @paygrid-network/sdk

Basic Configuration (Optional) - Skip if you don't have an API Key

import { Paygrid, SDKConfig } from '@paygrid-network/sdk';

// Optional configuration
const config: SDKConfig = {
  apiKey: 'process.env.PAYGRID_API_KEY'  // optional
};

// Initialize SDK
const paygrid = new Paygrid(config);

2. Fetch Corridors Routes & Price Discovery (Optional)

The Paygrid SDK provides a powerful way to discover payment routes and get real-time pricing information before initiating a payment. This helps you understand the fees and execution times for different payment routes. Learn more about Corridors.

See the quickstart code below to learn how to use this feature using the SDK:

paygrid-sdk/quickstart/corridor-quotes.ts at master · paygrid-tech/paygrid-sdkGitHub

TO KEEP IN MIND:

• Always check multiple corridors: Different routes may offer better pricing or speed.

• Consider expiration time: Quotes expire after a short period (typically 5 minutes).

• Match source/destination: Ensure your payment intent uses the same networks and tokens as your selected quote.

• No corridors may be available for certain token/network combinations. Make sure to handle errors returned from the SDK

3. Payment Intent Authorization

EIP2612 Gasless Token Approval

Before submitting a payment intent, the payer must first approve the official Permit2 canonical contract to allow Paygrid to spend their tokens in the future. For tokens that support the EIP2612 standard (like USDC and DAI), you can use gasless permit approvals instead of requiring users to submit an on-chain approval transaction.

We recommend approving a max or sufficient amount to cover future payments with the same wallet and avoid repetitive approvals. Permit2 approval mechanism is secure, contracts are immutable and ownerless. Paygrid does not hold custody of any funds and cannot pull funds from wallets at any time unless explicitly permissioned.

Benefits of EIP2612 Permits

• Gasless: No need for a separate on-chain approval transaction

• Better UX: Users can approve tokens with just a signature

• Security: Time-bound and amount-specific permissions

Generating Token Permit Signatures

The SDK provides a method to construct and sign EIP-2612 gasless permits to make it easy for you.

import { ethers } from 'ethers';
import { PaymentIntentSigner } from '@paygrid-network/sdk';

// Option 1: Get the EIP-712 permit payload (for inspection or manual signing)
const permitPayload = await PaymentIntentSigner.getTokenPermitPayload(
  'USDC',                                                  // Token symbol
  'ETHEREUM',                                              // Network
  '0xPayerWalletAddress',                                   // Owner address
  BigInt(ethers.constants.MaxUint256.toString()),          // Value (infinite approval)
  Math.floor(Date.now() / 1000) + 3600,                    // Deadline (1 hour)
  provider                                                 // ethers provider (payer's wallet)
);
// permitPayload contains: { domain, types, values } for EIP-712 signing

// Option 2: Generate and sign a permit in one step
const signedPermit = await PaymentIntentSigner.generateTokenPermit(
  'USDC',                                                  // Token symbol
  'ETHEREUM',                                              // Network
  '0xPayerWalletAddress',                                   // Owner address
  BigInt(ethers.constants.MaxUint256.toString()),          // Value (default infinite approval)
  Math.floor(Date.now() / 1000) + 3600,                    // Deadline (1 hour)
  signer                                                   // ethers signer (payer's wallet)
);
// signedPermit contains: { signature, nonce, deadline }

// 3. Use the signed permit in a payment intent
paymentIntent.authorizations.initial_permit = signedPermit;

Using the Permit with a Payment Intent

Once you have the signed permit, include it in your payment intent's authorizations:

// Create your payment intent
const paymentIntent = {
  // ... payment intent details
  authorizations: {
    // Include the signed permit
    initial_permit: signedPermit
  }
};

// Sign and submit the payment intent
const response = await paygrid.signAndInitiatePaymentIntent(
  paymentIntent,
  signer
);

Supported Tokens

Currently, the following tokens support EIP2612 permits:

• USDC on Ethereum, Polygon, Optimism, Arbitrum, and Base

• DAI on Ethereum, Polygon, Optimism, Arbitrum, Base (manual)

For tokens that don't support EIP2612 (like USDT), users will still need to perform a standard on-chain approval transaction to the Permit2 contract address:

0x000000000022D473030F116dDEE9F6B43aC78BA3

After approving permit2 you need to generate and sign the payment intent permit2_permit authorization using EIP-712 typed data signature scheme:

import { ethers } from 'ethers';
import {
  PaymentType,
  ChargeBearer,
  RoutingPriority,
  PaymentIntent
} from '@paygrid-network/sdk';

// Create payment intent object
const paymentIntent: PaymentIntent = {
  payment_type: PaymentType.ONE_TIME, // options: ONE_TIME, RECURRING (recurring currently not available)
  routing_priority: RoutingPriority.AUTO, // options: COST, SPEED, BALANCED, AUTO
  operator_data: {
    id: operatorId,
    operator: operatorAddress,
    treasury: treasuryAddress,
    fee_bps: 50 // 0.5% 
    webhook_url: "https://example.com/api/webhooks"
  },
  amount: 100, // 1 USD in cents
  source: {
    from_account: payerAddress,
    network_id: 'BASE',
    payment_token: 'USDC'
  },
  destination: {
    to_account: receiverAddress,
    network_id: 'POLYGON',
    payment_token: 'USDT'
  },
  processing_fees: {
    // Payer pays for the corridor fees
    charge_bearer: ChargeBearer.PAYER,
    // REQUIRED: Include the quoteId from the corridor quote response here only if charge bearer is the payer
    quoteId: 'c344fc42-18e5-4399-8c3b-8808c8b48955'
  },
  payment_reference: 'INV-319600',
  metadata: {
    customer_id: 'ACC_10a6c98b082b',
    payment_purpose: "B2B"
  }
};

// Get authorization payload for manual signing using any web3 library  
const payload = paygrid.constructPaymentAuthorizationPayload(paymentIntent);

// Sign with user's wallet directly using the SDK
const authorization = await paygrid.signPaymentIntent(paymentIntent, signer);

4. Initiate a Payment Intent

Submit a signed payment intent for processing. It should include the returned authorization object from both generateTokenPermit and signPaymentIntent.

const response = await paygrid.initiatePaymentIntent({
  ...paymentIntent,
  authorizations: {
    permit2_permit: authorization.permit2_permit,
    initial_permit: authorization.initial_permit
  }
});

console.log('Payment Intent created and released to gateway for processing:', {
  id: response.id,
  status: response.status
});

5. Sign & Initiate Payment Intent

Combine signing and initiation in one step:

const paymentIntentResponse = await paygrid.signAndInitiatePaymentIntent(
  paymentIntent,
  signer
);

6. Fetching Payment Intent by ID

Retrieve payment intent details:

const paymentIntent = await paygrid.getPaymentIntentById(paymentIntentId);

7. Track Payment Status

Monitor payment progress:

// Option 1: Poll for status updates
const finalPayment = await paygrid.pollPaymentIntentStatus(
  paymentIntentId,
  // Optional: Specify poll interval, timeout, and abort signal
  // {
  //   pollInterval: 5000, // Poll every 5 seconds
  //   timeout: 180000,    // Timeout after 3 minutes
  //   abortSignal: controller.signal
  // }
);

// Option 2: Manual status checks
const currentStatus = await paygrid.getPaymentIntentById(paymentIntentId);
console.log('Current Status:', currentStatus.status);

Learn more about Webhooks & IPN Events

Payment Status Lifecycle

Payments progress through the following states:

• RELEASED_TO_GATEWAY: The payment intent has been successfully submitted to the Paygrid Clearing Gateway Node

• PROCESSING: The payment intent has been cleared and submitted for processing.

• COMPLETED: The payment intent has been successfully completed. This indicates that the funds have been transferred.

• SCHEDULED: The payment intent is scheduled for processing at a specific time interval or recurring cycle.

• CANCELLED: The payment intent has been cancelled by the operator or either transaction parties

• FAILED: The payment transaction encountered an error or was reverted for some internal reason preventing the transaction from being completed.