Processing purchases with partial authorisation

Overview

During payment processing, you can encounter situations when the customer's account has insufficient balance for paying the full amount, but you would rather accept a portion of the payment amount than decline the whole payment. For example, it can be relevant when the customer adds funds to their account in the web service: it might not cover the full amount of the subscription fee, but at least a part of it will be paid. To accept such payments and avoid declining them due to insufficient funds, you can use the functionality of partial authorisation (also referred to as partial approval) when a portion of the payment amount is approved by the issuer. This feature is supported by specific card networks.

The ecommpay payment platform supports processing purchases with partial authorisation for standard card payments made with Mastercard and Visa. This capability is enabled upon agreement with your ecommpay account manager for specific projects, following which you can request to apply partial authorisation to each payment initiated on the side of the web service. You can use a specialised parameter allow_partial_approval that was added to the request structure in the API specification.

The ecommpay payment platform supports processing Mastercard and Visa payments with partial authorisation.

The exact amount for which the purchase can be authorised is determined each time by the issuer of the card used for making this purchase (the amount depends on the available balance on the customer's card). The information about this amount is passed from the issuer to the ecommpay payment platform where the approved amount is counted as the actual payment amount, while the initially requested payment amount is ignored. Note that this change can affect subsequent operations within this purchase, for example, capturing the funds held as part of a two-step purchase, or refunding the purchase amount. For example, if the purchase for the initially requested amount of 100 EUR was partially approved for the amount of 90 EUR (the sum actually paid by the customer), partial refund can be requested only for the amount lower than 90 EUR. In turn, the difference between the initial and approved amounts can be paid (and if needed, refunded) separately, with the use of a separate payment request.

The use of partial authorisation capability does not affect standard payment processing workflows as to the interaction between the web service and the payment platform. However, when using this capability, you should be aware of changes in the request and callback formats (more on this below) and be ready to supplement user scenarios as follows. You need to:

Inform your customers that partial authorisation capability is available or make sure they can consent to this payment option—before every purchase to which partial authorisation feature applies.
Inform you customers about the partially approved and paid amount—after every purchase with partial authorisation has been completed.
Provide your customers with the possibility to pay the outstanding amount by making a separate payment (with the use of a different payment instrument)—if necessary.
Ensure the possibility to refund the paid amount—if necessary.
Add other changes and modifications—if it is dictated by the specifics of the web service or the services you provide.

If you have questions about the integration of the partial authorisation capability, refer to your ecommpay account manager. If you have technical questions about the use of this capability, refer to the ecommpay support specialists

Special aspects and limitations

When working with the capability of processing purchases with partial authorisation, consider the following special aspects and limitations:

This capability is supported for purchases made with Mastercard and Visa cards, in cases when the issuer of the specific card supports partial approvals.
If the issuer does not support this capability and the customer's account has insufficient balance, the purchase is declined.
This capability must be enabled for the project.
If this capability is not enabled and the customer's account has insufficient balance, the purchase is declined even if the request contains an indicator that partial approval is allowed.
Partial authorisation can be applied to one-step and two-step purchases as well as one-click purchases if their terms are stored on the side of the web service (the value of stored_card_type parameter is 2, details). If a COF purchase is registered, the initial payment can be partially authorised. However, the change of the initially requested payment amount does not affect the actual amount of the series of debitings that is being registered.
If the request to initiate an on-demand or a regular COF purchase (the value of stored_card_type parameter is 4 or 6 respectively) contains an indicator that partial approval is allowed, it will be ignored and, if the customer's account has insufficient balance, the purchase will be declined.
After the feature of partial authorisation was applied, the actual payment amount is the amount approved by the issuer.
This factors in when currency conversion is used and it affects the subsequent operations within the payment, which can include various actions performed as part of the two-step purchase (increasing or decreasing the previously authorised amount, capturing the held funds or cancelling the hold, even if these operations are initiated automatically).

Setup and use

To enable the partial authorisation capability, discuss with your ecommpay account manager which projects you need this capability for and, once it is agreed upon, get notified by the ecommpay specialists that it has been added and set up.

To use the partial authorisation capability for a specific payment, make sure the capability has been enabled and to include the allow_partial_approval parameter with true specified as its value in the payment request sent from the web service to the payment platform.

Request format

When sending requests to initiate purchases with partial authorisation, consider the following:

To initiate a purchase, send a POST request to one of the following endpoints:
- for one-time one-step purchases with actual card details specified and for one-click purchases—/v2/payment/card/sale
- for one-time one-step purchases with the saved card identifier specified—/v2/payment/card/sale/saved
- for one-time one-step purchases with the card token specified—/v2/payment/card/sale/token
- for one-time two-step purchases with actual card details specified—/v2/payment/card/auth
- for one-time two-step purchases with the saved card identifier specified—/v2/payment/card/auth/saved
Each request must contain objects and parameters required for processing a purchase of a specific type (more information can be found in the descriptions of request formats for initiating one-step and two-step purchases and one-click purchases with their terms stored on the side of the web service.
Each request must contain the allow_partial_approval parameter with true specified as its value in the payment object. If false is passed, or this parameter is not passed in the request at all, partial authorisation is not allowed.
Additionally, any other parameters included in the API specification of the endpoint can be used.

Figure 1. Example of data in the request for processing a one-time one-step purchase with partial authorisation

{
  "general": {
      "project_id": 42,
      "payment_id": "135113521359",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "payment": {
      "amount": 10000,
      "currency": "EUR",
      "allow_partial_approval": true
  },
    "card": {
      "pan": "4314220000000056",
      "year": 2035,
      "month": 8,
      "card_holder": "Prostetnik Jeltz",
      "cvv": "521"
  }
    "customer": {
      "ip_address": "93.47.230.225",
      "id": "customer_12",
      "screen_res": "360x640",
      "phone": "44991234567",
      "email": "p.jeltz@mail.com"
  },
    "return_url": {
      "success": "https://cosmoshop.jupiter.example/pages/success",
      "decline": "https://cosmoshop.jupiter.example/pages/decline"
  }
}

Figure 2. Example of data in the request for processing a one-time one-step purchase with partial authorisation

{
  "general": {
      "project_id": 42,
      "payment_id": "135113521359",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "payment": {
      "amount": 10000,
      "currency": "EUR",
      "allow_partial_approval": true
  },
    "card": {
      "pan": "4314220000000056",
      "year": 2035,
      "month": 8,
      "card_holder": "Prostetnik Jeltz",
      "cvv": "521"
  }
    "customer": {
      "ip_address": "93.47.230.225",
      "id": "customer_12",
      "screen_res": "360x640",
      "phone": "44991234567",
      "email": "p.jeltz@mail.com"
  },
    "return_url": {
      "success": "https://cosmoshop.jupiter.example/pages/success",
      "decline": "https://cosmoshop.jupiter.example/pages/decline"
  }
}

Callback format

Results of purchases with partial authorisation are communicated in callbacks with standard format. To learn more about the callback format, see Handling callbacks. Note that parameters sum, sum_initial, and sum_converted passed in the payment and operation objects contain the amount approved by the issuer, and this amount should be used for reporting and reconciliation.

The following example contains the result of processing a one-time purchase for the amount of 90 EUR approved by the card issuer. (The example of the initial payment request specified the amount of 100 EUR.)

Figure 3. Example of data in the final callback about the one-step purchase with partial authorisation

{
    "account": {
        "number": "431422******0056",
        "type": "visa",
        "card_holder": "PROSTETNIK JELTZ",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2035"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2026-01-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 9000, // approved amount in the requested payment currency
            "currency": "EUR" // code of the requested payment currency
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2026-01-11T13:02:42+0000",
        "created_date": "2026-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 9000, // approved amount in the requested payment currency
            "currency": "EUR" // code of the requested payment currency
        },
        "sum_converted": {
            "amount": 7805, // approved amount in the actual operational currency
            "currency": "GBP" // code of the actual operational currency
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2026-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}

Figure 4. Example of data in the final callback about the one-step purchase with partial authorisation

{
    "account": {
        "number": "431422******0056",
        "type": "visa",
        "card_holder": "PROSTETNIK JELTZ",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2035"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2026-01-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 9000, // approved amount in the requested payment currency
            "currency": "EUR" // code of the requested payment currency
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2026-01-11T13:02:42+0000",
        "created_date": "2026-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 9000, // approved amount in the requested payment currency
            "currency": "EUR" // code of the requested payment currency
        },
        "sum_converted": {
            "amount": 7805, // approved amount in the actual operational currency
            "currency": "GBP" // code of the actual operational currency
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2026-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}

Useful links

The following materials can be useful when you work with the capability of partial authorisation:

One-time purchases—a section with articles about processing one-time one-step and two-step purchases via Gate, including description of processing workflows and data formats for working with standard card payments.
Credential-on-file (COF) purchases—a section with articles about registering and processing COF purchases via Gate, including description of processing workflows and data formats for working with standard card payments.
Purchase refunds—an article about refunding purchases via Gate, including general information about refunds and description of data formats for working with standard card payments.
Handling payment processing information—a section with articles about receiving and processing data on payments executed via the platform.