@ahdeyy/paystack

v1.0.0

Published

25 days ago

an api wrapper for paystack's api with types

0High
0Medium
0Low

ahdeyy

paystack api api wrapper wrapper online payment

paystack-api

A wrapper for the Paystack API with types.

Installation

NPM

    npm install @ahdeyy/paystack

PNPM

    pnpm add @ahdeyy/paystack

YARN

    yarn add @ahdeyy/paystack

BUN

    bun add @ahdeyy/paystack

Usage

Patterns

After using an API, check if the status of the call is true to work with the success response

import { Paystack } from "@ahdeyy/paystack"

// create the paystack object

const paystack = new Paystack(secret_key)

const created_request = await paystack.payment_request.create({
  amount: 10000,
  description: "Payment for goods",
  due_date: "2022-12-31",
  customer: "customer id",
})

// Check the status of the response
if (created_request.status) {
  // Work with the response success data
} else {
  // Work with the response error data
}

Payment request

Create payment request

const paystack = new Paystack(secret_key)

const created_request = await paystack.payment_request.create({
  amount: 10000,
  description: "Payment for goods",
  due_date: "2022-12-31",
  customer: "customer id",
})

Update payment request

const updated_request = await paystack.payment_request.update({
  amount: 10000,
  description: "Payment for goods",
  due_date: "2022-12-31",
  customer: "customer id",
})

Fetch payment request

const fetched_request = await paystack.payment_request.fetch("request id")

List payment requests

const list = await paystack.payment_request.list(query)

Verify payment request

const verified_request = await paystack.payment_request.verify("request id")

Send Notification

const sent_notification = await paystack.payment_request.sendNotification(
  "request id"
)

Payment request total

const total = await paystack.payment_request.total()

Finalize payment request

const finalized_request = await paystack.payment_request.finalize("request id")

Archive payment request

const archived_request = await paystack.payment_request.archive("request id")

Customer

Create customer

const customer = await paystack.customer.create({
  email: "[email protected]",
  first_name: "john",
  last_name: "doe",
})

List customers

const customer = await paystack.customer.list({ perPage: 10, page: 1 })

Fetch customer

const customer = await paystack.customer.fetch(customers_email)

Validate customer

const customer = await paystack.customer.validate(customer_code, {
  country,
  type,
  account_number,
  bvn,
  bank_code,
  first_name,
  last_name,
})

Update customer

const customer = await paystack.customer.update(customer_code, { phone })

Whitelist/Blacklist customer

const customer = await paystack.customer.whitelist_blacklist({
  customer: customer_code,
  risk_action: "deny",
})

Deactivate Authorization

const customer = await paystack.customer.deactivate_authorization(
  Authorization_code
)

Product

Create product

const product = await paystack.product.create({
  name: "sakura",
  description: "cherry blossom",
  price: 10000,
  currency: "NGN",
})

List products

const product = await paystack.product.list({ perPage: 10, page: 1 })

Fetch product

const product = await paystack.product.fetch(product_id)

Update product

const product = await paystack.product.update(product_id, { price: 69420 })

Dedicated Virtual Accounts

Create DVA

    const response = await paystack.dva.create({ customer: import.meta.env.CUSTOMER_CODE ?? '' })

Assign DVA

    const response = await paystack.dva.assign({
        email: "[email protected]",
        first_name: "Jane",
        middle_name: "Karen",
        last_name: "Doe",
        phone: "+2348100000000",
        preferred_bank: "test-bank",
        country: "NG"

    })

List DVA

    const response = await paystack.dva.list({ active: true, currency: "NGN" });

Fetch DVA

    const response = await paystack.dva.fetch("foo")

Requery DVA

    const response = await paystack.dva.requery({ account_number: "98897", provider_slug: "wema-bank" });

Deactivate DVA

    const response = await paystack.dva.deactivate("foo")

Split DVA

    const response = await paystack.dva.split({ customer: "janey" })

Remove split DVA

    const response = await paystack.dva.remove_split("bar")

Fetch bank providers

    const response = await paystack.dva.fetch_bank_providers();

Miscellanous

List banks

    const response = await paystack.miscellaneous.list_banks({ country: "nigeria", use_cursor: true, perPage: 40 })

List countries

    const response = await paystack.miscellaneous.list_countries()

