Skip to main content

Documentation

Incremental Authorizations for Card Payments

A merchant can use an incremental authorization for a customer-initiated card payment.

Use Create Payment for the transaction. Under the payment_method_options object in the request body, set the is_adjustable field to true. This will initiate a preauthorization for the card payment.

The merchant needs to be configured to be able to create adjustable payments.

If the final amount is higher, then an Update Payment request will need to be made. This is only possible if is_adjustable is set to true and capture is set to false. Then capture the final amount.

Card Payments Workflow

Create a card payment and then use an incremental authorization by updating the payment with an increased amount.

Step 1: Creating a Card Payment
incremental-authorization-flow-1.png

  1. The customer completes the card payment in checkout on your website.

  2. The third-party token provider requests a network token.

  3. You request Rapyd to process the card payment using a network token.

  4. Rapyd processes the payment and sends the response and webhook back to you.

  5. You display your purchase success page to the customer.

Step 2: Increasing the Payment Amount
incremental-authorization-flow-2.png

  1. You use Update Payment for the original payment.

  2. You request Rapyd update the card payment with an increased amount.

  3. Rapyd processes the payment and sends the response and webhook back to you.

PCI Certification

Only clients with PCI-DSS certification can handle personal identifying information for cards. This method is available to merchants who have signed a special agreement with Rapyd.

How Incremental Authorizations Work
Create a Card Payment

Use Create Payment to create a card payment.

Create Payment Request

    • Request

      • // Request URL: POST https://sandboxapi.rapyd.net/v1/payments

// Message body: 

