johnny-tools-node v1.0.9

checkout-node-sdk

Import

import import { Checkout } from "johnny-tools-node";

Initialise

Picks up your environment variables set as CKO_SECRET_KEY and CKO_PUBLIC_KEY

const cko = new Checkout();

With your secret key.

const cko = new Checkout('sk_XXXX');

With your secret key and custom config

const cko = new Checkout('sk_XXXX', { timeout: 7000 });

Environment

Unless you specify the host, the SDK will determine the environemnt based on your secret key

const cko = new Checkout('sk_XXXX', { host: 'test.com' }); // custom host
const cko = new Checkout('sk_XXXX'); // Live Environemnt
const cko = new Checkout('sk_test_XXXX'); // Sandbox Environemnt

In case you use the token endpoint you can set you publick key like this:

const cko = new Checkout('sk_XXXX', { pk: 'pk_XXX' });
// or cko.config.pk = "pk_XXX"

Payments

The SDK will infer the type of the payment source or destination, if not provided, for: token, id, card, customer, network_token

The request body is dynamic so if you want to see the paramenters check the docs

Request a payment or a payout

Source Type: token

const payment = await cko.payments.request({
    source: {
        token: 'tok_bzi43qc6jeee5mmnfo4gnsnera'
    },
    currency: 'USD',
    amount: 1000 // cents
});

Source Type: card

const payment = await cko.payments.request({
    source: {
        number: '4242424242424242',
        expiry_month: 6,
        expiry_year: 2029,
        cvv: '100'
    },
    currency: 'USD',
    amount: 1000 // cents
});

Source Type: id

const payment = await cko.payments.request({
    source: {
        id: 'src_vg3tm54ndfbefotjlmgrrvbxli'
    },
    currency: 'USD',
    amount: 1000 // cents
});

Source Type: customer

const payment = await cko.payments.request({
    source: {
        id: 'cus_6artgoevd77u7ojah2wled32sa'
    },
    currency: 'USD',
    amount: 1000 // cents
});

Source Type: Alternative Payment Method (APM)

const payment = await cko.payments.request({
    source: {
        type: 'sofort'
    },
    currency: 'EUR',
    amount: 1000 // cents
});

Destination Type: id

const payment = await cko.payments.request({
    destination: {
        id: 'src_vg3tm54ndfbefotjlmgrrvbxli'
    },
    currency: 'USD',
    amount: 1000 // cents
});

Get payment details

With: payment id

const payment = await cko.payments.get('pay_je5hbbb4u3oe7k4u3lbwlu3zkq');

With: session id

const payment = await cko.payments.get('sid_pm6woylsb23efp37npxgmml4ti');

Get payment actions

With: payment id

const payment = await cko.payments.getActions('pay_je5hbbb4u3oe7k4u3lbwlu3zkq');

Payment flow

Perform: Capture Void Refund

const capture = await cko.payments.capture('pay_je5hbbb4u3oe7k4u3lbwlu3zkq', {
    reference: 'capture'
});
const void = await cko.payments.void('pay_je5hbbb4u3oe7k4u3lbwlu3zkq', {
    reference: 'void'
});
const refund = await cko.payments.refund('pay_je5hbbb4u3oe7k4u3lbwlu3zkq', {
    reference: 'refund'
});

3DS Support

Payment Request Example

const payment = await cko.payments.request({
    source: {
        number: '4242424242424242',
        expiry_month: 6,
        expiry_year: 2029,
        cvv: '100'
    },
    '3ds': {
        enabled: true
    },
    currency: 'USD',
    amount: 1000 // cents
});

if (payment.requiresRedirect) {
    let redirectionUrl = payment.redirectLink;
    // redirect to the redirectionUrl
}

Tokens

The SDK will infer the type of the payload, if not provided

The request body is dynamic so if you want to see the paramenters check the docs

Request a token

Token Type: applepay

const token = await cko.tokens.request({
    token_data: {
        version: 'EC_v1',
        data: 'XXX',
        signature: 'XXX',
        header: {
            ephemeralPublicKey: 'XXX',
            publicKeyHash: 'XXX',
            transactionId: 'XXX'
        }
    }
});

Token Type: googlepay

const token = await cko.tokens.request({
    token_data: {
        protocolVersion: 'EC_v1',
        signature: 'XXX',
        signedMessage: 'XXX'
    }
});

Token Type: card

const token = await cko.tokens.request({
    number: '4242424242424242',
    expiry_month: '6',
    expiry_year: '2028',
    cvv: '100'
});

Sources

The SDK will infer the type of the source, if not provided

The request body is dynamic so if you want to see the paramenters check the docs

Request a source

Token Type: sepa

const token = await cko.sources.add({
    source: {
        token: 'tok_bzi43qc6jeee5mmnfo4gnsnera' // Generated by Checkout.Frames
        billing_address: {
            address_line1: 'Wall Street',
            address_line2: 'Dollar Avenue',
            city: 'London',
            state: 'London',
            zip: 'W1W W1W',
            country: 'GB'
        },
        phone: {
            country_code: '44',
            number: '7123456789'
        }
    },
    currency: 'USD',
    amount: 1000,
    payment_type: 'Regular',
    reference: 'ORDER 1234',
    description: 'Mint Tea',
    customer: {
        email: 'new_user@email.com',
        name: 'John Smith'
    },
    metadata: {
        myCustomProp: {
            value: 1
        }
    }
});

Token Type: ach

const token = await cko.sources.add({
    billing_address: {
        address_line1: 'Wayne Plaza 1',
        address_line2: null,
        city: 'Gotham City',
        state: null,
        zip: '12345',
        country: 'US'
    },
    source_data: {
        account_holder_name: 'Bruce Wayne',
        account_type: 'Checking',
        account_number: '0123456789',
        routing_number: '211370545',
        billing_descriptor: 'ACH Demo',
        company_name: null
    }
});

Exception handling

Example

try {
  const payment = await cko.payments.request({
  source: {
    id: "src_vg3tm54ndfbefotjlmgrrvbxli"
  },
  currency: "USD",
  amount: 1000 // cents
  });
} catch (e) {
    switch (err.name) {
        case "ApiTimeout": ...
          break;
        case "AuthenticationError": ...
          break;
        case "ActionNotAllowed": ...
          break;
        case "UrlAlreadyRegistered": ...
          break;
        case "NotFoundError": ...
          break;
        case "UnprocessableError": ...
          break;
        case "ErrorWithBody": ...
          break;
        case "ValidationError": ...
          break;
        case "TooManyRequestsError": ...
          break;
        case "BadGateway": ...
          break;
        case "ValueError": ...
          break;
        default:
          break;
      }
}

Utility

requiresRedirect

const payment = await cko.payments.request(...);

console.log(payment.requiresRedirect)

Boolean value. For the "true" value, this means that the transaction was Flagged by a risk rule and it requires manual review.