Custom automatic capture feature
Learn how payment providers enable custom automatic capture (settlement) in the connector manifest and how merchants schedule the settlement time frame in the VTEX Admin.
Merchants need flexibility to receive payments according to the characteristics and restrictions of their business. VTEX allows payment providers to offer merchants a custom delay interval for automatic payment settlement.
Setting up this feature involves two roles:
- Payment providers declare support for the feature in the connector manifest and define the range of delays merchants can choose from.
- Merchants select the settlement behavior for that provider in the VTEX Admin.
VTEX replaced the term capture with settlement throughout the Payments documentation. Some identifiers keep the previous term, such as
usesEarlySecurityCapture.
Before you begin
Check the requirements corresponding to your role:
- Payment providers: Your connector must be integrated through the Payment Provider Protocol, so that you can edit the manifest returned by the Get manifest endpoint. For connectors built as VTEX IO apps, edit the
manifest.jsonfile of the app, as described in Payment Provider Framework. - Merchants: The payment provider must be configured in your store, as described in Registering gateway affiliations.
If the fields described in this guide are unavailable for your connector, open a ticket with VTEX support requesting the connector update.
Provider setup
To control the settlement options merchants can use, declare the following fields in the connector manifest:
| Field | Type | Description |
|---|---|---|
usesAutoSettleOptions | Boolean | When set to true, the Scheduled: Schedules the automatic capture option becomes available in the Automatic settlement field in the provider configuration in the VTEX Admin. When set to false or omitted, merchants only see the settlement options that don't require a custom delay. |
autoSettleDelay | Object | Range of delays merchants can schedule, declared with the minimum and maximum properties. Both properties are required, and their values are strings expressed in whole hours. |
The following example declares a provider that accepts scheduled settlement between 0 and 720 hours:
_13{_13 "paymentMethods": [_13 {_13 "name": "Visa",_13 "allowsSplit": "onAuthorize"_13 }_13 ],_13 "usesAutoSettleOptions": true,_13 "autoSettleDelay": {_13 "minimum": "0",_13 "maximum": "720"_13 }_13}
Declare
minimumandmaximumas strings representing whole hours. Decimals aren't allowed. Declaring them as numbers makes the manifest validation fail. ⚠️ EnablingusesAutoSettleOptionsoverrides any behavior set for theusesEarlySecurityCapturefield.
Relationship with the authorization response
The manifest defines the range merchants can choose from, while the authorization response of the Create payment endpoint defines the delay applied to an individual payment. These fields use different units:
| Field | Where it's declared | Unit |
|---|---|---|
autoSettleDelay | Connector manifest | Whole hours, as a string |
delayToAutoSettle | Authorization response | Seconds, limited to 604800 (7 days) |
delayToAutoSettleAfterAntifraud | Authorization response | Seconds |
When the merchant schedules a time frame in the VTEX Admin, that value takes precedence over the delayToAutoSettle value returned in the authorization response.
Merchant configuration
To define how a payment provider settles payments, follow these instructions:
- In the VTEX Admin, go to Store Settings > Payment > Providers, or type Providers in the search bar at the top of the page.
- Select the payment provider you want to configure.
- In the Automatic settlement field, select one of the available options.
- (Optional) If you select Scheduled: Schedules the automatic capture, complete the Scheduled time frame in hours for automatic capture field with the period the platform must wait before settling the payment.
- Save the configuration.
Set the time frame in whole hours and within the range declared by the payment provider in the manifest. Decimals aren't allowed.
The Automatic settlement field provides the following options:
| Option | Behavior |
|---|---|
| Use behavior recommended by the payment processor | Settlement isn't automatic. It follows the period specified by the acquirer, which indicates whether the payment was authorized and can recommend a number of days for settlement. This is the default behavior of the platform. |
| Automatic capture immediately after payment authorization | Settlement happens right after payment authorization, even if the transaction includes an anti-fraud analysis. |
| Automatic capture immediately after anti-fraud analysis | Settlement happens after payment authorization and anti-fraud analysis. Without an anti-fraud analysis, the platform settles the payment right after authorization. |
| Disabled | Settlement happens only when the order is invoiced. Consider your invoicing time because it can exceed the settlement time agreed with the payment provider and lead to canceled transactions. |
| Scheduled: Schedules the automatic capture | Settlement happens after the time frame you define, within the range declared by the payment provider. |
When you select the scheduled option, the VTEX Admin displays the Scheduled time frame in hours for automatic settlement field, as shown in the following image:
