Nox SDK

An SDK made with typescript to interact with the Checkout API and V2 API in a simple and efficient way.

Installing

npm install nox-ts-sdk

Checkout API

Setup

To use the SDK, you will need an API token generated by the Nox system.

import { CheckoutAPI } from 'nox-ts-sdk';

const token = 'your_api_token';

// Optional
const url = null;

const checkoutApi = new CheckoutApi(token, url);

Using Checkout API methods

Listing Checkouts

Gets a list of checkouts based on the given query parameters.

getCheckouts(queryParams?: Record<string, any>): Promise<GetCheckoutsResponse>

Usage Example:

const response = await checkoutApi.getCheckouts({
    page: 1,
    created_at_start: '2024-04-08'
    created_at_end: '2024-05-08'
});
console.log(response.checkouts);

Response:

{
    "checkouts": [
        {
            "id": 1,
            "image": "base64image",
            "image_type": "image/png",
            "description": "Teste",
            "price": "50.00",
            "redirect_url": "https://example.com",
            "is_enabled": true,
            "theme_color": "custom",
            "payment_method": "all",
            "colors": {
                "primary": "#F2F2F2",
                "secondary": "#FFFFFF",
                "text": "#334155",
                "button": "#3F438C",
                "textButton": "#FFFFFF"
            },
            "created_at": "2024-06-13T18:41:20.329Z",
            "url_id": "f25f51c9-0a90-41c9-9571-035813ae0000"
        }
    ],
    "current_page": 1,
    "total_pages": 1,
}

Retrieving Checkout

Retrieves a checkout using its url_id identifier.

getCheckout(id: string): Promise<CheckoutDetail>

Usage Example:

const checkout = await checkoutApi.getCheckout('123');
console.log(checkout);

Response:

{
    "image": "base64image",
    "description": "Produto teste",
    "price": "10.00",
    "redirect_url": "https://example.com",
    "is_enabled": true,
    "payment_method": "all",
    "url_id": "0989d6cc-b02c-493b-b953-dab39dbc1111",
    "colors": {
        "primary": "#F2F2F2",
        "secondary": "#FFFFFF",
        "text": "#334155",
        "button": "#3F438C",
        "textButton": "#FFFFFF"
    },
    "code": "string",
    "txid": "string"
}

Creating Checkout

Create a new checkout with the provided data. createCheckout(data: CreateCheckoutData, file?: File): Promise<CreateCheckoutResponse>

Usage Example:

const data = {
    colors: {
        primary: '#000000',
        secondary: '#FFFFFF',
        text: '#333333',
        button: '#FF0000',
        textButton: '#FFFFFF',
    },
    price: 1000,
    description: 'Produto teste',
    redirect_url: 'https://example.com',
    payment_method: 'credit_card',
    is_enabled: true,
    theme_color: '#FF00FF',
};

const response = await checkoutApi.createCheckout(data, file);
console.log(response);

Response:

{
    "id": 1,
    "url_id": "87ff1499-dab3-44e6-9538-3cbb05b66666"
}

Updating Checkout

Updates data from an existing checkout.

updateCheckout(id: number, data: UpdateCheckoutData, file?: File): Promise<UpdateCheckoutResponse>

Usage Example:

const updateData = {
    price: 1200,
    change_image: false,
};

const response = await checkoutApi.updateCheckout(123, updateData, newFile);
console.log(response.detail);

Response:

{
    "detail": "Checkout updated successfully."
}

Error Handling

In case of errors, the methods will throw an exception with a detailed message

try {
    const checkout = await checkoutApi.getCheckout('123');
} catch (error) {
    console.error(error.message);
}

V2 API

Setup

To use the SDK, you will need an API token and a merchant resgistration. To achieve them, you must get in contact with Nox, so we can provide them to you.

import { V2API } from 'nox-ts-sdk';

const token = 'your_api_token';

const v2Api = new V2API(token);

Using V2 API methods

Get Account.

Retrieves the account information associated with the API token. getAccount()

Usage Example:

const account = await v2Api.getAccount();
console.log(account);

Response:

{
    "name": "John Doe",
    "balance": 1500.50
}

Create Payment Method

Creates a new payment using the specified method and details. createPayment(data: CreatePaymentData)

Usage Example:

const paymentResponse = await v2Api.createPayment({
    method: 'PIX',
    code: '123456',
    amount: 1000,
});
console.log(paymentResponse);

Response:

{
    "method": "PIX",
    "code": "123456",
    "amount": 1000,
    "qrcode": "https://api.example.com/qrcode",
    "qrcodebase64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "copypaste": "1234567890",
    "txid": "abc123",
    "Status": "WAITING_PAYMENT"
}

Create Cash-out Payment

Creates a new cash-out payment. createPaymentCashOut(data: CreatePaymentData)

Usage Example:

const paymentResponse = await v2Api.createPaymentCashOut({
    method: 'PIX',
    code: '123456',
    amount: 1000,
    type: 'PIX_KEY',
    pixkey: 'your-pix-key',
});
console.log(paymentResponse);

Response:

{
    "Method": "PIXOUT",
    "Status": "SENT",
    "Code": "123456",
    "TxID": "abc123",
    "Amount": 1000,
}

Retrieve Payment's Info

Fetches the details of a specific payment by its code or tx_id. getPayment(identifier: string)

Usage Example:

const payment = await v2Api.getPayment('payment-identifier');
console.log(payment);

Response:

{
    "Method": "PIX",
    "Status": "PAID",
    "Code": "123456",
    "TxID": "abc123",
    "Amount": 1000,
    "end2end": "e2e123",
    "receipt": "https://api.example.com/receipt"
}

Resend Webhook

Resends the webhook for a specific transaction. resendWebhook(txid: string)

Usage Example:

await v2Api.resendWebhook('txid');

Send Transactions Report

Generates and sends a transaction report based on the specified filters to merchant email associated with the token in csv format. sendTransactionsReport(filters: TransactionsRequestFilters)

Usage Example:

await v2Api.sendTransactionsReport({
    beginDate: '2024-01-01',
    endDate: '2024-01-31',
    method: 'PIX',
    status: 'PAID',
});

Create Credit Card Payment

Creates a new payment using a credit card. createCreditCardPayment(data: CreateCreditCardPaymentData)

Usage Example:

const creditCardPaymentResponse = await v2Api.createCreditCardPayment({
    amount: 1000,
    email: '[email protected]',
    code: '123456',
    name: 'User Name',
    cpf_cnpf: '12345678900',
    expired_url: 'https://example.com/expired',
    return_url: 'https://example.com/return',
    max_installments_value: 200,
    soft_descriptor_light: 'COMPANY NAME',
});
console.log(creditCardPaymentResponse);

Response:

{
    "id": "cc123",
    "due_date": "2024-12-31",
    "currency": "BRL",
    "email": "[email protected]",
    "status": "pending",
    "total_cents": 1000,
    "order_id": "order123",
    "secure_id": "secure123",
    "secure_url": "https://api.example.com/secure",
    "total": "10.00",
    "created_at_iso": "2024-09-01T12:34:56Z"
}

Retrieve Credit Card Payment

Retrieves details of a specific credit card payment by its identifier. getCreditCardPayment(identifier: string)

Usage Example:

const creditCardPayment = await v2Api.getCreditCardPayment('credit-card-payment-identifier');
console.log(creditCardPayment);

Response:

{
    "id": 123,
    "status": "PAID",
    "code": "cc123",
    "txid": "tx123",
    "amount": 1000,
    "created_at": "2024-09-01T12:34:56Z",
    "paid_at": "2024-09-01T13:00:00Z",
    "canceled_at": null,
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "customer_document": "123.456.789-00",
    "merchant_id": 456,
    "id_from_bank": "bank123"
}

Error Handling

In case of errors, the methods will throw an exception with a detailed message

try {
    const checkout = await v2Api.getCreditCardPayment('credit-card-payment-identifier');
} catch (error) {
    console.error(error.message);
}