?HAMA

Navigation

Breadcrumbs

/ / home / byroehnu / .trash / node_modules11 / flutterwave-node-v3 / documentation

Create

Create File | Create Folder | Upload Files | Run Command

Edit File Size: 20.99 KB

/home/byroehnu/.trash/node_modules11/flutterwave-node-v3/documentation/transactions.md

Text Base64

# TRANSACTIONS

We recommend reading the main readme first, to understand the requirements for using the library and how to initiate this in your apps. This guide assumes you've read that.

Manage user transactions via any of these methods:
1. [Get all transactions](#get-all-transactions)
2. [Get transaction fee](#get-transaction-fee)
3. [Resend transaction webhook](#resend-transaction-webhook)
4. [Verify transaction](#verify-transaction)
5. [Verify transaction with reference](#verify-transaction)
6. [Create a transaction refund](#create-a-transaction-refund)
7. [View transaction timeline](#view-transaction-timeline)

## Get all transactions

This describes how to fetch all transactions on your account

```javascript

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const fetch_transactions = async () => {

try {

const payload = {
            "from": "2020-01-01",
            "to": "2020-05-05"
        }
        const response = await flw.Transaction.fetch(payload)
        console.log(response);
    } catch (error) {
        console.log(error)
    }

}

fetch_transactions();
```

Sample Response

```javascript
{
  "status": "success",
  "message": "Transactions fetched",
  "meta": {
    "page_info": {
      "total": 44,
      "current_page": 1,
      "total_pages": 5
    }
  },
  "data": [
    {
      "id": "989226",
      "tx_ref": "m0ckaham-1578002686748",
      "flw_ref": "N/A",
      "device_fingerprint": "e2b5cd3ec0fa99d45bf204a1401fb981",
      "amount": 1000,
      "currency": "NGN",
      "charged_amount": 1000,
      "app_fee": null,
      "merchant_fee": 0,
      "processor_response": null,
      "auth_model": "AUTH",
      "ip": "197.211.58.137",
      "narration": "Earth Gang",
      "status": "pending",
      "payment_type": "account",
      "created_at": "2020-01-02T22:06:45.000Z",
      "amount_settled": null,
      "account": {
        "nuban": "0690000031",
        "bank": "ACCESS BANK NIGERIA"
      },
      "customer_name": "Yemi Desola",
      "customer_email": "user@gmail.com",
      "account_id": "73362"
    },
    {
      "id": "989223",
      "tx_ref": "m0ckaham-1578002686748",
      "flw_ref": "N/A",
      "device_fingerprint": "e2b5cd3ec0fa99d45bf204a1401fb981",
      "amount": 1000,
      "currency": "NGN",
      "charged_amount": 1000,
      "app_fee": null,
      "merchant_fee": 0,
      "processor_response": null,
      "auth_model": "AUTH",
      "ip": "197.211.58.137",
      "narration": "Earth Gang",
      "status": "pending",
      "payment_type": "account",
      "created_at": "2020-01-02T22:04:57.000Z",
      "amount_settled": null,
      "account": {
        "nuban": "0690000031",
        "bank": "ACCESS BANK NIGERIA"
      },
      "customer_name": "Yemi Desola",
      "customer_email": "user@gmail.com",
      "account_id": "73362"
    },
    {
      "id": "989222",
      "tx_ref": "m0ckaham-1578002611018",
      "flw_ref": "N/A",
      "device_fingerprint": "e2b5cd3ec0fa99d45bf204a1401fb981",
      "amount": 1000,
      "currency": "NGN",
      "charged_amount": 1000,
      "app_fee": null,
      "merchant_fee": 0,
      "processor_response": null,
      "auth_model": "AUTH",
      "ip": "197.211.58.137",
      "narration": "Earth Gang",
      "status": "pending",
      "payment_type": "account",
      "created_at": "2020-01-02T22:03:44.000Z",
      "amount_settled": null,
      "account": {
        "nuban": "0690000031",
        "bank": "ACCESS BANK NIGERIA"
      },
      "customer_name": "Yemi Desola",
      "customer_email": "user@gmail.com",
      "account_id": "73362"
    },
    {
      "id": "989217",
      "tx_ref": "m0ckaham-1578002504686",
      "flw_ref": "N/A",
      "device_fingerprint": "e2b5cd3ec0fa99d45bf204a1401fb981",
      "amount": 1000,
      "currency": "NGN",
      "charged_amount": 1000,
      "app_fee": null,
      "merchant_fee": 0,
      "processor_response": null,
      "auth_model": "AUTH",
      "ip": "197.211.58.137",
      "narration": "Earth Gang",
      "status": "pending",
      "payment_type": "account",
      "created_at": "2020-01-02T22:01:57.000Z",
      "amount_settled": null,
      "account": {
        "nuban": "0690000031",
        "bank": "ACCESS BANK NIGERIA"
      },
      "customer_name": "Yemi Desola",
      "customer_email": "user@gmail.com",
      "account_id": "73362"
    },
    {
      "id": "989216",
      "tx_ref": "m0ckaham-1578002147445",
      "flw_ref": "N/A",
      "device_fingerprint": "e2b5cd3ec0fa99d45bf204a1401fb981",
      "amount": 1000,
      "currency": "NGN",
      "charged_amount": 1000,
      "app_fee": null,
      "merchant_fee": 0,
      "processor_response": null,
      "auth_model": "AUTH",
      "ip": "197.211.58.137",
      "narration": "Earth Gang",
      "status": "pending",
      "payment_type": "account",
      "created_at": "2020-01-02T22:01:35.000Z",
      "amount_settled": null,
      "account": {
        "nuban": "0690000031",
        "bank": "ACCESS BANK NIGERIA"
      },
      "customer_name": "Yemi Desola",
      "customer_email": "user@gmail.com",
      "account_id": "73362"
    },
    {
      "id": "989214",
      "tx_ref": "m0ckaham-1578002147445",
      "flw_ref": "N/A",
      "device_fingerprint": "e2b5cd3ec0fa99d45bf204a1401fb981",
      "amount": 1000,
      "currency": "NGN",
      "charged_amount": 1000,
      "app_fee": null,
      "merchant_fee": 0,
      "processor_response": null,
      "auth_model": "AUTH",
      "ip": "197.211.58.137",
      "narration": "Earth Gang",
      "status": "pending",
      "payment_type": "account",
      "created_at": "2020-01-02T21:55:56.000Z",
      "amount_settled": null,
      "account": {
        "nuban": "0690000031",
        "bank": "ACCESS BANK NIGERIA"
      },
      "customer_name": "Yemi Desola",
      "customer_email": "user@gmail.com",
      "account_id": "73362"
    },
    {
      "id": "989213",
      "tx_ref": "m0ckaham-1578002107929",
      "flw_ref": "N/A",
      "device_fingerprint": "e2b5cd3ec0fa99d45bf204a1401fb981",
      "amount": 100000,
      "currency": "NGN",
      "charged_amount": 100000,
      "app_fee": null,
      "merchant_fee": 0,
      "processor_response": null,
      "auth_model": "AUTH",
      "ip": "197.211.58.137",
      "narration": "Earth Gang",
      "status": "pending",
      "payment_type": "account",
      "created_at": "2020-01-02T21:55:19.000Z",
      "amount_settled": null,
      "account": {
        "nuban": "0690000031",
        "bank": "ACCESS BANK NIGERIA"
      },
      "customer_name": "Yemi Desola",
      "customer_email": "user@gmail.com",
      "account_id": "73362"
    },
    {
      "id": "989208",
      "tx_ref": "m0ckaham-1578001692462",
      "flw_ref": "URF_1578001706192_7697035",
      "device_fingerprint": "e2b5cd3ec0fa99d45bf204a1401fb981",
      "amount": 100000,
      "currency": "NGN",
      "charged_amount": 100000,
      "app_fee": 1400,
      "merchant_fee": 0,
      "processor_response": "Approved Or Completed Successfully",
      "auth_model": "AUTH",
      "ip": "197.211.58.137",
      "narration": "Earth Gang",
      "status": "successful",
      "payment_type": "account",
      "created_at": "2020-01-02T21:48:26.000Z",
      "amount_settled": 98550,
      "account": {
        "nuban": "0690000031",
        "bank": "ACCESS BANK NIGERIA"
      },
      "customer_name": "Yemi Desola",
      "customer_email": "user@gmail.com",
      "account_id": "73362"
    },
    {
      "id": "989207",
      "tx_ref": "Flutterwave-Pages919998081709",
      "flw_ref": "URF_1578001508809_392835",
      "device_fingerprint": "e2b5cd3ec0fa99d45bf204a1401fb981",
      "amount": 1000,
      "currency": "NGN",
      "charged_amount": 1000,
      "app_fee": 14,
      "merchant_fee": 0,
      "processor_response": "Approved Or Completed Successfully",
      "auth_model": "AUTH",
      "ip": "197.211.58.137",
      "narration": "Earth Gang",
      "status": "successful",
      "payment_type": "account",
      "created_at": "2020-01-02T21:45:08.000Z",
      "amount_settled": 936,
      "account": {
        "nuban": "0690000031",
        "bank": "ACCESS BANK NIGERIA"
      },
      "customer_name": "Yemi Desola",
      "customer_email": "user@gmail.com",
      "account_id": "73362"
    },
    {
      "id": "989058",
      "tx_ref": "m0ckaham-1577989302655",
      "flw_ref": "URF_1577989314468_5262435",
      "device_fingerprint": "e2b5cd3ec0fa99d45bf204a1401fb981",
      "amount": 50000,
      "currency": "NGN",
      "charged_amount": 50000,
      "app_fee": 700,
      "merchant_fee": 0,
      "processor_response": "Approved Or Completed Successfully",
      "auth_model": "AUTH",
      "ip": "197.211.58.137",
      "narration": "Earth Gang",
      "status": "successful",
      "payment_type": "account",
      "created_at": "2020-01-02T18:21:54.000Z",
      "amount_settled": 49300,
      "account": {
        "nuban": "0690000031",
        "bank": "ACCESS BANK NIGERIA"
      },
      "customer_name": "Yemi Desola",
      "customer_email": "user@gmail.com",
      "account_id": "73362"
    }
  ]
}
```

## Get transaction fee

This describes how Get transaction fees

```javascript

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const get_fee = async () => {

try {

const payload = {
            "amount": "1000",
            "currency": "NGN"
        }
        const response = await flw.Transaction.fee(payload)
        console.log(response);
    } catch (error) {
        console.log(error)
    }

}

get_fee();
```

Sample Response

```javascript
{
  "status": "success",
  "message": "Charged fee",
  "data": {
      "charge_amount": 10000,
      "fee": 140,
      "merchant_fee": 0,
      "flutterwave_fee": 140,
      "stamp_duty_fee": 50,
      "currency": "NGN"
  }
}
```

## Resend transaction webhook

This describes how resend a failed transaction webhook to your server

```javascript

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const resendHooks = async () => {

try {

const payload = {
            "tx_ref": "rave-123wsvgfwefcwsfc456"
        }
        const response = await flw.Transaction.resend_hooks(payload)
        console.log(response);
    } catch (error) {
        console.log(error)
    }

}

resendHooks();

```

Sample Response

```javascript
{
    "status": "success",
    "message": "hook sent successfully",
    "data": "hook sent"
}
```

## Create a transaction refund

This describes how to initiate a transaction refund

```javascript

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const refund = async () => {

try {

const payload = {
            "id": "5708", //This is the transaction unique identifier. It is returned in the initiate transaction call as data.id
            "amount":"10"
        }
        const response = await flw.Transaction.refund(payload)
        console.log(response);
    } catch (error) {
        console.log(error)
    }

}

refund();

```

Sample Response

```javascript
{
  "status": "success",
  "message": "Transaction refund initiated",
  "data": {
      "id": 8612,
      "account_id": 73362,
      "tx_id": 5708,
      "flw_ref": "URF_1577867664541_3572735",
      "wallet_id": 74639,
      "amount_refunded": 5000,
      "status": "completed",
      "destination": "payment_source",
      "meta": {
          "source": "availablebalance"
      },
      "created_at": "2020-01-24T09:18:37.366Z"
  }
}
```

## Verify transaction

This describes how to verify transactions using the transaction id

```javascript

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const verify = async () => {

try {
        const payload = {"id": "288200108" //This is the transaction unique identifier. It is returned in the initiate transaction call as data.id
        }
        const response = await flw.Transaction.verify(payload)
        console.log(response);
    } catch (error) {
        console.log(error)
    }

}

verify();
```

Sample Response

```javascript
{
  "status": "success",
  "message": "Transaction fetched successfully",
  "data": {
    "id": 288200108,
    "tx_ref": "LiveCardTest",
    "flw_ref": "YemiDesola/FLW275407301",
    "device_fingerprint": "N/A",
    "amount": 100,
    "currency": "NGN",
    "charged_amount": 100,
    "app_fee": 1.4,
    "merchant_fee": 0,
    "processor_response": "Approved by Financial Institution",
    "auth_model": "PIN",
    "ip": "::ffff:10.5.179.3",
    "narration": "CARD Transaction ",
    "status": "successful",
    "payment_type": "card",
    "created_at": "2020-07-15T14:31:16.000Z",
    "account_id": 17321,
    "card": {
      "first_6digits": "232343",
      "last_4digits": "4567",
      "issuer": "FIRST CITY MONUMENT BANK PLC",
      "country": "NIGERIA NG",
      "type": "VERVE",
      "token": "flw-t1nf-4676a40c7ddf5f12scr432aa12d471973-k3n",
      "expiry": "02/23"
    },
    "meta": null,
    "amount_settled": 98.6,
    "customer": {
      "id": 216519823,
      "name": "Yemi Desola",
      "phone_number": "N/A",
      "email": "user@gmail.com",
      "created_at": "2020-07-15T14:31:15.000Z"
    }
  }
}
```

## Verify transaction with reference

This describes how to verify transactions status using the transaction reference (tx_ref).

```javascript

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const verify_by_tx = async () => {

try {
        const payload = {"tx_ref": "txref-DI0NzMx13" //This is the transaction reference. It is returned in the initiate transaction call as data.tx_ref
        }
        const response = await flw.Transaction.verify_by_tx(payload)
        console.log(response);
    } catch (error) {
        console.log(error)
    }

}

verify_by_tx();
```

Sample Response

```javascript
{
    "status": "success",
    "message": "Transaction fetched successfully",
    "data": {
        "id": 8415006,
        "tx_ref": "txref-DI0NzMx13",
        "flw_ref": "FLW-MOCK-3b10a512c4dae649e580a7e5747cfd2c",
        "device_fingerprint": "2a4bf5d669b2a0cd4b684ffba8caaae8",
        "amount": 2500,
        "currency": "NGN",
        "charged_amount": 2500,
        "app_fee": 35,
        "merchant_fee": 0,
        "processor_response": "Please enter the OTP sent to your mobile number 080****** and email te**@rave**.com",
        "auth_model": "NOAUTH",
        "ip": "54.75.161.64",
        "narration": "CARD Transaction ",
        "status": "successful",
        "payment_type": "card",
        "created_at": "2025-02-27T18:29:34.000Z",
        "account_id": 20937,
        "card": {
            "first_6digits": "418742",
            "last_4digits": "4246",
            "issuer": "ACCESS BANK PLC DEBIT CLASSIC",
            "country": "NIGERIA NG",
            "type": "VISA",
            "token": "flw-t1nf-937086f0365b7334de60da246def40df-m03k",
            "expiry": "09/32"
        },
        "meta": {
            "__CheckoutInitAddress": "https://cdpn.io/FlutterwaveEng/fullembedgrid/PoVpKqb?animations=run&forceRefresh=1740680880044&type=embed",
            "source": "docs-inline-test",
            "consumer_mac": "92a3-912ba-1192a"
        },
        "amount_settled": 2462.37,
        "customer": {
            "id": 2362222,
            "name": "Ayomide Jimi-Oni",
            "phone_number": "08100000000",
            "email": "test@mailinator.com",
            "created_at": "2024-02-28T09:51:09.000Z"
        }
    }
}
```

## View transaction timeline

This describes how view Transaction Timeline

```javascript

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const View_Transaction_Timeline = async () => {

try {
        const payload = {
            "id": "1296063" //This is the unique transaction ID. It is returned in the verify transaction call as data.id
        }
        const response = await flw.Transaction.event(payload)
        console.log(response);
    } catch (error) {
        console.log(error)
    }

}

View_Transaction_Timeline();
```

Sample Response

```javascript
{
  "status": "success",
  "message": "Transaction events fetched",
  "data": [
    {
      "note": "Loaded modal https://raveappv2.herokuapp.com/pay/akhlm",
      "actor": "h0vkard@flw.ext",
      "object": "modal",
      "action": "loaded",
      "context": "web",
      "created_at": "2019-12-13T22:09:57.997Z"
    },
    {
      "note": "Switched to Pay with Bank Option",
      "actor": "h0vkard@flw.ext",
      "object": "modal",
      "action": "switched",
      "context": "web",
      "created_at": "2019-12-13T22:09:58.001Z"
    },
    {
      "note": "Pay button clicked",
      "actor": "h0vkard@flw.ext",
      "object": "MODAL",
      "action": "click",
      "context": "web",
      "created_at": "2019-12-13T22:09:56.903Z"
    },
    {
      "note": "IP Resolved 197.210.29.248",
      "actor": "h0vkard@flw.ext",
      "object": "IP",
      "action": "request",
      "context": "web",
      "created_at": "2019-12-13T22:09:59.595Z"
    },
    {
      "note": "Switched to Pay with Card Option",
      "actor": "h0vkard@flw.ext",
      "object": "modal",
      "action": "switched",
      "context": "web",
      "created_at": "2019-12-13T22:10:00.314Z"
    },
    {
      "note": "Entering Card Number",
      "actor": "h0vkard@flw.ext",
      "object": "Card Number",
      "action": "typing",
      "context": "web",
      "created_at": "2019-12-13T22:10:03.505Z"
    },
    {
      "note": "Stopped entering Card Number",
      "actor": "h0vkard@flw.ext",
      "object": "Card Number",
      "action": "typing",
      "context": "web",
      "created_at": "2019-12-13T22:10:04.522Z"
    },
    {
      "note": "Entering Expiry",
      "actor": "h0vkard@flw.ext",
      "object": "Expiry",
      "action": "typing",
      "context": "web",
      "created_at": "2019-12-13T22:10:04.523Z"
    },
    {
      "note": "Entering CVV",
      "actor": "h0vkard@flw.ext",
      "object": "CVV",
      "action": "typing",
      "context": "web",
      "created_at": "2019-12-13T22:10:06.595Z"
    },
    {
      "note": "Stopped entering Expiry",
      "actor": "h0vkard@flw.ext",
      "object": "Expiry",
      "action": "typing",
      "context": "web",
      "created_at": "2019-12-13T22:10:06.593Z"
    },
    {
      "note": "Stopped entering CVV",
      "actor": "h0vkard@flw.ext",
      "object": "CVV",
      "action": "typing",
      "context": "web",
      "created_at": "2019-12-13T22:10:12.412Z"
    },
    {
      "note": "Attempting card charge request",
      "actor": "h0vkard@flw.ext",
      "object": "CREDIT_CARD",
      "action": "charge",
      "context": "web",
      "created_at": "2019-12-13T22:10:12.530Z"
    },
    {
      "note": "Submitted Payment Details",
      "actor": "h0vkard@flw.ext",
      "object": "payment details:credit_card",
      "action": "submitted",
      "context": "web",
      "created_at": "2019-12-13T22:10:12.529Z"
    },
    {
      "note": "card charge request successful: request for PIN",
      "actor": "h0vkard@flw.ext",
      "object": "CREDIT_CARD",
      "action": "charge",
      "context": "web",
      "created_at": "2019-12-13T22:10:14.097Z"
    },
    {
      "note": "Attempting card charge request",
      "actor": "h0vkard@flw.ext",
      "object": "CREDIT_CARD",
      "action": "charge",
      "context": "web",
      "created_at": "2019-12-13T22:10:19.209Z"
    },
    {
      "note": "Card charge taking too long. Polling for response",
      "actor": "h0vkard@flw.ext",
      "object": "LONG_REQUEST",
      "action": "charge",
      "context": "web",
      "created_at": "2019-12-13T22:10:23.880Z"
    },
    {
      "note": "card charge request successful: request for OTP",
      "actor": "h0vkard@flw.ext",
      "object": "CREDIT_CARD",
      "action": "charge",
      "context": "web",
      "created_at": "2019-12-13T22:10:25.263Z"
    },
    {
      "note": "Attempting to validate card charge",
      "actor": "h0vkard@flw.ext",
      "object": "CARD_CHARGE",
      "action": "validate",
      "context": "web",
      "created_at": "2019-12-13T22:10:31.630Z"
    },
    {
      "note": "Validate card charge request complete",
      "actor": "h0vkard@flw.ext",
      "object": "CARD_CHARGE",
      "action": "validate",
      "context": "web",
      "created_at": "2019-12-13T22:10:33.146Z"
    },
    {
      "note": "Transaction Completed!",
      "actor": "h0vkard@flw.ext",
      "object": "TRANSACTION",
      "action": "completion",
      "context": "web",
      "created_at": "2019-12-13T22:10:33.151Z"
    },
    {
      "note": "Validate card charge successful",
      "actor": "h0vkard@flw.ext",
      "object": "CARD_CHARGE",
      "action": "validate",
      "context": "web",
      "created_at": "2019-12-13T22:10:33.147Z"
    }
  ]
}
```

Exit & Reset Text mode: syntax highlighting auto-detects file type.

Directory Contents

Dirs: 0 × Files: 16

Sort:

Enable drag-to-move

Name	Size	Perms	Modified	Actions
banks.md	13.22 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
beneficiary.md	6.40 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
billPayments.md	20.69 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
collections.md	33.42 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
ebills.md	2.35 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
misc.md	5.85 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
otp.md	2.36 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
payment-plan.md	8.39 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
settlements.md	12.92 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
subaccount.md	9.89 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
subscription.md	4.84 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
tokenization.md	13.03 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
transactions.md	20.99 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
transfers.md	15.22 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
virtualAccount.md	7.40 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive
virtualCard.md	11.38 KB	lrw-r--r--	2026-02-21 00:54:24	Edit Download recursive recursive