List states

    const response = await paystack.miscellaneous.list_states("US")

Transactions

Initialize transaction

    const response = await paystack.transaction.initialize({
        amount: 10000,
        email: "[email protected]",
    })

Verify transaction

    const response = await paystack.transaction.verify("transaction reference")

List transactions

    const response = await paystack.transaction.list({ perPage: 10, page: 1 })

Fetch transaction

    const response = await paystack.transaction.fetch(123456789)

Charge authorization

    const response = await paystack.transaction.charge_authorization({
        amount: 10000,
        email: "[email protected]",
        authorization_code: "AUTH_72btv547",
    })

View transaction timeline

    const response = await paystack.transaction.timeline("transaction id or reference")

Transaction totals

    const response = await paystack.transaction.totals()

Export transactions

    const response = await paystack.transaction.export({ perPage: 10 })

Partial debit

    const response = await paystack.transaction.partial_debit({
        authorization_code: "AUTH_72btv547",
        currency: "NGN",
        amount: 10000,
        email: "[email protected]",
    })

Transaction Splits

Create split

    const response = await paystack.split.create({
        name: "Band split",
        type: "percentage",
        currency: "NGN",
        subaccounts: [
            { subaccount: "ACCT_z3x6z3nbo14xsil", share: 50 },
            { subaccount: "ACCT_pwwualwty4nhq9d", share: 50 },
        ],
        bearer_type: "subaccount",
        bearer_subaccount: "ACCT_z3x6z3nbo14xsil",
    })

List splits

    const response = await paystack.split.list({ perPage: 10, page: 1 })

Fetch split

    const response = await paystack.split.fetch("split id")

Update split

    const response = await paystack.split.update("split id", { name: "New name", active: true })

Add/update subaccount in split

    const response = await paystack.split.add_subaccount("split id", {
        subaccount: "ACCT_hdl8abxl8drhrl3",
        share: 30,
    })

Remove subaccount from split

    const response = await paystack.split.remove_subaccount("split id", {
        subaccount: "ACCT_hdl8abxl8drhrl3",
    })

Terminal

Send event

    const response = await paystack.terminal.send_event("terminal id", {
        type: "transaction",
        action: "process",
        data: { id: "transaction id" },
    })

Fetch event status

    const response = await paystack.terminal.fetch_event_status("terminal id", "event id")

Fetch terminal status

    const response = await paystack.terminal.fetch_terminal_status("terminal id")

List terminals

    const response = await paystack.terminal.list({ perPage: 10 })

Fetch terminal

    const response = await paystack.terminal.fetch("terminal id")

Update terminal

    const response = await paystack.terminal.update("terminal id", { name: "New name", address: "New address" })

Commission terminal

    const response = await paystack.terminal.commission({ serial_number: "serial number" })

Decommission terminal

    const response = await paystack.terminal.decommission({ serial_number: "serial number" })

Virtual Terminal

Create virtual terminal

    const response = await paystack.virtual_terminal.create({
        name: "Checkout Terminal",
        destinations: [{ target: "+2348100000000", name: "Sales" }],
    })

List virtual terminals

    const response = await paystack.virtual_terminal.list({ perPage: 10, status: "active" })

Fetch virtual terminal

    const response = await paystack.virtual_terminal.fetch("virtual terminal code")

Update virtual terminal

    const response = await paystack.virtual_terminal.update("virtual terminal code", { name: "New name" })

Deactivate virtual terminal

    const response = await paystack.virtual_terminal.deactivate("virtual terminal code")

Assign destination

    const response = await paystack.virtual_terminal.assign_destination("virtual terminal code", {
        destinations: [{ target: "+2348100000000", name: "Sales", type: "whatsapp" }],
    })

Unassign destination

    const response = await paystack.virtual_terminal.unassign_destination("virtual terminal code", {
        targets: ["+2348100000000"],
    })

Add split code

    const response = await paystack.virtual_terminal.add_split_code("virtual terminal code", { split_code: "SPL_uVbQELZ80V" })

Remove split code

    const response = await paystack.virtual_terminal.remove_split_code("virtual terminal code", { split_code: "SPL_uVbQELZ80V" })

Direct Debit

Trigger activation charge

    const response = await paystack.direct_debit.trigger_activation_charge({ customer_ids: [123456] })

