Skip to content
NETWORK-Z-DevPublic

About

Simple PayPal and Coinbase Payment Handler

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

24 Commits

Folders and files

Repository files navigation

dSyncPay

As another part of the dSync library family this library is responsible for payment handling currently supporting PayPal and Coinbase Crypto payments. It works independently and without any percentage cuts by using your own API keys.

Note

Payment Providers may take a cut from your money or have other fees that are outside of this library's control.


Setup

import dSyncPay from '@hackthedev/dsync-pay';

// const app = express();
const payments = new dSyncPay({
    app,
    domain: 'https://domain.com',
    basePath: '/payments', // optional, default is '/payments'
    redirects: { // optional, customize redirect pages
        success: '/payment-success',
        error: '/payment-error',
        cancelled: '/payment-cancelled',
        subscriptionSuccess: '/subscription-success',
        subscriptionError: '/subscription-error'
    },
    paypal: {
        clientId: 'xxx',
        clientSecret: 'xxx',
        sandbox: true // or false for production
    },
    coinbase: {
        apiKey: 'xxx',        // coinbase commerce API key
        webhookSecret: 'xxx'  // optional, for webhook verification
    },

    // events
    onPaymentCreated: (data) => {},
    onPaymentCompleted: (data) => {},
    onPaymentFailed: (data) => {},
    onPaymentCancelled: (data) => {},
    onSubscriptionCreated: (data) => {},
    onSubscriptionActivated: (data) => {},
    onSubscriptionCancelled: (data) => {},
    onError: (error) => {}
});

Coinbase API Key

dSyncPay uses Coinbase Commerce for crypto payments - not the Coinbase exchange or developer platform. Get your API key at https://commerce.coinbase.com/settings/security.


PayPal Usage

Create an order

const payment = await payments.paypal.createOrder({
    title: 'product name',
    price: 19.99,
    // optional params:
    description: 'product description',   // default: 'no description'
    quantity: 1,                           // default: 1
    currency: 'EUR',                       // default: 'EUR'
    customId: 'your-custom-id',           // default: auto-generated 17-digit id
    metadata: { userId: '123' },          // passed through to onPaymentCompleted
    returnUrl: 'https://custom.com/ok',   // default: https://domain.com/payments/paypal/verify
    cancelUrl: 'https://custom.com/no'    // default: https://domain.com/payments/cancel
});

// redirect user to:
payment.approvalUrl

// result object:
{
    provider: 'paypal',
    type: 'order',
    approvalUrl: '...',
    transactionId: 'customId',
    orderId: '...',
    amount: 19.99,
    currency: 'EUR',
    metadata: {},
    rawResponse: {}
}

Note

metadata is cached in memory for 1 hour and passed through to the payment callbacks automatically.

Verify an order manually

const result = await payments.paypal.verifyOrder(orderId);
// result.status === 'COMPLETED'

Managing subscriptions

// step 1: create a plan (one time setup)
const plan = await payments.paypal.createPlan({
    name: 'monthly premium',
    price: 9.99,
    interval: 'MONTH',       // MONTH, YEAR, WEEK, DAY
    // optional:
    description: '...',
    currency: 'EUR',         // default: 'EUR'
    frequency: 1             // default: 1
});
// save plan.planId for later use

// step 2: create a subscription
const sub = await payments.paypal.createSubscription({
    planId: 'P-xxxxx',
    // optional:
    customId: 'your-custom-id',
    metadata: { userId: '123' },
    returnUrl: 'https://custom.com/success',  // default: https://domain.com/payments/paypal/subscription/verify
    cancelUrl: 'https://custom.com/cancel'    // default: https://domain.com/payments/cancel
});

// redirect user to:
sub.approvalUrl
// also available: sub.subscriptionId

// step 3: verify subscription manually
const result = await payments.paypal.verifySubscription(subscriptionId);
// result.status === 'ACTIVE'

// cancel a subscription
await payments.paypal.cancelSubscription(subscriptionId, 'reason');

Coinbase Usage

Creating a charge

const charge = await payments.coinbase.createCharge({
    title: 'product name',
    price: 19.99,
    // optional:
    description: 'product description',   // default: 'no description'
    quantity: 1,                           // default: 1
    currency: 'EUR',                       // default: 'EUR'
    metadata: { userId: '123' },
    redirectUrl: 'https://custom.com/ok', // default: https://domain.com/payments/coinbase/verify
    cancelUrl: 'https://custom.com/no'    // default: https://domain.com/payments/cancel
});

// redirect user to:
charge.hostedUrl

// result object:
{
    provider: 'coinbase',
    type: 'charge',
    hostedUrl: '...',
    chargeId: '...',
    chargeCode: '...',
    amount: 19.99,
    currency: 'EUR',
    metadata: {},
    rawResponse: {}
}

Verify a charge manually

const result = await payments.coinbase.verifyCharge(chargeCode);
// result.status === 'COMPLETED'

Routes

dSyncPay automatically registers verification routes that handle payment returns from PayPal and Coinbase.

Verification Routes

PayPal

  • GET /payments/paypal/verify?token=xxx
  • GET /payments/paypal/subscription/verify?subscription_id=xxx
  • GET /payments/cancel

Coinbase

  • GET /payments/coinbase/verify?code=xxx
  • POST /payments/webhook/coinbase (only registered if webhookSecret is set)
  • GET /payments/cancel

Status Page

After a payment is completed, failed, or cancelled, the user is redirected to a built-in status page at:

GET /payments/payment-status.html?status=success&provider=paypal&amount=19.99&currency=EUR

The status query param controls what is shown:

status description
success payment or subscription completed
error payment failed
cancelled user cancelled

Additional query params (payment_id, provider, amount, currency, type) are passed through automatically and displayed on the page.

You can customize where users land before the status page using the redirects option in the constructor. These are intermediate routes that pass through query params and redirect to the status page.


Custom Configuration

const payments = new dSyncPay({
    app,
    domain: 'https://domain.com',
    basePath: '/api/pay',   // default: '/payments'
    redirects: {
        success: '/custom/success',
        error: '/custom/error',
        cancelled: '/custom/cancelled',
        subscriptionSuccess: '/custom/sub-success',
        subscriptionError: '/custom/sub-error'
    },
    paypal: { ... }
});

// verification routes: /api/pay/paypal/verify, /api/pay/coinbase/verify, etc.
// auto-generated return urls: https://domain.com/api/pay/paypal/verify
// status page: /api/pay/payment-status.html

Events

All callbacks receive a data object with at minimum provider, type, status, metadata, and rawResponse.

event trigger
onPaymentCreated order or charge was created
onPaymentCompleted payment verified as completed
onPaymentFailed payment failed or expired
onPaymentCancelled user cancelled payment
onSubscriptionCreated subscription was created
onSubscriptionActivated subscription verified as active
onSubscriptionCancelled subscription was cancelled
onError internal error (auth, api call, etc.)

About

Simple PayPal and Coinbase Payment Handler

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages