@profullstack/coinpay 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to `@profullstack/coinpay` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.23.0] - 2026-10-21
+
+### Added
+- `createPayment({ successUrl, cancelUrl })`, like Stripe Checkout: once the payment confirms, the
+  hosted pay page sends the customer to `successUrl` (`{PAYMENT_ID}` is replaced with the payment id);
+  `cancelUrl` is the "Back to merchant" link from an expired checkout. Before this the crypto checkout
+  had no way to return the buyer and left them on "Payment Complete!".
+
 ## [0.22.0] - 2026-10-19
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "CoinPay SDK & CLI \u2014 Accept cryptocurrency and card payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet, swap and a live finances dashboard",
   "type": "module",
   "main": "./src/index.js",

package/src/client.d.ts

@@ -27,6 +27,10 @@ export interface PaymentParams {
   description?: string;
   /** Custom metadata attached to the payment (e.g., `{ orderId: 'ORD-123' }`) */
   metadata?: Record<string, unknown>;
+  /** Where the pay page sends the customer once the payment confirms, like Stripe's `success_url`. `{PAYMENT_ID}` is replaced with the payment id. */
+  successUrl?: string;
+  /** Where "Back to merchant" goes from an expired or abandoned checkout */
+  cancelUrl?: string;
 }
 
 /** Parameters for listing payments */

package/src/client.js

@@ -228,6 +228,8 @@ export class CoinPayClient {
    * @param {string} params.blockchain - Blockchain/cryptocurrency (BTC, ETH, SOL, POL, BCH, USDC_ETH, USDC_POL, USDC_SOL)
    * @param {string} [params.description] - Payment description (shown to customer)
    * @param {Object} [params.metadata] - Custom metadata (e.g., { orderId: 'ORD-123', customerId: 'CUST-456' })
+   * @param {string} [params.successUrl] - Where the pay page sends the customer once the payment confirms, like Stripe's success_url. {PAYMENT_ID} is replaced with the payment id.
+   * @param {string} [params.cancelUrl] - Where "Back to merchant" goes from an expired or abandoned checkout
    * @returns {Promise<Object>} Created payment with address and QR code
    *
    * @example
@@ -238,7 +240,8 @@ export class CoinPayClient {
    *   currency: 'USD',
    *   blockchain: 'BTC',
    *   description: 'Order #12345',
-   *   metadata: { orderId: '12345', customerEmail: 'customer@example.com' }
+   *   metadata: { orderId: '12345', customerEmail: 'customer@example.com' },
+   *   successUrl: 'https://yoursite.com/orders/12345?payment={PAYMENT_ID}',
    * });
    *
    * // Display payment.payment_address and payment.qr_code to customer
@@ -250,6 +253,8 @@ export class CoinPayClient {
     blockchain,
     description,
     metadata,
+    successUrl,
+    cancelUrl,
   }) {
     // Map to API field names (snake_case)
     return this.request('/payments/create', {
@@ -261,6 +266,8 @@ export class CoinPayClient {
         blockchain: blockchain?.toUpperCase(),
         description,
         metadata,
+        success_url: successUrl,
+        cancel_url: cancelUrl,
       }),
     });
   }

package/src/payments.d.ts

@@ -25,6 +25,10 @@ export interface CreatePaymentParams {
   description?: string;
   /** Custom metadata for your records */
   metadata?: Record<string, unknown>;
+  /** Where the pay page sends the customer once the payment confirms, like Stripe's `success_url`. `{PAYMENT_ID}` is replaced with the payment id. */
+  successUrl?: string;
+  /** Where "Back to merchant" goes from an expired or abandoned checkout */
+  cancelUrl?: string;
 }
 
 /** Parameters for the standalone `getPayment` function */

package/src/payments.js

@@ -34,6 +34,8 @@ import { CoinPayClient } from './client.js';
  * @param {string} params.blockchain - Blockchain to use (BTC, ETH, SOL, POL, BCH, USDC_ETH, USDC_POL, USDC_SOL)
  * @param {string} [params.description] - Payment description shown to customer
  * @param {Object} [params.metadata] - Custom metadata for your records
+ * @param {string} [params.successUrl] - Where the pay page sends the customer after the payment confirms ({PAYMENT_ID} is filled in)
+ * @param {string} [params.cancelUrl] - Where "Back to merchant" goes from an expired checkout
  * @returns {Promise<Object>} Created payment with address and QR code
  *
  * @example
@@ -60,6 +62,8 @@ export async function createPayment({
   blockchain,
   description,
   metadata,
+  successUrl,
+  cancelUrl,
 }) {
   const coinpay = client || new CoinPayClient({ apiKey });
   
@@ -70,6 +74,8 @@ export async function createPayment({
     blockchain,
     description,
     metadata,
+    successUrl,
+    cancelUrl,
   });
 }