skuidma/ycp-sdk-ts

Unofficial YouCan Pay NodeJS SDK built using TypeScript

YouCan Pay SDK for NodeJS

Unofficial SDK to use the YouCan Pay service

Installation

# Using npm
npm i ycp-sdk-ts
# Using yarn
yarn add ycp-sdk-ts

Usage

Creating a payment token

To ask a customer for a payment, you first need to generate a Payment token. You can achieve that by calling the tokenizePayment method.

Example code:

import { YcpFactory } from 'ycp-sdk-ts';

// Create a Youcanpay instance using the factory
const ycp = YcpFactory.ycp({
  // Your API's private key, you can get it from Dashboard > Settings > API Keys
  privateKey: '',
  // True to enable Sandbox mode
  isSandboxMode: true,
});

const token = await ycp.tokenizePayment({
  order_id: '',
  amount: 1337,
  currency: 'MAD',
  customer_ip: '13.37.4.2',
  // URL where to redirect to when payment is successful
  success_url: '',
  // URL where to redirect to when payment is not successful
  error_url: '',
  // Information about the customer
  customer: {
    name: 'Hmida Bar9al',
    address: 'Hay takadom',
    zip_code: '21',
    city: 'Fes',
    state: 'Chaouia-ourdigha',
    country_code: 'MA',
    phone: '06',
    email: 'hmida.bar9al@gmail.com',
  },
  // Metadata that will be returned via the webhook
  metadata: {
    anything: 'some value',
  },
});

console.log(token)

The result will be:

{
  "tokenId": "payment-token-to-be-used",
  "paymentUrl": "https://youcanpay.com/payment-form/token-id"
}

You can use tokenId to display the payment form or use the paymentUrl to take the user directly to the payment page.

Webhook signature validation

When receiving a webhook, a very necessary step (unfortunately, it is not mentioned in the official documentation) is to validate the webhook's signature to ensure that it is coming from YouCan Pay and not a bad actor.

The signature is sent in a header along with the request, the header's name is X-Youcanpay-Signature

Example code:

import { YcpFactory } from 'ycp-sdk-ts';

// Create a Youcanpay instance using the factory
const ycp = YcpFactory.ycp({
  // Your API's private key, you can get it from Dashboard > Settings > API Keys
  privateKey: '',
  // True to enable Sandbox mode
  isSandboxMode: true,
});

// The signature in the X-Youcanpay-Signature header
const expectedSignature = '';

// The webhook's request body, accepts both a parsed or a string JSON
const body = '';

const isValid = ycp.validateWebhookSignature(body, expectedSignature);

console.log(isValid);

The result will be either true or false