DocumentationRecipesAPI ReferencesSupportBlog
Documentation

Preauthorization

Learn about the preauthorized card charge.

Suggest Edits

ℹ️

Approval Required

Preauthorization is not available by default on your account. To request access to this feature, please contact our support team via [email protected].

Preauthorization (also referred to as preauth) involves placing a temporary hold on a specific amount when charging a customer's card. This hold ensures that the card is valid and that the customer has sufficient funds before the actual charge is captured.

In a preauth transaction, the customer is not charged immediately. Instead, a lien is placed on the transaction amount, reserving the funds on their account. This lien is valid for seven (7) days, after which it is automatically released if not captured. You are expected to capture the charge within this window.

For example, if you run a ride-hailing service or hospitality business, you typically charge the customer after their trip or stay. However, by estimating the cost upfront and preauthorizing the charge, you can place a hold on the expected amount. This ensures the customer has sufficient funds and helps guarantee payment once the service is completed.

Payment Flow

To complete a preauthorized charge, follow these steps:

  1. Initiate a preauthorized charge.
  2. Capture a preauthorized charge. Partially or fully capture the preauthorized charge.
  3. Void a preauthorized charge. It can be manually triggered, but it occurs automatically after 7 days if the charge is not captured.
  4. Refund a preauthorized charge. Optionally refund previously captured preauthorized charge amounts back to the customer.
  5. Enable webhooks to receive real-time updates on preauthorization events (e.g., the final status after a preauthorized charge has been captured).

Initiating a Preauthorized Charge

To preauthorize a card, include the preauthorize parameter in your request when initiating a card payment. This parameter should be added with other required fields for a direct card charge.

By default, preauthorized transactions are processed via the NoAuth authorization model. To require additional customer authentication (e.g., 3DS), set the usesecureauth parameter to true in your charge request.

{
  "preauthorize": true,// initiates a preauthorized charge
  "usesecureauth": true,// set to true if you want to authorize the card payment with 3DS, set to false to charge with NoAuth
  "card_number": "5377283645077450",
  "expiry_month": "09",
  "expiry_year": "31",
  "cvv": "789",
  "currency": "NGN",
  "amount": "7500",
  "email": "[email protected]",
  "fullname": "John Doe",
  "phone_number": "+2349012345678",
  "tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
  "redirect_url": "https://example_company.com/success"
}

You need to encrypt your request payload to charge a customer using preauthorization successfully. The encrypted data is then sent to initiate the charge. This helps secure the payment and prevents potential fraud or misuse. Visit our encryption section to learn how to encrypt your requests for card charges.

curl --request POST \
  --url https://api.flutterwave.com/v3/charges?type=card \
  --header 'Authorization: Bearer {{FLW_SECRET_KEY}}' \
  --header 'content-type: application/json' \
  --data '{ "client": "Of8p6iJUVUezgvjUkjjJsP8aPd6CjHR3f9ptHiH5Q0+2h/FzHA/X1zPlDmRmH5v+GoLWWB4TqEojrKhZI38MSjbGm3DC8UPf385zBYEHZdgvQDsacDYZtFEruJqEWXmbvw9sUz+YwUHegTSogQdnXp7OGdUxPngiv6592YoL0YXa4eHcH1fRGjAimdqucGJPurFVu4sE5gJIEmBCXdESVqNPG72PwdRPfAINT9x1bXemI1M3bBdydtWvAx58ZE4fcOtWkD/IDi+o8K7qpmzgUR8YUbgZ71yi0pg5UmrT4YpcY2eq5i46Gg3L+fxFl4tauG9H4WBChF0agXtP4kjfhfYVD48N9Hrt"}'

When you successfully initiate a preauthorized charge, the transaction amount is placed on lien (i.e., a hold is placed on the customer’s account for the transaction amount).

