📘

Authorization and capture is in beta

If you are interested in Authorization and Capture, please contact your Customer Success Manager or Rainforest Support.

Rainforest supports a two-step authorization and capture payment flow, enabling your platform better control of the authorization and holding of funds and when the funds will be captured and processed.

This guide will explain how to integrate the authorization and capture payment flow in your platform.

Authorize the payin

Configure the payin

The processing mode is configured by passing the processing_mode of AUTHORIZE on the create payin config request.

{
    "merchant_id": "{{merchant_id}}",
    "idempotency_key": "{{idempotency_key}}",
    "amount": 10000,
    "currency_code": "USD",
+   "processing_mode": "AUTHORIZE"
}

The processing_mode of AUTHORIZE tells Rainforest to only authorize the payin. When processing the payin through the Payment Component, the user must choose to pay with a Card payment method in order to run an authorization only.

🚧

Authorization only available for Card payins

The processing mode Authorize is only available for payments processed with a Card payment method. If the user chooses to process with an ACH payment method, the processing mode of Authorize and Capture will be used and the payin will result in the status of Processing or Failed.

Authorization result

After processing the payin through the Payment Component or the Rainforest API, the payin will result in the status of Authorized or Failed.

Authorized

If the issuing bank determines the user has enough funds and there are no other reasons to decline the payin, the payin will be approved and the status will move to Authorized. The issuing bank will put a hold on the user's funds.

The get payin endpoint, returns an authorized_amount:

{
    "payin_id": "pyi_2v5d4mFGts9NQPEwQ9gAAIbsjKO",
    "amount": 10000,
    "currency_code": "USD",
    // ...
+   "authorized_amount": 10000,
    "status": "AUTHORIZED"
}

Failed

If the issuing bank declines the payin, the payin status will move to Failed and the authorized_amount will be $0.

{
    "payin_id": "pyi_2v5d4mFGts9NQPEwQ9gAAIbsjKO",
    "amount": 10000,
    "currency_code": "USD",
    // ...
+   "authorized_amount": 0,
    "status": "FAILED",
    "refusal_code": "INSUFFICIENT_FUNDS"
}

Capture the payin

Once the payin is successfully Authorized, you can capture the payin at a later time. This can be minutes, hours, or days later. You should ensure you are following the authorization expiration guidelines to reduce any interchange implications.

By default, the capture payin request will utilize all configuration from the create payin config request, which includes:

• The amount to capture
• The amount splits to allocate the funds across the platform and merchant

Optional request fields

Amount

You can choose to pass an amount into the capture payin request. The amount must be less than or equal to the amount authorized. If the amount is set to $0, then the full authorized amount will be captured.

Amount splits

You can choose to pass in a new amount split into the capture payin request. The amount split must be less than or equal to the amount authorized.

Capture result

Processing

If the capture is successful, the payin status will move to Processing. The funds will move from the user's issuing bank to the merchant.

The get payin endpoint returns a captured_amount that can be different from the authorized_amount if an amount less than the authorized amount was requested to be captured.

For example, a $100 payin was authorized for $100, but only $75 was captured:

{
    "payin_id": "pyi_2v5d4mFGts9NQPEwQ9gAAIbsjKO",
    "amount": 10000,
    "currency_code": "USD",
    // ...
    "authorized_amount": 10000,
+   "captured_amount": 7500,
    "status": "PROCESSING"
}

Failed

If the capture is declined, the payin status will move to Failed and the captured_amount will be $0.

{
    "payin_id": "pyi_2v5d4mFGts9NQPEwQ9gAAIbsjKO",
    "amount": 10000,
    "currency_code": "USD",
    // ...
    "authorized_amount": 10000,
+   "captured_amount": 0,
    "status": "FAILED",
    "refusal_code": "DECLINED"
}

Cancel the authorized payin

A payin can be canceled, also known as voided, when the payin status is Authorized. Canceling a payin will void the full amount of the authorization and remove the hold on the user's funds.

Canceling an authorized payin does incur an authorization void fee, in addition to the authorization fee.

Rainforest recommends you cancel authorizations that will not be captured. Otherwise, the funds will continue to be held on the user's card until the issuing bank expires the authorization. This can result in inquiries from the user to the merchant if the authorization is not canceled in a timely manner.

Sandbox simulation

Utilize the test cards in sandbox to simulate an approval or decline on the authorization request.

For all the test cards in the Approved or Declined categories, the payin statuses will result in the following for the authorization and capture requests:

The following test card can be utilized to simulate an Approved payment on the authorization request, with the status of Authorized, and then later capture of the payin will result in a Declined payment, with the status of Failed.