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=card

Body Params

amount int32

This is the amount to be charged for the transaction.

card_number int32

This is the number on the cardholders card. Sample cards can be used to mock transactions.

cvv int32

Card security code. This is 3/4 digit code at the back of the customers card, used for web payments.

expiry_month int32

Two-digit number representing the card's expiration month.

expiry_year int32

Two-digit number representing the card's expiration year.

email 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.

tx_ref string

This is a unique reference peculiar to the transaction being carried out.

preauthorize boolean

This should be set to true for preauthoize card transactions

authorization 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`

mode string

This is the auth model of the card to use when validating, it is returned in the initiate charge call as authorization.mode

pin int32

This is the card's pin. Required when the suggested auth mode is PIN

city string

This is the city in the card's billing details. It is required when the suggested auth mode is avs_noauth

address string

This is the cards billing address. It is required when the suggested auth mode is avs_noauth

state string

This is the card issuing state. It is required when the suggested auth mode is avs_noauth

country string

This is the cards issuing country. It is required when the suggested auth mode is avs_noauth

zipcode int32

This is cards billing address zipcod. It is required when the suggested auth mode is avs_noauth

Show optional parameters

Headers

Authorization 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
}

Secure Preauthorize charge

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/capture

Path Params

flw_ref string

This is the data.flw_ref returned in the charge response.

Body Params

amount 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

Authorization 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/void

Path Params

flw_ref string

This is a unique reference internally generated by Flutterwave. It is returned as data.flw_ref in the charge response.

Headers

Authorization 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/refund

Path Params

flw_ref string

This is a unique reference internally generated by Flutterwave. It is returned as data.flw_ref in the charge response.

Body Params

amount int32

This is the amount to be refunded.

Headers

Authorization 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"
    }
  }
}

{}

Preauthorization

API Reference

Endpoints

Preauthorisation

Introduction

Create a Charge

Body Params

Headers

Capture a Charge

Path Params

Body Params

Headers

Void a Charge

Path Params

Headers

Create a refund

Path Params

Body Params

Headers