Payto-rl NPM | npm.io

Payto-RL

payto-rl is a TypeScript library for handling Payto Resource Locators (PRLs). This library is based on the URL API and provides additional functionality for managing PRLs.

Features

🐥 Small: gzipped, distributed as minified ES modules.
📜 Standardized: Based on the URL Web API.
🏗️ Simple: Easy to implement.
🗂 Typed: Ships with types included.
🧪 Tested: Robust test coverage.
🌲 Tree Shaking: Zero dependencies, no side effects.

Installation

Install the payto-rl package using your package manager:

npm i payto-rl

pnpm add payto-rl

yarn add payto-rl

Usage

Here's an example of how to use the payto-rl package:

import Payto from 'payto-rl';

// Basic payment URL
const paytoString = 'payto://xcb/cb7147879011ea207df5b35a24ca6f0859dcfb145999?amount=ctn:10.01&fiat=eur';
const payto = new Payto(paytoString);

// Standard payment properties
console.log(payto.address);  // 'cb7147879011ea207df5b35a24ca6f0859dcfb145999'
console.log(payto.amount);   // 'ctn:10.01'
console.log(payto.value);    // 10.01
console.log(payto.network);  // 'xcb'
console.log(payto.currency); // ['ctn', 'eur']

// Update payment amount
payto.value = 20.02;
console.log(payto.amount);   // 'ctn:20.02'
console.log(payto.fiat);     // 'eur'

// Color customization
payto.colorBackground = 'ff0000';  // Red background (6-character hex)
payto.colorForeground = '000000';  // Black foreground
console.log(payto.colorBackground); // 'ff0000'

// ACH payment examples
const achPayto1 = new Payto('payto://ach/123456789/1234567'); // With routing number
console.log(achPayto1.routingNumber); // 123456789
console.log(achPayto1.accountNumber); // 1234567

const achPayto2 = new Payto('payto://ach/1234567'); // Account number only
console.log(achPayto2.accountNumber); // 1234567

// UPI/PIX payment examples (case-insensitive email)
const upiPayto = new Payto('payto://upi/USER@example.com');
console.log(upiPayto.accountAlias); // 'user@example.com'

const pixPayto = new Payto('payto://pix/user@EXAMPLE.com');
console.log(pixPayto.accountAlias); // 'user@example.com'

// Geo location example
const geoPayto = new Payto('payto://void/geo');
geoPayto.location = '51.5074,0.1278';  // Valid coordinates
console.log(geoPayto.void);     // 'geo'
console.log(geoPayto.location); // '51.5074,0.1278'

// Plus code example
const plusPayto = new Payto('payto://void/plus');
plusPayto.location = '8FVC9G8V+R9';  // Valid plus code
console.log(plusPayto.void);     // 'plus'
console.log(plusPayto.location); // '8FVC9G8V+R9'

// Bank details example (case-insensitive BIC)
const bankPayto = new Payto('payto://bic/deutdeff500');
console.log(bankPayto.bic);           // 'DEUTDEFF500'
bankPayto.routingNumber = 123456789;  // Valid 9-digit routing number
console.log(bankPayto.routingNumber); // 123456789

// Value handling examples
const numericPayto = new Payto('payto://example/address?amount=10.5');
console.log(numericPayto.value);  // 10.5
console.log(numericPayto.amount); // '10.5'

const tokenPayto = new Payto('payto://example/address?amount=token:10.5');
console.log(tokenPayto.value);    // 10.5
console.log(tokenPayto.amount);   // 'token:10.5'
console.log(tokenPayto.asset);    // 'token'

// Convert to JSON object
const jsonObj = payto.toJSONObject();
console.log(jsonObj.colorForeground); // Access typed properties
console.log(jsonObj['custom-field']); // Access custom properties

API Reference

Constructor

new Payto(paytoString: string)

Creates a new Payto instance from a payto URL string.

Properties

Property	Type	Description
`accountAlias`	`string \\| null`	Email address for UPI/PIX payments (case-insensitive)
`accountNumber`	`number \\| null`	Account number (7-14 digits) for ACH payments
`address`	`string \\| null`	Payment address
`amount`	`string \\| null`	Payment amount with optional currency prefix
`asset`	`string \\| null`	Asset type or contract address
`barcode`	`'qr' \\| 'pdf417' \\| 'aztec' \\| 'code128' \\| null`	Barcode format
`bic`	`string \\| null`	Bank Identifier Code (8 or 11 characters, case-insensitive)
`colorBackground`	`string \\| null`	Background color in 6-character hex format
`colorForeground`	`string \\| null`	Foreground color in 6-character hex format
`currency`	`[string \\| null, string \\| null]`	Currency codes array asset, fiat
`deadline`	`number \\| null`	Payment deadline (Unix timestamp)
`donate`	`boolean \\| null`	Donation flag
`fiat`	`string \\| null`	Fiat currency code (case-insensitive)
`hash`	`string`	URL hash component
`host`	`string`	Complete host (hostname:port)
`hostname`	`string`	Host without port (case-insensitive)
`href`	`string`	Complete URL string
`iban`	`string \\| null`	International Bank Account Number (case-insensitive)
`item`	`string \\| null`	Item description (max 40 chars)
`location`	`string \\| null`	Location data (format depends on void type)
`message`	`string \\| null`	Payment message
`network`	`string`	Network identifier (case-insensitive)
`organization`	`string \\| null`	Organization name (max 25 chars)
`origin`	`string \\| null`	URL origin
`password`	`string`	URL password component
`pathname`	`string`	URL path component
`port`	`string`	URL port component
`protocol`	`string`	URL protocol (always 'payto:')
`receiverName`	`string \\| null`	Receiver's name
`recurring`	`string \\| null`	Recurring payment details
`routingNumber`	`number \\| null`	Bank routing number (9 digits)
`rtl`	`boolean \\| null`	right-to-left layout
`search`	`string`	URL search component
`searchParams`	`URLSearchParams`	URL search parameters
`split`	`[string, string, boolean] \\| null`	Payment split information
`swap`	`string \\| null`	Swap transaction details
`username`	`string`	URL username component
`value`	`number \\| null`	Numeric amount value (extracted from both simple and token:amount formats)
`void`	`string \\| null`	Void path type (e.g., 'geo', 'plus')

Methods

Method	Return Type	Description
`toString()`	`string`	Returns the complete payto URL string
`toJSON()`	`string`	Returns a JSON string representation
`toJSONObject()`	`PaytoJSON`	Returns a typed object with all properties and custom fields