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 or positive integer) | | 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 |

Type Safety

The library includes TypeScript type definitions and runtime validation for:

• Bank Identifier Codes (BIC) - 8 or 11 characters, case-insensitive
• Routing numbers (9 digits)
• Account numbers (7-14 digits)
• Email addresses (for UPI/PIX, case-insensitive)
• Geographic coordinates
• Plus codes
• Unix timestamps
• Barcode formats
• IBAN format (case-insensitive)
• Color formats (6-character hex)

Payment System Support

IBAN

Supports two formats (case-insensitive):

• payto://iban/iban (without BIC)
• payto://iban/bic/iban (with BIC)

ACH Payments

Supports two formats:

• payto://ach/routing/account (with routing number)
• payto://ach/account (account number only)

UPI/PIX Payments

Email-based payment identifiers (case-insensitive):

• payto://upi/email@example.com
• payto://pix/email@example.com

License

This project is licensed under the CORE License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Acknowledgments

• Based on the URL Web API
• Implements RFC 8905 - The 'payto' URI Scheme

Funding

If you find this project useful, please consider supporting it:

• GitHub Sponsors
• Core
• Bitcoin
• Litecoin

List of sponsors: