Preauthorisation
Introduction
The Preauthorize APIs allow Developers to manage preauth attempts on Card transactions. You can capture, void or refund preauth transactions.
Create a Charge
When you create a preauth charge, you must apply this to either a Card
transaction.
Creating a new preauthorize charge will create a lien on the customer's account for the transaction amount. The hold on the funds only lasts for seven working days.
You can optionally attempt a preauth charge in secured mode. This mode would ensure that the user completes the transaction in VBVSECURECODE
auth model and redirect them to meta.authorization.redirect
to preauthorize the transaction.
A Preauth object is created and returned as the response.
post
https://api.flutterwave.com/v3/charges?type=cardBody Params
int32
This is the amount to be charged for the transaction.
int32
This is the number on the cardholders card. Sample cards can be used to mock transactions.
int32
Card security code. This is 3/4 digit code at the back of the customers card, used for web payments.
int32
Two-digit number representing the card's expiration month.
int32
Two-digit number representing the card's expiration year.
string
The customer's email address.. It is the address to which the receipt will be sent. Receipts are sent for both test and live transactions.
string
This is a unique reference peculiar to the transaction being carried out.
boolean
This should be set to true for preauthoize card transactions
object
This is an object that contains the authorization details of the card you want to charge. The authorization instructions for card charges are returned in the initiate charge call as `meta.authorization`
string
This is the auth model of the card to use when validating, it is returned in the initiate charge call as authorization.mode
int32
This is the card's pin. Required when the suggested auth mode is PIN
string
This is the city in the card's billing details. It is required when the suggested auth mode is avs_noauth
string
This is the cards billing address. It is required when the suggested auth mode is avs_noauth
string
This is the card issuing state. It is required when the suggested auth mode is avs_noauth
string
This is the cards issuing country. It is required when the suggested auth mode is avs_noauth
int32
This is cards billing address zipcod. It is required when the suggested auth mode is avs_noauth
Show optional parameters
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call
{
"card_number": "*****",
"cvv": "157",
"expiry_month": "5",
"expiry_year": "22",
"amount": "20000",
"fullname": "Flutterwave Developers",
"tx_ref": "sample-ref",
"currency": "NGN",
"country": "NG",
"email": "developers@flutterwavego.com",
"redirect_url":"https://www.flutterwave.com/ng/",
"meta": {
"values": "TESTX29",
"random": "9988",
},
"preauthorize": true
}
{
"status": "success",
"message": "Successful",
"data": {
"id": 4962404,
"tx_ref": "13_15901x",
"flw_ref": "FLW-MOCK-PREAUTH-d7108582722457d542dc11051ad3af5f",
"device_fingerprint": "N/A",
"amount": 120,
"charged_amount": 120,
"app_fee": 6.96,
"merchant_fee": 0,
"processor_response": "Approved. Successful",
"auth_model": "NOAUTH",
"currency": "NGN",
"ip": "54.75.161.64",
"narration": "FLW-PBF CARD Transaction ",
"status": "pending",
"auth_url": "N/A",
"payment_type": "card",
"plan": null,
"fraud_status": "ok",
"charge_type": "preauth",
"created_at": "2024-03-12T23:59:44.000Z",
"account_id": 20937,
"customer": {
"id": 2370821,
"phone_number": null,
"name": "Test User",
"email": "user@gmail.com",
"created_at": "2024-03-12T23:59:44.000Z"
},
"card": {
"first_6digits": "537728",
"last_4digits": "7450",
"issuer": "MASTERCARD JSB PROBUSINESSBANK CREDITGOLD",
"country": "RU",
"type": "MASTERCARD",
"expiry": "09/31"
}
}
}
{
"status": "error",
"message": "No PBTX transaction found",
"data": null
}
To initiate a preauth charge in secure mode, simply pass a usesecureauth
parameter in your card charge payload and set the value to true before encryption.
Capture a Charge
This endpoint allows you to capture the payment of an existing but uncaptured charge. This is the final step of a two-part payment flow. Where you first need to create the charge.
Uncaptured funds expire after seven (7) working days after the charge is first created. If they remain uncaptured at this time, they will no longer be eligible for capture.
Capturing a charge is always successful, unless the charge is previously captured, refunded or expired. In such cases, We return HTTP code 400 for the call.
post
https://api.flutterwave.com/v3/charges/:flw_ref/capturePath Params
string
This is the data.flw_ref
returned in the charge response.
Body Params
int32
This is the amount to be captured. This allows you to capture an amount less than the original amount authorised on the card.
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call
require("../library/Preauth.php");
use Flutterwave\Preauth;
$payment = new Preauth();
$result = $payment->cardCharge($card);
$capture = $payment->captureFunds(['flw_ref' => 'FLW-MOCK-PREAUTH-72544a3c7659bcd74cc3a3110fe95101', 'amount' => 2000]); //pass flw_ref and amount
echo "<pre>";
print_r($capture);
echo "<pre>";
exit;
require './flutterwave_sdk'
payment = Flutterwave.new(ENV["PUBLIC_KEY"], ENV["SECRET_KEY"], ENV["ENCRYPTION_KEY"])
auth = Preauth.new(payment)
payload = {
"amount" => "50"
}
flw_ref = "FLW-MOCK-PREAUTH-72544a3c7659bcd74cc3a3110fe95101"
repsonse = auth.capture_preauth(flw_ref, payload)
print response
{
"status": "success",
"message": "Charge captured",
"data": {
"id": 4962404,
"tx_ref": "13_15901x",
"flw_ref": "FLW-MOCK-PREAUTH-d7108582722457d542dc11051ad3af5f",
"device_fingerprint": "N/A",
"amount": 50,
"charged_amount": 50,
"app_fee": 2.9,
"merchant_fee": 0,
"processor_response": "Approved",
"auth_model": "NOAUTH",
"currency": "NGN",
"ip": "54.75.161.64",
"narration": "FLW-PBF CARD Transaction ",
"status": "successful",
"auth_url": "N/A",
"payment_type": "card",
"plan": null,
"fraud_status": "ok",
"charge_type": "preauth",
"created_at": "2024-03-12T23:59:44.000Z",
"account_id": 20937,
"customer": {
"id": 2370821,
"phone_number": null,
"name": "Test User",
"email": "user@gmail.com",
"created_at": "2024-03-12T23:59:44.000Z"
},
"card": {
"first_6digits": "537728",
"last_4digits": "7450",
"issuer": "MASTERCARD JSB PROBUSINESSBANK CREDITGOLD",
"country": "RU",
"type": "MASTERCARD",
"expiry": "09/31"
}
}
}
{
"status": "error",
"message": "Transaction with ref FLW-MOCK-PREAUTH-d7108582722457d542dc11051ad3af either does not exist or is not a valid preauth transaction",
"data": null
}
Void a Charge
Voids the payment of a captured charge. This releases the hold on the previously captured funds
This can happen for a number of reasons e.g. if value was not given for the service, the merchant would typically be required to void the transaction.
You can only void transaction with valid liens. If the hold on a transaction is expired, you should refund the transaction.
post
https://api.flutterwave.com/v3/charges/:flw_ref/voidPath Params
string
This is a unique reference internally generated by Flutterwave. It is returned as data.flw_ref
in the charge response.
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call
require("../library/Preauth.php");
use Flutterwave\Preauth;
$payment = new Preauth();
$result = $payment->cardCharge($card);
$void = $payment->voidFunds(['flw_ref' => 'FLW-TYR67844']);//pass only flw_ref
echo "<pre>";
print_r($void);
echo "<pre>";
exit;
require './flutterwave_sdk'
payment = Flutterwave.new(ENV["PUBLIC_KEY"], ENV["SECRET_KEY"], ENV["ENCRYPTION_KEY"])
auth = Preauth.new(payment)
flw_ref = "FLW-TYR67844"
response = auth.void_preauth(flw_ref)
print response
{
"status": "success",
"message": "Charge voided",
"data": {
"id": 1191267,
"tx_ref": "MC-158523sd09v5050e8",
"flw_ref": "FLW-TYR67844",
"order_id": "USS_URG_89398292s3s2323",
"device_fingerprint": "62wd2342s3rq324323qew1",
"amount": 1500,
"charged_amount": 1500,
"app_fee": 1703,
"merchant_fee": 0,
"auth_model": "AUTH",
"currency": "XAF",
"ip": "154.123.220.1",
"narration": "Kizito Akhilome",
"status": "successful",
"processor_response": "Charge voided",
"payment_type": "mobilemoneysn",
"fraud_status": "ok",
"charge_type": "normal",
"created_at": "2020-03-27T14:54:50.000Z",
"account_id": 73362,
"customer": {
"id": 349061,
"phone_number": "054709929220",
"name": "John Madakin",
"email": "johnmadakin@gmail.com",
"created_at": "2020-03-27T09:12:54.000Z"
},
"card": {
"first_6digits": 553188,
"last_4digits": 2950,
"issuer": "MASTERCARD CREDIT",
"country": "NG",
"type": "MASTERCARD",
"expiry": "0/22"
}
}
}
{
"status": "error",
"message": "No PBTX transaction found",
"data": null
}
Create a refund
When creating a refund, you must assign it to a charge.
Refunding a transaction would return the charged amount for an existing, unrefunded transaction. Funds will be refunded to the debit or credit cards charged originally.
Partial refunds are supported. You can refund part of the transaction amount many times before until the initial transaction amount has been refunded.
Transactions can't be refunded once the initial amount has been fully refunded.
An attempt to refund part of a fully refunded transaction would return HTTP code 400
.
post
https://api.flutterwave.com/v3/charges/:flw_ref/refundPath Params
string
This is a unique reference internally generated by Flutterwave. It is returned as data.flw_ref
in the charge response.
Body Params
int32
This is the amount to be refunded.
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call
require("../library/Preauth.php");
use Flutterwave\Preauth;
$payment = new Preauth();
$result = $payment->cardCharge($card);
$refund = $payment->reFunds(['flw_ref' => 'FLW-MOCK-PREAUTH-72544a3c7659bcd74cc3a3110fe95101', 'amount' => 2000]);//pass flw_ref and amount
echo "<pre>";
print_r($refund);
echo "<pre>";
exit;
require './flutterwave_sdk'
payment = Flutterwave.new(ENV["PUBLIC_KEY"], ENV["SECRET_KEY"], ENV["ENCRYPTION_KEY"])
auth = Preauth.new(payment)
payload = {
"amount" => "30"
}
flw_ref = "FLW-MOCK-PREAUTH-72544a3c7659bcd74cc3a3110fe95101"
response = auth.refund_preauth(flw_ref, payload)
print response
{
"status": "success",
"message": "Charge refunded",
"data": {
"id": 1196959,
"tx_ref": "sampleRef135",
"flw_ref": "FLW-MOCK-PREAUTH-72544a3c7659bcd74cc3a3110fe95101",
"device_fingerprint": "N/A",
"amount": 10000,
"charged_amount": 10000,
"app_fee": 38,
"merchant_fee": 0,
"processor_response": "APPROVED",
"auth_model": "VBVSECURECODE",
"currency": "NGN",
"ip": "169.123.8.9",
"narration": "FLW-PBF CARD Transaction ",
"status": "successful",
"auth_url": "N/A",
"payment_type": "card",
"fraud_status": "ok",
"charge_type": "preauth",
"created_at": "2020-03-30T17:58:56.000Z",
"account_id": 73362,
"customer": {
"id": 347498,
"phone": "0902620185",
"fullName": "temi desola",
"customertoken": null,
"email": "user@gmail.com",
"createdAt": "2020-03-24T17:38:27.000Z",
"updatedAt": "2020-03-24T17:38:27.000Z",
"deletedAt": null,
"AccountId": 73362
},
"card": {
"first_6digits": "537728",
"last_4digits": "7450",
"issuer": "MASTERCARD JSB PROBUSINESSBANK CREDITGOLD",
"country": "RU",
"type": "MASTERCARD",
"expiry": "09/21"
}
}
}
{}