Preauthorisation
Introduction
The Preauthorize APIs allow Developers to manage preauth attempts on Card and PayPal transactions. You can capture, void or refund preauth transactions.
Related guide: Understanding Preauthorization
Create a Charge
When you create a preauth charge, you must apply this to either a Card
or Pay_with_PayPal
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
This is the email address of the customer. 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.
string
This is the specified currency to charge in. Must be a supported currency
string
This is the phone number linked to the customer's Bank account or mobile money account
string
This is the name of the customer making the payment.
boolean
This should be set to true for preauthoize card transactions
string
This is a url you provide, we redirect to it after the customer completes payment and append the response to it as query parameters. (3DSecure only).
string
This represents the current IP address of the customer carrying out the transaction.
string
This is the fingerprint for the device being used. It can be generated using a library on whatever platform is being used.
string
This is the id of a previously created payment plan needed to add a card user to the payment plan.
object
This is used to include additional payment information.
string
This could be the extra information you want to pass
string
This could be any message you'd like to associate with this call
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
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": "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": 2113235,
"tx_ref": "sampleRef134",
"flw_ref": "FLW-MOCK-PREAUTH-72544a3c7659bcd74cc3a3110fe95101",
"device_fingerprint": "N/A",
"amount": 1000,
"charged_amount": 1000,
"app_fee": 38,
"merchant_fee": 0,
"processor_response": "Approved",
"auth_model": "NOAUTH",
"currency": "NGN",
"ip": "::ffff:10.101.182.164",
"narration": "FLW-PBF CARD Transaction ",
"status": "successful",
"auth_url": "N/A",
"payment_type": "card",
"plan": null,
"fraud_status": "ok",
"charge_type": "preauth",
"created_at": "2021-05-14T21:36:15.000Z",
"account_id": 20937,
"customer": {
"id": 870254,
"phone_number": null,
"name": "Cornelius Ashley",
"email": "cornelius@flutter.com",
"created_at": "2021-05-14T21:36:15.000Z"
},
"card": {
"first_6digits": "537728",
"last_4digits": "7450",
"issuer": "MASTERCARD JSB PROBUSINESSBANK CREDITGOLD",
"country": "RU",
"type": "MASTERCARD",
"expiry": "09/31"
}
}
}
{}
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"
}
}
}
{}
Capture a PayPal Charge
Capture the payment of a previously uncaptured PayPal charge. Like Card charge capture, This is also the second leg of a two-part flow.
Supply the flw_ref returned from your initial PayPal charge attempt and Flutterwave captures the funds for the corresponding transaction.
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/paypal-captureBody 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
{}
{}
{
"status": "success",
"message": "Charge captured",
"data": {
"id": 1882861,
"tx_ref": "test-ref-123456001",
"flw_ref": "FLWT001341851",
"device_fingerprint": "62wd23423rq324323qew1",
"amount": 10,
"charged_amount": 10,
"app_fee": 0,
"merchant_fee": 0,
"processor_response": "Transaction Successful",
"auth_model": "PAYPAL",
"currency": "ZAR",
"ip": "::ffff:10.69.244.94",
"narration": "anjola sandbox",
"status": "successful",
"auth_url": "N/A",
"payment_type": "paypal",
"fraud_status": "ok",
"charge_type": "preauth",
"created_at": "2021-02-03T08:01:53.000Z",
"account_id": 7813,
"customer": {
"id": 562419,
"phone_number": "054222234847",
"name": "John Madakin",
"email": "dovedom221@vss6.com",
"created_at": "2021-01-11T15:08:34.000Z"
}
}
}
{}
Void a PayPal Charge
This allows the merchant to release the hold on the PayPal funds i.e. if value was not given for the service, the merchant would typically be required to void the transaction.
post
https://api.flutterwave.com/v3/charges/paypal-voidPath Params
string
This is the data.flw_ref
returned in the charge response.
Headers
string
Pass your secret key as a bearer token in the request header to authorize this call
{}
{}
{{
"status": "success",
"message": "Charge voided",
"data": {
"id": 1886093,
"tx_ref": "payPalv3Test04",
"flw_ref": "FLWT001342132",
"device_fingerprint": "62wd23423rq324323qew1",
"amount": 10,
"charged_amount": 10,
"app_fee": 0,
"merchant_fee": 0,
"processor_response": "Approved",
"auth_model": "PAYPAL",
"currency": "USD",
"ip": "::ffff:10.91.151.49",
"narration": "anjola sandbox",
"status": "voided",
"auth_url": "https://www.sandbox.paypal.com/checkoutnow?token=0AL13991YL864625V",
"payment_type": "paypal",
"fraud_status": "ok",
"charge_type": "preauth",
"created_at": "2021-02-04T13:13:56.000Z",
"account_id": 7813,
"customer": {
"id": 562419,
"phone_number": "054222234847",
"name": "John Madakin",
"email": "dovedom221@vss6.com",
"created_at": "2021-01-11T15:08:34.000Z"
}
}
}
{
"status": "error",
"message": "No PBTX transaction found",
"data": null
}