Skip to main content

Documentation

Reauthorizing a Card Payment

Extend the duration of a card authorization by creating a reauthorization payment. This process links a new payment to an existing active authorization, which resets the hold period. To extend the period again, link to the most recent payment in the chain.

When you reauthorize a payment, a new one is created, and the original payment is canceled. To capture funds later, you must use the ID of the most recent payment.

Examples of when to use this procedure:

  • Hospitality - A guest extends their hotel stay.

  • Rentals - A vehicle rental period is extended.

How

This procedure includes the following steps:

Create Initial Authorization

Create the first payment with capture set to false. The response returns a payment ID with status ACT (Active).

  1. Run Create Payment with the following parameters:

    • amount - The amount to hold.

    • capture - Set to false.

    • initiation_type - Set to customer_present (or relevant type).

      • Request

        • curl -X post 'https://sandboxapi.rapyd.net/v1/payments' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
    "amount": 360,
    "currency": "GBP",
    "description": "original payment",
    "statement_descriptor": "Four Star Hotel",
    "payment_method": {
        "type": "gb_visa_card",
        "fields": {
            "name": "Card Test",
            "number": "4921816852872867",
            "expiration_month": "05",
            "expiration_year": "28",
            "cvv": "184"
        }
    },
    "payment_method_options": {
        "3d_required": true
    },
    "capture": false,
    "save_payment_method": true,
    "complete_payment_url": "https://complete.rapyd.net",
    "error_payment_url": "https://error.rapyd.net"
}'

      • Response

        • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "e913166f-89bf-435c-a391-5b1f122081b3"
    },
    "data": {
        "id": "payment_888ab1012d71b951bea51db15ebb923c",
        "amount": 0,
        "original_amount": 360,
        "is_partial": false,
        "currency_code": "GBP",
        "country_code": "GB",
        "status": "ACT",
        "description": "original payment",
        "merchant_reference_id": "",
        "customer_token": "cus_0920518332848660f421f064756c0173",
        "payment_method": null,
        "payment_method_data": {
            "id": null,
            "type": "gb_visa_card",
            "category": "card",
            "metadata": null,
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "3d_verification",
            "name": "Card Test",
            "last4": "2867",
            "acs_check": "unchecked",
            "cvv_check": "unchecked",
            "bin_details": {
                "type": "DEBIT",
                "brand": "VISA",
                "level": "CLASSIC",
                "issuer": "LLOYDS BANK PLC",
                "country": "GB",
                "bin_number": "492181"
            },
            "expiration_year": "28",
            "expiration_month": "05",
            "fingerprint_token": "ocfp_cb32cd6ab1a353fdbd27e91eca6d8e0c"
        },
        "auth_code": null,
        "expiration": 1773233060,
        "captured": false,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "https://qacheckout.rapyd.net/3ds/challenge.html?redirection_data=%7B%22creq",
        "complete_payment_url": "https://complete.rapyd.net",
        "error_payment_url": "https://error.rapyd.net",
        "receipt_number": "",
        "flow_type": "",
        "address": null,
        "statement_descriptor": "Four Star Hotel",
        "transaction_id": "",
        "created_at": 1772628260,
        "metadata": {},
        "failure_code": "",
        "failure_message": "",
        "paid": false,
        "paid_at": 0,
        "dispute": null,
        "refunds": null,
        "order": null,
        "outcome": null,
        "visual_codes": {},
        "textual_codes": {},
        "instructions": [],
        "ewallet_id": "ewallet_6f288d7c178f545ebb56be8990ff0ff2",
        "ewallets": [
            {
                "ewallet_id": "ewallet_6f288d7c178f545ebb56be8990ff0ff2",
                "amount": 360,
                "percent": 100,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {
            "3d_required": true
        },
        "payment_method_type": "gb_visa_card",
        "payment_method_type_category": "card",
        "fx_rate": 1,
        "merchant_requested_currency": null,
        "merchant_requested_amount": null,
        "fixed_side": "",
        "payment_fees": null,
        "invoice": "",
        "escrow": null,
        "group_payment": "",
        "cancel_reason": null,
        "initiation_type": "customer_present",
        "mid": "mid_a1fac8e583533d2c746da93733eed20d",
        "next_action": "3d_verification",
        "error_code": "",
        "remitter_information": {},
        "save_payment_method": true,
        "merchant_advice_code": null,
        "merchant_advice_message": null,
        "enhanced_data": null,
        "payment_request_id": null,
        "authentication_result": {
            "eci": null,
            "result": "R",
            "version": "2.2.0",
            "cardholder_info": null
        },
        "transaction_link_id": null
    }
}
Create Reauthorization Payment

To extend the hold, create a new payment that references the original one. This step creates a new payment ID. The previous payment must be in active status (ACT).

  1. Run Create Payment again with the following parameters:

    • amount - The amount to hold. Must be less than or equal to the original amount.

    • original_payment - The ID of the payment from the previous step (in this example, the ID is payment_a3517c959cdde762b1f4b6ad815823c4).

    • initiation_type - Set to reauthorization.

    • capture - Set to false.

      • Request

        • curl -X post 'https://sandboxapi.rapyd.net/v1/payments' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
    "amount": 200,
    "currency": "GBP",
    "description": "reauthorization payment",
    "capture": false,
    "original_payment": "payment_888ab1012d71b951bea51db15ebb923c",
    "initiation_type": "reauthorization",
    "payment_method": {
        "type": "gb_visa_card",
        "fields": {
            "name": "Card Test",
            "number": "4921816852872867",
            "expiration_month": "05",
            "expiration_year": "28",
            "cvv": "184"
        }
    },
    "complete_payment_url": "https://complete.rapyd.net",
    "error_payment_url": "https://error.rapyd.net"
}'

      • Response

        • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "d0531fe3-4816-467a-a6c0-37e1de27cc7c"
    },
    "data": {
        "id": "payment_8a6661833e2a6a8d0b30642fe56ddd7d",
        "amount": 0,
        "original_amount": 200,
        "is_partial": false,
        "currency_code": "GBP",
        "country_code": "GB",
        "status": "ACT",
        "description": "reauthorization payment",
        "merchant_reference_id": "",
        "customer_token": "cus_8934219c9839a37c4f825f4285ce6522",
        "payment_method": null,
        "payment_method_data": {
            "id": null,
            "type": "gb_visa_card",
            "category": "card",
            "metadata": null,
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "not_applicable",
            "name": "Card Test",
            "last4": "2867",
            "acs_check": "unchecked",
            "cvv_check": "unchecked",
            "bin_details": {
                "type": "DEBIT",
                "brand": "VISA",
                "level": "CLASSIC",
                "issuer": "LLOYDS BANK PLC",
                "country": "GB",
                "bin_number": "492181"
            },
            "expiration_year": "28",
            "expiration_month": "05",
            "fingerprint_token": "ocfp_cb32cd6ab1a353fdbd27e91eca6d8e0c",
            "network_reference_id": "000000174207254",
            "payment_account_reference": "V0010012427441491861593156464"
        },
        "auth_code": "121549",
        "expiration": 1773187200,
        "captured": false,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "",
        "complete_payment_url": "https://complete.rapyd.net",
        "error_payment_url": "https://error.rapyd.net",
        "receipt_number": "",
        "flow_type": "",
        "address": null,
        "statement_descriptor": "Four Star Hotel",
        "transaction_id": "",
        "created_at": 1772628315,
        "metadata": {},
        "failure_code": "",
        "failure_message": "",
        "paid": false,
        "paid_at": 0,
        "dispute": null,
        "refunds": null,
        "order": null,
        "outcome": null,
        "visual_codes": {},
        "textual_codes": {},
        "instructions": [],
        "ewallet_id": "ewallet_6f288d7c178f545ebb56be8990ff0ff2",
        "ewallets": [
            {
                "ewallet_id": "ewallet_6f288d7c178f545ebb56be8990ff0ff2",
                "amount": 200,
                "percent": 100,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {},
        "payment_method_type": "gb_visa_card",
        "payment_method_type_category": "card",
        "fx_rate": 1,
        "merchant_requested_currency": null,
        "merchant_requested_amount": null,
        "fixed_side": "",
        "payment_fees": null,
        "invoice": "",
        "escrow": null,
        "group_payment": "",
        "cancel_reason": null,
        "initiation_type": "reauthorization",
        "mid": "mid_a1fac8e583533d2c746da93733eed20d",
        "next_action": "pending_capture",
        "error_code": "",
        "remitter_information": {},
        "save_payment_method": false,
        "merchant_advice_code": null,
        "merchant_advice_message": null,
        "enhanced_data": null,
        "payment_request_id": null,
        "transaction_link_id": null,
        "original_payment": "payment_888ab1012d71b951bea51db15ebb923c"
    }
}
Inspect Webhooks

When the reauthorization is successful, Rapyd triggers specific webhooks to indicate the change in status for both the old and new payments. See List Webhooks.

Confirm that the following events occurred:

  • Original Payment - The system cancels the payment used in the original_payment field. Returns the PAYMENT_CANCELED webhook.

  • New Payment - A new payment is created with status ACT and a new expiration timestamp. Returns the PAYMENT_SUCCEEDED webhook.

    • PAYMENT_CANCELED

      • {
    id: "wh_8300364cfd3fe50a959c5a67f34c39d9",
    type: "PAYMENT_CANCELED",
    data: {
        id: "payment_888ab1012d71b951bea51db15ebb923c",
        amount: 0,
        original_amount: 360,
        is_partial: false,
        currency_code: "GBP",
        country_code: "GB",
        status: "CAN",
        description: "original payment",
        merchant_reference_id: "",
        customer_token: "cus_0920518332848660f421f064756c0173",
        payment_method: "card_b7f683e35fa0c90d3f8cafc06000f964",
        payment_method_data: {
            cvv_check: "fail",
            acs_check: "pass"
        },
        auth_code: "203958",
        expiration: 1773187200,
        captured: false,
        refunded: false,
        refunded_amount: 0,
        receipt_email: "",
        redirect_url: "https://qacheckout.rapyd.net/3ds/challenge.html?redirection_data=%7B%22creq%22%3A%22ey",
        complete_payment_url: "https://complete.rapyd.net",
        error_payment_url: "https://error.rapyd.net",
        receipt_number: "",
        flow_type: "",
        address: null,
        statement_descriptor: "Four Star Hotel",
        transaction_id: "",
        created_at: 1772628260,
        metadata: {},
        failure_code: "",
        failure_message: "",
        paid: false,
        paid_at: 0,
        dispute: null,
        refunds: null,
        order: null,
        outcome: null,
        visual_codes: {},
        textual_codes: {},
        instructions: [],
        ewallet_id: "ewallet_6f288d7c178f545ebb56be8990ff0ff2",
        ewallets:
        [
            {
                ewallet_id: "ewallet_6f288d7c178f545ebb56be8990ff0ff2",
                amount: 360,
                percent: 100,
                refunded_amount: 0,
            },
        ],
        payment_method_options: {
            "3d_required": true
        },
        payment_method_type: "gb_visa_card",
        payment_method_type_category: "card",
        fx_rate: 1,
        merchant_requested_currency: null,
        merchant_requested_amount: null,
        fixed_side: "",
        payment_fees: null,
        invoice: "",
        escrow: null,
        group_payment: "",
        cancel_reason: "Reauthorized",
        initiation_type: "customer_present",
        mid: "mid_a1fac8e583533d2c746da93733eed20d",
        next_action: "not_applicable",
        error_code: "",
        remitter_information: {},
        save_payment_method: true,
        merchant_advice_code: null,
        merchant_advice_message: null,
        enhanced_data: null,
        payment_request_id: null,
        authentication_result: {
            eci: "05",
            result: "A",
            version: "2.2.0",
            cardholder_info: null,
        },
        transaction_link_id: null,
    },
    trigger_operation_id: "d0531fe3-4816-467a-a6c0-37e1de27cc7c",
    status: "NEW",
    created_at: 1772628317,
    extended_timestamp: 1772628317672
}

    • PAYMENT_SUCCEEDED

      • {
    id: "wh_7b8156ec35cc8ef87c10c3a880c1d6bf",
    type: "PAYMENT_SUCCEEDED",
    data: {
        id: "payment_8a6661833e2a6a8d0b30642fe56ddd7d",
        amount: 0,
        original_amount: 200,
        is_partial: false,
        currency_code: "GBP",
        country_code: "GB",
        status: "ACT",
        description: "reauthorization payment",
        merchant_reference_id: "",
        customer_token: "cus_8934219c9839a37c4f825f4285ce6522",
        payment_method: null,
        payment_method_data: {
            id: null,
            type: "gb_visa_card",
            category: "card",
            metadata: null,
            image: "",
            webhook_url: "",
            supporting_documentation: "",
            next_action: "not_applicable",
            name: "Card Test",
            last4: "2867",
            acs_check: "unchecked",
            cvv_check: "unchecked",
            bin_details: {
                type: "DEBIT",
                brand: "VISA",
                level: "CLASSIC",
                issuer: "LLOYDS BANK PLC",
                country: "GB",
                bin_number: "492181"
            },
            expiration_year: "28",
            expiration_month: "05",
            fingerprint_token: "ocfp_cb32cd6ab1a353fdbd27e91eca6d8e0c",
            network_reference_id: "000000174207254",
            payment_account_reference: "V0010012427441491861593156464"
        },
        auth_code: "121549",
        expiration: 1773187200,
        captured: false,
        refunded: false,
        refunded_amount: 0,
        receipt_email: "",
        redirect_url: "",
        complete_payment_url: "https://complete.rapyd.net",
        error_payment_url: "https://error.rapyd.net",
        receipt_number: "",
        flow_type: "",
        address: null,
        statement_descriptor: "Four Star Hotel",
        transaction_id: "",
        created_at: 1772628315,
        metadata: {},
        failure_code: "",
        failure_message: "",
        paid: false,
        paid_at: 0,
        dispute: null,
        refunds: null,
        order: null,
        outcome: null,
        visual_codes: {},
        textual_codes: {},
        instructions: [],
        ewallet_id: "ewallet_6f288d7c178f545ebb56be8990ff0ff2",
        ewallets: [
            {
                ewallet_id: "ewallet_6f288d7c178f545ebb56be8990ff0ff2",
                amount: 200,
                percent: 100,
                refunded_amount: 0
            }
        ],
        payment_method_options: {},
        payment_method_type: "gb_visa_card",
        payment_method_type_category: "card",
        fx_rate: 1,
        merchant_requested_currency: null,
        merchant_requested_amount: null,
        fixed_side: "",
        payment_fees: null,
        invoice: "",
        escrow: null,
        group_payment: "",
        cancel_reason: null,
        initiation_type: "reauthorization",
        mid: "mid_a1fac8e583533d2c746da93733eed20d",
        next_action: "pending_capture",
        error_code: "",
        remitter_information: {},
        save_payment_method: false,
        merchant_advice_code: null,
        merchant_advice_message: null,
        enhanced_data: null,
        payment_request_id: null,
        transaction_link_id: null,
        original_payment: "payment_888ab1012d71b951bea51db15ebb923c"
    },
    trigger_operation_id: "d0531fe3-4816-467a-a6c0-37e1de27cc7c",
    status: "NEW",
    created_at: 1772628318,
    extended_timestamp: 1772628318290
}
Related Error Messages

Error Code

Description

ERROR_CAPTURE_TRUE_FOR_REAUTHORIZING_CARD_PAYMENT

The request tried to reauthorize a card payment , but the ‘capture’ field is set to true. The request was rejected. Corrective action: Rerun the request with the ‘capture’ field set to false.

ERROR_REAUTHORIZING_CANCELED_CARD_PAYMENT

The request tried to reauthorize a card payment, but the original payment was canceled. The request was rejected. Corrective action: None.

ERROR_REAUTHORIZING_CLOSED_PAYMENT

The request tried to update a payment to extend the existing authorization, but the payment was already closed. Corrective action: Create a new payment.

ERROR_CREATE_PAYMENT_FOR_REAUTHORIZATION

The request tried to reauthorize a card payment, but a processing issue occurred. The request was rejected. Corrective action: Rerun the request. If the error persists, contact Rapyd Client Support.

In this section: