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 helps verify that the customer's card is valid and that they have enough funds to cover the transaction before debiting.

In a preauth transaction, the customer is not debited for the transaction immediately. Instead, a lien for the transaction amount is placed on their account. This lien is valid for seven (7) days after which it is lifted. You are expected to capture the charge during this period.

For instance, if you run a ride-hailing service or hospitality business, you'd typically charge the customer after their trip or stay. However, you can estimate how much the trip or stay will cost and preauthorize the charge. This will "lock" the requested amount and you are sure the customer can pay their bill after rendering the service.

Payment flow

You can follow the steps below in order to complete a preauthorized charge.

  • Initiate a preauthorized charge.
  • Capture a preauthorized charge. Partially or fully capture the preauthorized charge.
  • Void a preauthorized charge. Can be manually triggered, but occurs automatically after 7 days if the charge is not captured.
  • Refund a preauthorized charge. You can optionally refund previously captured preauthorized charge amounts back to the customer.
  • 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.

Preauthorized transactions are usually processed via the NoAuth authorization model. You also have the option to authenticate the customer using 3DS. To do this, 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 successfully charge a customer using preauth. The encrypted data is then sent to initiate the charge. This secures the payment and protects you from any potential issues. Visit our encryption section to learn how to encrypt your requests for card charge.

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

In order to capture a preauthorized charge once, you should 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 allows merchants to capture a preauthorized charge multiple times. This approach helps you to capture the preauthorized amount more than once partially.

For instance, if you run a hospitality business, preauthorizing your customer’s card helps you to 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 1 month ago