Transactions
Manage transactions, query statuses, logs and fees.
Verify a transaction
This endpoint helps developers to query the final status of a transaction. This can be used to check transactions of all payment types after they have been attempted.
get
https://api.flutterwave.com/v3/transactions/:id/verifyPath Params
int32
This is a unique transaction identifier generated by our systems. It is returned in the initiate charge response as data.id
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.
const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave("public key", "secret key");
const payload = {"id": "288200108"};
const response = await flw.Transaction.verify(payload)
require("Flutterwave-PHP-v3/library/Transactions.php");
use Flutterwave\Transactions;
$history = new Transactions();
$data = array("id"=>"288200108");
$verifyTransaction = $history->verifyTransaction($data);
print_r($verifyTransaction);
require './flutterwave_sdk'
payment = Flutterwave.new("public key", "secret key", "encryption key")
transactions = Transactions.new(payment)
response = transactions.verify_transaction("288200108")
print response
{
"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"
}
}
}
{}
You can also verify transaction using your transaction reference tx_ref
. This is done by sending a GET request to https://api.flutterwave.com/v3/transactions/verify_by_reference. The tx_ref should be passed as a query parameter for this call.
Create a Refund
This endpoint allows you to create a refund for any transaction that is being disputed. Kindly note that refunds initiated usually take between 3-15 working days to be completed.
post
https://api.flutterwave.com/v3/transactions/:id/refundPath Params
string
This is a unique transaction identifier generated by our systems. It is returned in the initiate charge and verify transaction responses as data.id
Body Params
Show optional parameters
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.
const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave("public key", "secret key");
const payload = {"id": "908790", "amount":"5000"};
const response = await flw.Transaction.refund(payload)
require './flutterwave_sdk'
payment = Flutterwave.new("public key", "secret key", "encryption key")
transactions = Transactions.new(payment)
payload = {
"amount" => "5"
}
# id = 908790
transactions = Transactions.new(payment)
response = transactions.initiate_a_refund(payload, 908790)
print response
{
"status": "success",
"message": "Transaction refund initiated",
"data": {
"id": 8612,
"account_id": 73362,
"tx_id": 908790,
"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"
}
}
{}
Get multiple Transactions
This endpoint allows developers to query previously initiated transactions. You can do a single or bulk query with the endpoint depending on your use case.
get
https://api.flutterwave.com/v3/transactionsQuery Params
Show optional parameters
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.
const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave("public key", "secret key");
const payload = {
"from": "2020-01-01",
"to": "2020-05-05"
};
const response = await flw.Transaction.fetch(payload);
require("Flutterwave-PHP-v3/library/Transactions.php");
use Flutterwave\Transactions;
$data = array(
"from"=> "2020-01-01",
"to"=> "2020-05-05"
);
$history = new Transactions();
$transactions = $history->viewTransactions($data);
print_r($transactions);
require './flutterwave_sdk'
payment = Flutterwave.new("public key", "secret key", "encryption key")
transactions = Transactions.new(payment)
response = transactions.get_transactions
print response
{
"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 multiple refund transactions
This endpoint allows developers to query previously initiated refunds. You can get information for multiple refunded transactions using the query filters.
get
https://api.flutterwave.com/v3/refundsQuery Params
Show optional parameters
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.
{
"status": "success",
"message": "Refunds fetched",
"meta": {
"page_info": {
"total": 3,
"current_page": 1,
"total_pages": 1,
"page_size": 20
}
},
"data": [
{
"id": 258505,
"amount_refunded": 150,
"status": "completed-mpgs",
"flw_ref": "FLW265072855",
"comment": "",
"settlement_id": "412245",
"meta": "{\"source\":\"ledgerbalance\"}",
"created_at": "2020-06-26T13:07:15.000Z",
"account_id": 82796,
"transaction_id": 263746647
},
{
"id": 258504,
"amount_refunded": 150,
"status": "completed-mpgs",
"flw_ref": "FLW265071998",
"comment": "",
"settlement_id": "412245",
"meta": "{\"source\":\"ledgerbalance\"}",
"created_at": "2020-06-26T13:05:41.000Z",
"account_id": 82796,
"transaction_id": 263746287
},
{
"id": 258502,
"amount_refunded": 140,
"status": "completed-mpgs",
"flw_ref": "FLW265071246",
"comment": "",
"settlement_id": "412245",
"meta": "{\"source\":\"ledgerbalance\"}",
"created_at": "2020-06-26T13:04:38.000Z",
"account_id": 82796,
"transaction_id": 263745966
}
]
}
{}
Get refund details
This endpoint helps you query the details of a refunded transaction. it only supports querying one transaction per API call.
get
https://api.flutterwave.com/v3/refunds/:idPath Params
int32
This is a unique transaction identifier generated by our systems. It is returned in the initiate charge and verify transaction responses as data.id
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.
{
"id": 469462,
"amount_refunded": 101.4,
"status": "completed-mpgs",
"flw_ref": "ZRIR3520596614954",
"comment": null,
"settlement_id": "735099",
"meta": "{\"source\":\"ledgerbalance\",\"uniquereference\":\"65972551792\",\"provider\":\"GTBANK_DIRECT\"}",
"created_at": "2021-05-12T23:19:11.000Z",
"account_id": 35308,
"transaction_id": 394347475
}
{}
Get transactions fees (Collections)
This endpoint helps developers query the fees expected to be paid for a particular transaction. This endpoint only returns fees for collections i.e. inflows.
get
https://api.flutterwave.com/v3/transactions/feeQuery Params
int32
This is the amount of the product or service to be charged from the customer.
string
This is the specified currency to charge in.
Show optional parameters
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.
const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave("public key", "secret key");
const payload = {
"amount": "1000",
"currency": "NGN"
};
const response = await flw.Transaction.fee(payload);
require("Flutterwave-PHP-v3/library/Transactions.php");
use Flutterwave\Transactions;
$data = array(
"amount"=> 1000,
"currency"=> "NGN",
"payment_type"=> "card"
);
$history = new Transactions();
$transactionfee = $history->getTransactionFee($data);
print_r($transactionfee);
require './flutterwave_sdk'
payment = Flutterwave.new("public key", "secret key", "encryption key")
transactions = Transactions.new(payment)
response = transactions.transaction_fee("NGN", "1000")
print response
{
"status": "success",
"message": "Charged fee",
"data": {
"charge_amount": 10000,
"fee": 140,
"merchant_fee": 0,
"flutterwave_fee": 140,
"stamp_duty_fee": 50,
"currency": "NGN"
}
}
{}
Resend failed Webhooks
This endpoint helps you resend webhooks from failed sending queues to your server.
post
https://api.flutterwave.com/v3/transactions/:id/resend-hookPath Params
int32
This is a unique transaction identifier generated by our systems. It is returned in the initiate charge response as data.id
Body Params
Show optional parameters
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.
const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave("public key", "secret key");
const payload = {"id": "1321548"};
const response = await flw.Transaction.resend_hooks(payload);
require './flutterwave_sdk'
payment = Flutterwave.new("public key", "secret key", "encryption key")
transactions = Transactions.new(payment)
response = transactions.resend_transactions_webhook(1321548)
print response
{
"status": "success",
"message": "hook sent successfully",
"data": null
}
{}
View transaction timeline
This endpoint allows you to view the timeline for a transaction. A transaction timeline is a list of events that happened to a selected transaction. Some key events include: loading the payment modal, Switching payment methods and Entering details in modal fields. Using the response, you can get insights into the transactions and payment behaviour of users.
get
https://api.flutterwave.com/v3/transactions/:id/eventsPath Params
int32
This is a unique transaction identifier generated by our systems. It is returned in the initiate charge and verify transaction responses as data.id
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.
const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave("public key", "secret key");
const payload = {"id": "1321548"};
const response = await flw.Transaction.event(payload);
require("Flutterwave-PHP-v3/library/Transactions.php");
use Flutterwave\Transactions;
$data = array("id"=> "1321548");
$history = new Transactions();
$timeline = $history->viewTimeline($data);
print_r($timeline);
require './flutterwave_sdk'
payment = Flutterwave.new("public key", "secret key", "encryption key")
transactions = Transactions.new(payment)
response = transactions.transactions_events(1321548)
print response
{
"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"
}
]
}
{}