Fetch mandate authorizations

    const response = await paystack.direct_debit.fetch_mandate_authorizations({ status: "active", per_page: 10 })

Preauthorization

Initialize preauthorization

    const response = await paystack.preauthorization.initialize({
        email: "[email protected]",
        amount: 10000,
    })

Capture preauthorization

    const response = await paystack.preauthorization.capture({
        reference: "transaction reference",
        amount: 10000,
        currency: "NGN",
    })

Release preauthorization

    const response = await paystack.preauthorization.release({ reference: "transaction reference" })

Reauthorize preauthorization

    const response = await paystack.preauthorization.reauthorize({
        email: "[email protected]",
        amount: 10000,
        authorization_code: "AUTH_72btv547",
    })

Apple Pay

Register domain

    const response = await paystack.apple_pay.register_domain({ domainName: "example.com" })

List domains

    const response = await paystack.apple_pay.list_domains({ use_cursor: true })

Unregister domain

    const response = await paystack.apple_pay.unregister_domain({ domainName: "example.com" })

Capitec Pay

Charge with Capitec Pay

    const response = await paystack.capitec_pay.charge({
        email: "[email protected]",
        amount: 10000,
        currency: "ZAR",
        capitec_pay: {
            identifier: { type: "CELLPHONE", value: "0712345678" },
        },
    })

Check charge status

    const response = await paystack.capitec_pay.check_status("transaction reference")

Subaccounts

Create subaccount

    const response = await paystack.subaccount.create({
        business_name: "Sunshine Studios",
        settlement_bank: "058",
        account_number: "0000000000",
        percentage_charge: 18.2,
    })

List subaccounts

    const response = await paystack.subaccount.list({ perPage: 10, page: 1 })

Fetch subaccount

    const response = await paystack.subaccount.fetch("subaccount id or code")

Update subaccount

    const response = await paystack.subaccount.update("subaccount id or code", { description: "New description" })

Plans

Create plan

    const response = await paystack.plan.create({
        name: "Monthly retainer",
        amount: 500000,
        interval: "monthly",
    })

List plans

    const response = await paystack.plan.list({ perPage: 10, page: 1 })

Fetch plan

    const response = await paystack.plan.fetch("plan id or code")

Update plan

    const response = await paystack.plan.update("plan id or code", { name: "New name" })

Subscriptions

Create subscription

    const response = await paystack.subscription.create({
        customer: "customer code or email",
        plan: "PLN_xxxxxxxx",
    })

List subscriptions

    const response = await paystack.subscription.list({ perPage: 10, page: 1 })

Fetch subscription

    const response = await paystack.subscription.fetch("subscription id or code")

Enable subscription

    const response = await paystack.subscription.enable({ code: "SUB_xxxxxxxx", token: "email token" })

Disable subscription

    const response = await paystack.subscription.disable({ code: "SUB_xxxxxxxx", token: "email token" })

Generate update subscription link

    const response = await paystack.subscription.generate_update_link("SUB_xxxxxxxx")

Send update subscription link

    const response = await paystack.subscription.send_update_link("SUB_xxxxxxxx")

Storefronts

Create storefront

    const response = await paystack.storefront.create({
        name: "My Shop",
        slug: "my-shop",
        currency: "NGN",
    })

List storefronts

    const response = await paystack.storefront.list({ perPage: 10, page: 1 })

Fetch storefront

    const response = await paystack.storefront.fetch("storefront id or slug")

Update storefront

    const response = await paystack.storefront.update("storefront id", { description: "New description" })

Orders

List orders

    const response = await paystack.order.list({ perPage: 10, page: 1 })

Fetch order

    const response = await paystack.order.fetch("order id")

Update order

    const response = await paystack.order.update("order id", { status: "delivered" })

Payment Pages

Create payment page

    const response = await paystack.payment_page.create({
        name: "Buy Ebook",
        amount: 50000,
    })

List payment pages

    const response = await paystack.payment_page.list({ perPage: 10, page: 1 })

Fetch payment page

    const response = await paystack.payment_page.fetch("page id or slug")

Update payment page

    const response = await paystack.payment_page.update("page id or slug", { description: "New description" })

Check slug availability

    const response = await paystack.payment_page.check_slug_availability("my-page-slug")