{
    "amount": 100,
    "currency": "GBP",
    "description": "testing preauth for another merchant",
    "enhanced_data": {},
    "payment_method": {
        "type": "gb_visa_card",
        "fields": {
            "name": "Card Test",
            "number": "4176660000000100",
            "expiration_month": "01",
            "expiration_year": "29",
            "cvv": "123"
        }
    },
    "payment_method_options": {
        "is_adjustable": true
    },
    "capture": false,
    "save_payment_method": true,
    "complete_payment_url": "https://www.yahoo.com",
    "error_payment_url": "https://www.lego.com"
}
Create Payment Response

    • Response

      • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "fbb3f728-05cd-4ec1-9e5e-7ce6b2cdd2b4"
    },
    "data": {
        "id": "payment_fb3f486eaf16c1d3e0c7c1b1bba85b22",
        "amount": 0,
        "original_amount": 100,
        "is_partial": false,
        "currency_code": "GBP",
        "country_code": "GB",
        "status": "ACT",
        "description": "testing preauth for another merchant",
        "merchant_reference_id": "",
        "customer_token": "cus_9cb668a06820dfad16560fcb7d66bf8b",
        "payment_method": "card_2926398a8aa1df155399e837db4cc124",
        "payment_method_data": {
            "id": "card_2926398a8aa1df155399e837db4cc124",
            "type": "gb_visa_card",
            "category": "card",
            "metadata": null,
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "not_applicable",
            "name": "Card Test",
            "last4": "0100",
            "acs_check": "pass",
            "cvv_check": "pass",
            "bin_details": {
                "type": "CREDIT",
                "brand": "VISA",
                "level": "CLASSIC",
                "issuer": "VISA EUROPE LIMITED",
                "country": "GB",
                "bin_number": "417666"
            },
            "expiration_year": "29",
            "expiration_month": "01",
            "fingerprint_token": "ocfp_8eb736573e0985910cbd9303441ab75d",
            "network_reference_id": "000000258200813",
            "payment_account_reference": "V0010019169397631953494893013"
        },
        "auth_code": "645605",
        "expiration": 1771632000,
        "captured": false,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "",
        "complete_payment_url": "https://www.yahoo.com",
        "error_payment_url": "https://www.lego.com",
        "receipt_number": "",
        "flow_type": "",
        "address": null,
        "statement_descriptor": "from db",
        "transaction_id": "",
        "created_at": 1769060571,
        "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_c3016bb4e958f489046b5a7e82826063",
        "ewalleters": null,
        "ewallets": [
            {
                "ewallet_id": "ewallet_c3016bb4e958f489046b5a7e82826063",
                "amount": 100,
                "percent": 100,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {
            "3d_required": true,
            "is_adjustable": 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_26302_00000001_valitor",
        "next_action": "pending_capture",
        "error_code": "",
        "remitter_information": {},
        "save_payment_method": true,
        "merchant_advice_code": null,
        "merchant_advice_message": null,
        "authentication_result": {
            "eci": "05",
            "result": "A",
            "version": "2.2.0",
            "cardholder_info": null
        },
        "transaction_link_id": null
    }
}
Update the Card Payment

Use Update Payment to increase the payment amount.

Prerequisite

To update a card payment and initiate an incremental authorization, the original payment being updated must have the is_adjustable field set to true.

Update Payment Request

    • Request

      • // Request URL: POST https://sandboxapi.rapyd.net/v1/payments/payment_fb3f486eaf16c1d3e0c7c1b1bba85b22

// Message body: 

{
    "amount": 500,
    "description": "Increasing amount"
}
Update Payment Response

    • Response

      • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "a336f29f-4b4d-4e9b-8a82-ca6cff275688"
    },
    "data": {
        "id": "payment_fb3f486eaf16c1d3e0c7c1b1bba85b22",
        "amount": 0,
        "original_amount": 500,
        "is_partial": false,
        "currency_code": "GBP",
        "country_code": "GB",
        "status": "ACT",
        "description": "Increasing amount",
        "merchant_reference_id": "",
        "customer_token": "cus_9cb668a06820dfad16560fcb7d66bf8b",
        "payment_method": "card_2926398a8aa1df155399e837db4cc124",
        "payment_method_data": {
            "id": "card_2926398a8aa1df155399e837db4cc124",
            "type": "gb_visa_card",
            "category": "card",
            "metadata": null,
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "not_applicable",
            "name": "Card Test",
            "last4": "0100",
            "acs_check": "pass",
            "cvv_check": "pass",
            "bin_details": {
                "type": "CREDIT",
                "brand": "VISA",
                "level": "CLASSIC",
                "issuer": "VISA EUROPE LIMITED",
                "country": "GB",
                "bin_number": "417666"
            },
            "expiration_year": "29",
            "expiration_month": "01",
            "fingerprint_token": "ocfp_8eb736573e0985910cbd9303441ab75d",
            "network_reference_id": "000000258200813",
            "payment_account_reference": "V0010019169397631953494893013"
        },
        "auth_code": "404383",
        "expiration": 1771632000,
        "captured": false,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "",
        "complete_payment_url": "https://www.yahoo.com",
        "error_payment_url": "https://www.lego.com",
        "receipt_number": "",
        "flow_type": "",
        "address": null,
        "statement_descriptor": "from db",
        "transaction_id": "",
        "created_at": 1769060571,
        "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_c3016bb4e958f489046b5a7e82826063",
        "ewallets": [
            {
                "ewallet_id": "ewallet_c3016bb4e958f489046b5a7e82826063",
                "amount": 100,
                "percent": 100,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {
            "3d_required": true,
            "is_adjustable": 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_26302_00000001_valitor",
        "next_action": "pending_capture",
        "error_code": "",
        "remitter_information": {},
        "save_payment_method": true,
        "merchant_advice_code": null,
        "merchant_advice_message": null,
        "authentication_result": {
            "eci": "05",
            "result": "A",
            "version": "2.2.0",
            "cardholder_info": null
        },
        "transaction_link_id": null
    }
}
Capture the Card Payment

Use Capture Payment to capture the final payment amount.

Capture Payment Request

    • Request

      • // Request URL: POST https://sandboxapi.rapyd.net/v1/payments/:payment/capture

// Message body: 

{
    "amount": 500
}
Capture Payment Response

    • Response

      • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "c26baa5e-1764-4f47-9d98-9d60f4da485d"
    },
    "data": {
        "id": "payment_fb3f486eaf16c1d3e0c7c1b1bba85b22",
        "amount": 500,
        "original_amount": 500,
        "is_partial": false,
        "currency_code": "GBP",
        "country_code": "GB",
        "status": "CLO",
        "description": "Increasing amount",
        "merchant_reference_id": "",
        "customer_token": "cus_9cb668a06820dfad16560fcb7d66bf8b",
        "payment_method": "card_2926398a8aa1df155399e837db4cc124",
        "payment_method_data": {
            "id": "card_2926398a8aa1df155399e837db4cc124",
            "type": "gb_visa_card",
            "category": "card",
            "metadata": null,
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "not_applicable",
            "name": "Card Test",
            "last4": "0100",
            "acs_check": "pass",
            "cvv_check": "pass",
            "bin_details": {
                "type": "CREDIT",
                "brand": "VISA",
                "level": "CLASSIC",
                "issuer": "VISA EUROPE LIMITED",
                "country": "GB",
                "bin_number": "417666"
            },
            "expiration_year": "29",
            "expiration_month": "01",
            "fingerprint_token": "ocfp_8eb736573e0985910cbd9303441ab75d",
            "network_reference_id": "000000258200813",
            "payment_account_reference": "V0010019169397631953494893013"
        },
        "auth_code": "404383",
        "expiration": 1771632000,
        "captured": true,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "",
        "complete_payment_url": "https://www.yahoo.com",
        "error_payment_url": "https://www.lego.com",
        "receipt_number": "",
        "flow_type": "",
        "address": null,
        "statement_descriptor": "from db",
        "transaction_id": "",
        "created_at": 1769060571,
        "metadata": {},
        "failure_code": "",
        "failure_message": "",
        "paid": true,
        "paid_at": 1769060627,
        "dispute": null,
        "refunds": null,
        "order": null,
        "outcome": null,
        "visual_codes": {},
        "textual_codes": {},
        "instructions": [],
        "ewallet_id": "ewallet_c3016bb4e958f489046b5a7e82826063",
        "ewallets": [
            {
                "ewallet_id": "ewallet_c3016bb4e958f489046b5a7e82826063",
                "amount": 100,
                "percent": 100,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {
            "3d_required": true,
            "is_adjustable": 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_26302_00000001_valitor",
        "next_action": "not_applicable",
        "error_code": "",
        "remitter_information": {},
        "save_payment_method": true,
        "merchant_advice_code": null,
        "merchant_advice_message": null,
        "authentication_result": {
            "eci": "05",
            "result": "A",
            "version": "2.2.0",
            "cardholder_info": null
        },
        "transaction_link_id": null
    }
}
In this section:

Regulations developed for the payment card industry for data security and protection against fraud.