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

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.

tx_ref string

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

currency string

This is the specified currency to charge in. Must be a supported currency

phone_number string

This is the phone number linked to the customer's Bank account or mobile money account

fullname string

This is the name of the customer making the payment.

preauthorize boolean

This should be set to true for preauthoize card transactions

redirect_url 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).

client_ip string

This represents the current IP address of the customer carrying out the transaction.

device_fingerprint string

This is the fingerprint for the device being used. It can be generated using a library on whatever platform is being used.

payment_plan string

This is the id of a previously created payment plan needed to add a card user to the payment plan.

meta object

This is used to include additional payment information.

flightID string

This could be the extra information you want to pass

sideNote string

This could be any message you'd like to associate with this call

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

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

{}

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

Body 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

{}

{}

{
    "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-void

Path Params

flw_ref string

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

Headers

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

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

Capture a PayPal Charge

Body Params

Headers

Void a PayPal Charge

Path Params

Headers