Add products to page

    const response = await paystack.payment_page.add_products("page id", { product: [123, 456] })

Settlements

List settlements

    const response = await paystack.settlement.list({ perPage: 10, status: "success" })

List settlement transactions

    const response = await paystack.settlement.list_transactions("settlement id", { perPage: 10 })

Transfer Recipients

Create transfer recipient

    const response = await paystack.transfer_recipient.create({
        type: "nuban",
        name: "Tolu Robert",
        account_number: "0000000000",
        bank_code: "058",
        currency: "NGN",
    })

Bulk create transfer recipients

    const response = await paystack.transfer_recipient.bulk_create({
        batch: [
            { type: "nuban", name: "Habenero Mundane", account_number: "0123456789", bank_code: "033" },
        ],
    })

List transfer recipients

    const response = await paystack.transfer_recipient.list({ perPage: 10, page: 1 })

Fetch transfer recipient

    const response = await paystack.transfer_recipient.fetch("recipient id or code")

Update transfer recipient

    const response = await paystack.transfer_recipient.update("recipient id or code", { name: "New name" })

Delete transfer recipient

    const response = await paystack.transfer_recipient.delete("recipient id or code")

Transfers

Initiate transfer

    const response = await paystack.transfer.initiate({
        source: "balance",
        amount: 10000,
        recipient: "RCP_xxxxxxxx",
        reason: "Holiday Flexing",
    })

Finalize transfer

    const response = await paystack.transfer.finalize({ transfer_code: "TRF_xxxxxxxx", otp: "123456" })

Initiate bulk transfer

    const response = await paystack.transfer.initiate_bulk({
        source: "balance",
        transfers: [
            { amount: 10000, recipient: "RCP_xxxxxxxx", reason: "Salary" },
        ],
    })

List transfers

    const response = await paystack.transfer.list({ perPage: 10, page: 1 })

Fetch transfer

    const response = await paystack.transfer.fetch("transfer id or code")

Verify transfer

    const response = await paystack.transfer.verify("transfer reference")

Transfers Control

Check balance

    const response = await paystack.transfers_control.check_balance()

Fetch balance ledger

    const response = await paystack.transfers_control.fetch_balance_ledger()

Resend transfer OTP

    const response = await paystack.transfers_control.resend_otp({ transfer_code: "TRF_xxxxxxxx", reason: "resend_otp" })

Disable OTP requirement for transfers

    const response = await paystack.transfers_control.disable_otp()

Finalize disable OTP

    const response = await paystack.transfers_control.finalize_disable_otp({ otp: "123456" })

Enable OTP requirement for transfers

    const response = await paystack.transfers_control.enable_otp()

Bulk Charges

Initiate bulk charge

    const response = await paystack.bulk_charge.initiate([
        { authorization: "AUTH_ncx8hews93", amount: 2500, reference: "dam1266638dhhd" },
        { authorization: "AUTH_xfuz7dy4b9", amount: 1500, reference: "dam1266638dhhe" },
    ])

List bulk charge batches

    const response = await paystack.bulk_charge.list({ perPage: 10, page: 1 })

Fetch bulk charge batch

    const response = await paystack.bulk_charge.fetch_batch("batch id or code")

Fetch charges in a batch

    const response = await paystack.bulk_charge.fetch_charges("batch id or code", { status: "success" })

Pause bulk charge batch

    const response = await paystack.bulk_charge.pause("batch code")

Resume bulk charge batch

    const response = await paystack.bulk_charge.resume("batch code")

Integration

Fetch payment session timeout

    const response = await paystack.integration.fetch_payment_session_timeout()

Update payment session timeout

    const response = await paystack.integration.update_payment_session_timeout({ timeout: 30 })

Charge

Create charge

    const response = await paystack.charge.create({
        email: "[email protected]",
        amount: 10000,
        bank: { account_number: "0000000000", code: "057" },
    })

Submit PIN

    const response = await paystack.charge.submit_pin({ pin: "1234", reference: "transaction reference" })

Submit OTP

    const response = await paystack.charge.submit_otp({ otp: "123456", reference: "transaction reference" })

Submit phone

    const response = await paystack.charge.submit_phone({ phone: "08012345678", reference: "transaction reference" })

