@xocash/json-payment-protocol-v2 v0.0.1-development.9126759194

@xocash/json-payment-protocol-v2

NOTE: This package is EXTREMELY UNSTABLE and WILL BREAK frequently. DO NOT USE YET.

A TypeScript implementation of the JSON Payment Protocol v2, providing a robust interface for handling cryptocurrency payment requests and verification.

Installation

npm install @xocash/json-payment-protocol-v2

Features

• Typed implementation of JSON Payment Protocol v2 (primarily targeting BCH)
• Built-in signature verification
• Configurable trusted keys management
• Comprehensive error handling

Usage

Basic Example

import { JSONPaymentProtocolV2 } from "@xocash/json-payment-protocol-v2";

// Create a new instance
const paymentProtocol = new JSONPaymentProtocolV2();

// Get payment options
const options = await paymentProtocol.paymentOptions(
  "https://merchant.com/pay",
);

// Request payment details
const request = await paymentProtocol.paymentRequest(
  "https://merchant.com/pay",
  {
    chain: "BCH",
    currency: "BCH",
  },
);

// Send payment
const payment = await paymentProtocol.payment("https://merchant.com/pay", {
  chain: "BCH",
  transactions: [
    {
      tx: "rawTransaction",
    },
  ],
});

With Signature Verification

const paymentProtocol = new JSONPaymentProtocolV2({
  verifySignatures: true,
  allowUnknownIdentities: false,
});

API Reference

Constructor Options

interface Options {
  verifySignatures: boolean; // Enable/disable signature verification
  allowUnknownIdentities: boolean; // Allow/reject unknown signing identities
}

Methods

paymentOptions(url: string): Promise<PaymentOptionsResponse>

Fetches available payment options from the merchant.

paymentRequest(url: string, body: PaymentRequestBody): Promise<PaymentRequestResponse>

Requests specific payment details for a chosen cryptocurrency.

paymentVerification(url: string, body: PaymentVerificationBody): Promise<void>

Verifies a payment transaction.

payment(url: string, body: PaymentBody): Promise<PaymentResponse>

Submits payment transaction(s) to the merchant.

Response Types

The library includes TypeScript interfaces for all request and response types. Key interfaces include:

• PaymentOptionsResponse
• PaymentRequestResponse
• PaymentVerificationBody
• PaymentResponse

Security

This library includes built-in signature verification using the BitPay payment protocol trusted keys. You can configure signature verification behavior and trusted keys when instantiating the client.

Default Security Settings

• Signature verification is disabled by default
• Unknown identities are allowed by default
• Includes BitPay's trusted keys

To enhance security, enable signature verification:

const paymentProtocol = new JSONPaymentProtocolV2(
  {
    verifySignatures: true,
    allowUnknownIdentities: false,
  },
  customTrustedKeys,
);

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

License Type - see LICENSE file for details

Acknowledgments

Based on the BitPay Payment Protocol specification.