{
    "status": "success",
    "message": "Successful",
    "data": {
        "id": 7518573,
        "tx_ref": "UNIQUE_TRANSACTION_REFERENCE_001",
        "flw_ref": "FLW-MOCK-PREAUTH-78ac51471cce114d788d9ccedd2d03dc",
        "device_fingerprint": "N/A",
        "amount": 7500,
        "charged_amount": 7500,
        "app_fee": 285,
        "merchant_fee": 0,
        "processor_response": "Approved. Successful",
        "auth_model": "NOAUTH",
        "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-10-15T13:48:31.000Z",
        "account_id": 20937,
        "customer": {
            "id": 2509582,
            "phone_number": "+2349012345678",
            "name": "Flutterwave Developers",
            "email": "[email protected]",
            "created_at": "2024-10-08T19:45:17.000Z"
        },
        "card": {
            "first_6digits": "537728",
            "last_4digits": "7450",
            "issuer": "MASTERCARD JSB PROBUSINESSBANK CREDITGOLD",
            "country": "RU",
            "type": "MASTERCARD",
            "expiry": "09/31"
        }
    }
}

This means that the card isn’t debited yet, but the customer can not use the "locked" funds. When you are ready to charge the customer, you can capture the funds using the capture preauthorized charge endpoint.

Capturing a Preauthorized Charge

Capturing the transaction means that you are debiting the customer for that payment. There are two supported models for capturing transactions:

  • Single Capture: Using this method, you capture the full value of the transaction. This can only be done once.
  • Multiple Capture: This method allows you to make smaller captures for the transaction many times. For example, if you have a pending preauth charge of N100, you can choose to capture N20, N70 and N10 on three different occasions, thus spreading out the funds capture.

Single Capture

To capture a preauthorized charge once, specify the amount equal to the initial preauthorized amount, along with the reference of the transaction. This information is sent to the capture preauthorized charge endpoint.

curl --request POST \
  --url https://api.flutterwave.com/v3/charges/:flw_ref/capture \
  --header 'Authorization: Bearer {{FLW_SECRET_KEY}}' \
  --header 'content-type: application/json' \
  --data '{ "amount": 7500 }'

