🚧

Upgrade to the latest version

These docs are for version 2023-12-01. We encourage you to upgrade to version 2024-10-16 to access new features. Please see the changelog for more information.

Partial authorizations can be utilized to reduce the occurrence of payments failing due to insufficient funds. If the payment is allowed to be partially authorized, then the issuing bank will authorize and process the available amount, instead of declining the payment.

Limitations

There are a few limitations to consider with partial authorizations:

• There is no guarantee that the issuing bank supports partial authorization
• Partial authorization is mainly supported for Visa and Mastercard
• Partial authorization is not supported with amount splits
• Additional logic will be required by the platform to ensure the remaining balance is processed

Enable partial authorization

Partial authorization is configured by setting the allow_partial_authorization boolean on the create payin config request.

{
    "merchant_id": "{{merchant_id}}",
    "idempotency_key": "{{idempotency_key}}",
    "amount": 10000,
    "currency_code": "USD",
+   "allow_partial_authorization": true
}

Know if the payment was partially authorized

Rainforest will return the following fields to indicate if a payment was authorized and processed for a partial amount.

For example, if a payin was configured for $10, but partially authorized for $5, the payin response would look like the following:

{
    "payin_id": "pyi_123",
    ...
+   "amount": 500,
    "currency_code": "USD",
+   "is_partially_authorized": true,
    "status": "PROCESSING",
    ...
    "payin_config": {
      "payin_config_id": "cfg_123",
+     "amount": 1000,
      "currency_code": "USD",
    }
}

If the payment was for a partial amount, you should direct the customer accordingly to process the remaining balance. If the customer chooses to exit the payment flow, the partially authorized payin will need to be voided resulting in a payin status of Canceled.

Listen to Payment Component events

The payment component will emit the approved event and the event data will include the fields returned by the get payin endpoint, which includes the fields defined above.

Listen to webhooks

The payin webhook for payin.processing will include the fields defined above.

Query the API

The get payin endpoint will include the fields defined above.

View in the components

The Payin Details in the Payment Report Component displays a "Partially Authorization" indicator next to the payin status and the full amount requested in the "Related Info" section.

Simulate partial authorization scenarios in sandbox

Utilize the test cards in sandbox to simulate various partial authorization scenarios depending on if the allow_partial_authorization boolean is set in the payin config.