Have you ever integrated our payment API into your product? Help us improve the developer experience for you and everyone by taking this short survey, get started here

Preauthorisation

Introduction

Manage your preauth payments. Capture, void and refund transactions with our preauth APIs.

Create a Charge

Initiate pre-authorization card transactions.

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": "5377283645077450",
    "cvv": "789",
    "expiry_month": "09",
    "expiry_year": "31",
    "amount": "20000",
    "fullname": "John Doe",
    "tx_ref": "sample-ref",
    "currency": "NGN",
    "country": "NG",
    "email": "johndoe@gmail.com",
    "redirect_url":"https://www.flutterwave.com/ng/",
    "meta": {
      "values": "TESTX29",
      "random": "9988",
    },
    "preauthorize": true
  }

{
   "status":"success",
   "message":"Successful",
   "data":{
      "id":6591350,
      "tx_ref":"sample-ref",
      "flw_ref":"FLW-MOCK-PREAUTH-4f653c6c5db375d3fabdd9db773d4128",
      "device_fingerprint":"N/A",
      "amount":20000,
      "charged_amount":20000,
      "app_fee":760,
      "merchant_fee":0,
      "processor_response":"Approved. Successful",
      "auth_model":"VBVSECURECODE",
      "currency":"NGN",
      "ip":"52.209.154.143",
      "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-09-05T08:35:03.000Z",
      "account_id":1816498,
      "customer":{
         "id":2487736,
         "phone_number":null,
         "name":"John Doe",
         "email":"johndoe@gmail.com",
         "created_at":"2024-09-05T08:35:03.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
}

Capture a Charge

Capture funds for initiated pre-authorization payments.

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

Release hold (lien) on pre-authorized transactions.

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

Refund pre-authorization transactions.

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

{}
Loading...