{
    "status": "success",
    "message": "Charge captured",
    "data": {
        "id": 7567142,
        "tx_ref": "UNIQUE_TRANSACTION_REFERENCE_001",
        "flw_ref": "FLW-MOCK-PREAUTH-7a1ec8514cc5af5f96c8ba8edce58174",
        "device_fingerprint": "N/A",
        "amount": 7500,
        "charged_amount": 7500,
        "app_fee": 285,
        "merchant_fee": 0,
        "processor_response": "Approved",
        "auth_model": "VBVSECURECODE",
        "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-10-16T10:48:05.000Z",
        "account_id": 1816498,
        "customer": {
            "id": 2476403,
            "phone_number": "+2349012345678",
            "name": "Flutterwave Developers",
            "email": "[email protected]",
            "created_at": "2024-08-20T10:49:52.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-7a1ec8514cc5af5f96c8ba8edce58170 either does not exist or is not a valid preauth transaction",
    "data": null
}

Multiple Capture

Flutterwave supports multiple partial captures for a single preauthorized charge.

For instance, if you run a hospitality business, preauthorizing your customers’ cards helps you manage risks related to potential damages. You can charge a partial amount at check-in and debit the remainder when they check out. By capturing the transaction several times, you ensure flexible billing and prevent unexpected costs.

To partially capture a preauthorized charge, you must specify the amount you wish to capture along with the preauthorization reference for the transaction.

ℹ️

Multiple Capture Total Amount

The total captured amount after multiple partial captures must be less than or equal to the initial preauthorized amount.

curl --request POST \
  --url https://api.flutterwave.com/v3/charges/:flw_ref/capture \
  --header 'Authorization: Bearer {{FLW_SECRET_KEY}}' \
  --header 'content-type: application/json' \
  --data '{ "amount": 1000 }'

{
    "status": "success",
    "message": "Charge captured",
    "data": {
        "id": 6546262,
        "tx_ref": "testing-preauth_00122",
        "flw_ref": "FLW-MOCK-PREAUTH-af0a27db1299ad1ab4ecdca146fcf1a3",
        "device_fingerprint": "N/A",
        "amount": 1000,
        "charged_amount": 1000,
        "app_fee": 38,
        "merchant_fee": 0,
        "processor_response": "Approved",
        "auth_model": "VBVSECURECODE",
        "currency": "NGN",
        "ip": "52.209.154.143",
        "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-08-16T12:40:12.000Z",
        "account_id": 1816498,
        "customer": {
            "id": 2474218,
            "phone_number": null,
            "name": "Adekunle Odujoko",
            "email": "[email protected]",
            "created_at": "2024-08-16T12:40:12.000Z"
        },
        "card": {
            "first_6digits": "537728",
            "last_4digits": "7450",
            "issuer": "MASTERCARD JSB PROBUSINESSBANK CREDITGOLD",
            "country": "RU",
            "type": "MASTERCARD",
            "expiry": "09/31"
        }
    }
}

{
    "status": "error",
    "message": "Total amount for multiple captures must not exceed preauth charged amount.",
    "data": null
}

Voiding a Preauthorized Charge

Flutterwave allows you to release the hold on a preauthorized transaction before it is captured by voiding the transaction. Once a preauthorized transaction is voided, it can no longer be captured. Any preauthorized transaction that isn't captured within 7 days of initiation will be automatically voided.

To void a preauthorized charge, simply provide the transaction reference and send a request to the void preauthorized charge endpoint.

curl --request POST \
  --url https://api.flutterwave.com/v3/charges/:flw_ref/void \
  --header 'Authorization: Bearer {{FLW_SECRET_KEY}}' \
  --header 'content-type: application/json' \

Refunding a Preauthorized Charge

A captured preauthorized transaction can also be refunded. To initiate a refund, specify the amount to be refunded along with the reference of the captured charge, and send the request to the refund preauthorized charge endpoint.

curl --request POST \
  --url https://api.flutterwave.com/v3/charges/:flw_ref/refund \
  --header 'Authorization: Bearer {{FLW_SECRET_KEY}}' \
  --header 'content-type: application/json' \
  --data '{ "amount": 5000 }'

Enable Webhooks for Real-Time Updates on Preauthorization Events

If you have webhooks enabled on your dashboard, we will send the charge details, along with the status of the transaction, to the webhook URL specified. Webhook events will be sent after every successful capture and preauthorization request. 

{
  "event": "preauth-card",
  "data": {
    "id": 6601831,
    "tx_ref": "sample-ref",
    "flw_ref": "FLW-MOCK-PREAUTH-d19e956c6573e341f793a4dccbe98058",
    "device_fingerprint": "N/A",
    "amount": 3000,
    "currency": "NGN",
    "charged_amount": 3000,
    "app_fee": 114,
    "merchant_fee": 0,
    "processor_response": "Approved. Successful",
    "auth_model": "VBVSECURECODE",
    "ip": "54.75.161.64",
    "narration": "FLW-PBF CARD Transaction ",
    "status": "pending-capture",
    "payment_type": "card",
    "created_at": "2024-09-10T11:08:50.000Z",
    "account_id": 1816498,
    "customer": {
      "id": 2491034,
      "name": "Flutterwave Developers",
      "phone_number": null,
      "email": "[email protected]",
      "created_at": "2024-09-10T11:08:50.000Z"
    },
    "card": {
      "first_6digits": "537728",
      "last_4digits": "7450",
      "issuer": "MASTERCARD JSB PROBUSINESSBANK CREDITGOLD",
      "country": "RU",
      "type": "MASTERCARD",
      "expiry": "09/31"
    }
  },
  "event.type": "CARD_TRANSACTION"
}

{
  "event": "charge.completed",
  "data": {
    "id": 6601831,
    "tx_ref": "sample-ref",
    "flw_ref": "FLW-MOCK-PREAUTH-d19e956c6573e341f793a4dccbe98058",
    "device_fingerprint": "N/A",
    "amount": 2000,
    "currency": "NGN",
    "charged_amount": 2000,
    "app_fee": 76,
    "merchant_fee": 0,
    "processor_response": "Approved",
    "auth_model": "VBVSECURECODE",
    "ip": "54.75.161.64",
    "narration": "FLW-PBF CARD Transaction ",
    "status": "successful",
    "payment_type": "card",
    "created_at": "2024-09-10T11:08:50.000Z",
    "account_id": 1816498,
    "customer": {
      "id": 2491034,
      "name": "Flutterwave Developers",
      "phone_number": null,
      "email": "[email protected]",
      "created_at": "2024-09-10T11:08:50.000Z"
    },
    "card": {
      "first_6digits": "537728",
      "last_4digits": "7450",
      "issuer": "MASTERCARD JSB PROBUSINESSBANK CREDITGOLD",
      "country": "RU",
      "type": "MASTERCARD",
      "expiry": "09/31"
    }
  },
  "event.type": "CARD_TRANSACTION"
}

Updated about 18 hours ago