Submit birthday

    const response = await paystack.charge.submit_birthday({ birthday: "1990-01-01", reference: "transaction reference" })

Submit address

    const response = await paystack.charge.submit_address({
        address: "140 N 2nd St",
        city: "Stroudsburg",
        state: "Pennsylvania",
        zipcode: "18360",
        reference: "transaction reference",
    })

Check pending charge

    const response = await paystack.charge.check_pending("transaction reference")

Disputes

List disputes

    const response = await paystack.dispute.list({ perPage: 10, status: "pending" })

Fetch dispute

    const response = await paystack.dispute.fetch("dispute id")

List transaction disputes

    const response = await paystack.dispute.list_transaction_disputes("transaction id")

Update dispute

    const response = await paystack.dispute.update("dispute id", { refund_amount: 10000 })

Add evidence

    const response = await paystack.dispute.add_evidence("dispute id", {
        customer_email: "[email protected]",
        customer_name: "Mensah King",
        customer_phone: "0802345167",
        service_details: "claim for buying product",
    })

Get upload URL

    const response = await paystack.dispute.get_upload_url("dispute id", { upload_filename: "receipt.pdf" })

Resolve dispute

    const response = await paystack.dispute.resolve("dispute id", {
        resolution: "merchant-accepted",
        message: "Merchant accepted",
        refund_amount: 10000,
        uploaded_filename: "qesp8a4df1xejihd9x5q",
    })

Export disputes

    const response = await paystack.dispute.export({ perPage: 10 })

Refunds

Create refund

    const response = await paystack.refund.create({ transaction: "transaction id or reference", amount: 10000 })

List refunds

    const response = await paystack.refund.list({ perPage: 10, page: 1 })

Fetch refund

    const response = await paystack.refund.fetch("refund id")

Verification

Resolve account number

    const response = await paystack.verification.resolve_account({
        account_number: "0022728151",
        bank_code: "063",
    })

Validate account

    const response = await paystack.verification.validate_account({
        account_name: "Ann Bron",
        account_number: "0000000000",
        account_type: "personal",
        bank_code: "632005",
        country_code: "ZA",
        document_type: "identityNumber",
        document_number: "1234567890123",
    })

Resolve card BIN

    const response = await paystack.verification.resolve_card_bin("539983")

ROADMAP

