Quickstart
Paygrid SDK Quickstart guide
The SDK is currently in BETA version. Feel free to report any issues or feedback you might have here.
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/sdkor
yarn add @paygrid-network/sdkBasic 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:
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
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 NodePROCESSING: 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 partiesFAILED: The payment transaction encountered an error or was reverted for some internal reason preventing the transaction from being completed.
Last updated