[x] Requests
- [x] Create payment request
- [x] Update payment request
- [x] Fetch payment request
- [x] List payment requests
- [x] Verify payment request
- [x] Send Notification
- [x] Payment request total
- [x] Finalize payment request
- [x] Archive payment request
- [x] Tests
[x] Customers
- [x] Create Customer
- [x] List Customers
- [x] Fetch Customer
- [x] Update Customer
- [x] Validate Customer
- [x] Whitelist/Blacklist Customer
- [x] Deactivate Authorization
- [x] Tests
[x] Products
- [x] Create Product
- [x] List Products
- [x] Fetch Product
- [x] Update Product
- [x] Tests
[x] Dedicated Virtual Accounts
- [x] Create Dedicated Virtual Account
- [x] Assign Dedicated Virtual Account
- [x] List Dedicated Accounts
- [x] Fetch Dedicated Account
- [x] Requery Dedicated Account
- [x] Deactivate Dedicated Account
- [x] Split Dedicated Account Transaction
- [x] Remove Split from Dedicated Account
- [x] Fetch Bank Providers
- [x] Tests
[x] Transactions
- [x] Initialize Transaction
- [x] Verify Transaction
- [x] List Transactions
- [x] Fetch Transaction
- [x] Charge Authorization
- [x] View Transaction Timeline
- [x] Transaction Totals
- [x] Export Transactions
- [x] Partial Debit
- [x] Tests
[x] Transaction Splits
- [x] Create Split
- [x] List/Search Splits
- [x] Fetch Split
- [x] Update Split
- [x] Add/Update Subaccount Split
- [x] Remove Subaccount from Split
- [x] Tests
[x] Terminal
- [x] Send Event
- [x] Fetch Event Status
- [x] Fetch Terminal Status
- [x] List Terminals
- [x] Fetch Terminal
- [x] Update Terminal
- [x] Commission Terminal
- [x] Decommission Terminal
- [x] Tests
[x] Virtual Terminal
- [x] Create Virtual Terminal
- [x] List Virtual Terminals
- [x] Fetch Virtual Terminal
- [x] Update Virtual Terminal
- [x] Deactivate Virtual Terminal
- [x] Assign Destination
- [x] Unassign Destination
- [x] Add Split Code
- [x] Remove Split Code
- [x] Tests
[x] Direct Debit
- [x] Trigger Activation Charge
- [x] Fetch Mandate Authorizations
- [x] Tests
[x] Preauthorization
- [x] Initialize Preauthorization
- [x] Capture Preauthorization
- [x] Release Preauthorization
- [x] Reauthorize Preauthorization
- [x] Tests
[x] Apple Pay
- [x] Register Domain
- [x] List Domains
- [x] Unregister Domain
- [x] Tests
[x] Capitec Pay
- [x] Charge with Capitec Pay
- [x] Check Charge Status
- [x] Tests
[x] Subaccounts
- [x] Create Subaccount
- [x] List Subaccounts
- [x] Fetch Subaccount
- [x] Update Subaccount
- [x] Tests
[x] Plans
- [x] Create Plan
- [x] List Plans
- [x] Fetch Plan
- [x] Update Plan
- [x] Tests
[x] Subscriptions
- [x] Create Subscription
- [x] List Subscriptions
- [x] Fetch Subscription
- [x] Enable Subscription
- [x] Disable Subscription
- [x] Generate Update Subscription Link
- [x] Send Update Subscription Link
- [x] Tests
[x] Storefronts
- [x] Create Storefront
- [x] List Storefronts
- [x] Fetch Storefront
- [x] Update Storefront
- [x] Tests
[x] Orders
- [x] List Orders
- [x] Fetch Order
- [x] Update Order
- [x] Tests
[x] Payment Pages
- [x] Create Payment Page
- [x] List Payment Pages
- [x] Fetch Payment Page
- [x] Update Payment Page
- [x] Check Slug Availability
- [x] Add Products to Page
- [x] Tests
[x] Settlements
- [x] List Settlements
- [x] List Settlement Transactions
- [x] Tests
[x] Transfer Recipients
- [x] Create Transfer Recipient
- [x] Bulk Create Transfer Recipient
- [x] List Transfer Recipients
- [x] Fetch Transfer Recipient
- [x] Update Transfer Recipient
- [x] Delete Transfer Recipient
- [x] Tests
[x] Transfers
- [x] Initiate Transfer
- [x] Finalize Transfer
- [x] Initiate Bulk Transfer
- [x] List Transfers
- [x] Fetch Transfer
- [x] Verify Transfer
- [x] Tests
[x] Transfers Control
- [x] Check Balance
- [x] Fetch Balance Ledger
- [x] Resend Transfer OTP
- [x] Disable OTP Requirement for Transfers
- [x] Finalize Disable OTP
- [x] Enable OTP Requirement for Transfers
- [x] Tests
[x] Bulk Charges
- [x] Initiate Bulk Charge
- [x] List Bulk Charge Batches
- [x] Fetch Bulk Charge Batch
- [x] Fetch Charges in a Batch
- [x] Pause Bulk Charge Batch
- [x] Resume Bulk Charge Batch
- [x] Tests
[x] Integration
- [x] Fetch Payment Session Timeout
- [x] Update Payment Session Timeout
- [x] Tests
[x] Charge
- [x] Create Charge
- [x] Submit PIN
- [x] Submit OTP
- [x] Submit Phone
- [x] Submit Birthday
- [x] Submit Address
- [x] Check Pending Charge
- [x] Tests
[x] Disputes
- [x] List Disputes
- [x] Fetch Dispute
- [x] List Transaction Disputes
- [x] Update Dispute
- [x] Add Evidence
- [x] Get Upload URL
- [x] Resolve Dispute
- [x] Export Disputes
- [x] Tests
[x] Refunds
- [x] Create Refund
- [x] List Refunds
- [x] Fetch Refund
- [x] Tests
[x] Verification
- [x] Resolve Account Number
- [x] Validate Account
- [x] Resolve Card BIN
- [x] Tests
[x] Miscellanous
- [x] List Banks
- [x] List/Search Countries
- [x] List States (AVS)

Testing

To run the tests, clone the repository

    git clone https://github.com/Ahdeyyy/paystack-api.git

    bun test