You can force a credit or a debit operation for a specified account, and the Pismo platform guarantees idempotence and integrity of this operation. A forced operation uses a processing_code, generates a new authorization, and directly impacts the account balance. However, it does not include any of the validations that are performed in the Transfer funds endpoint, such as validating the account status, account balance, or flexible transaction controls. You can choose to include or exclude a forced operation from the account timeline.

The Force operation API is recommended for all new implementations that need to force some anticipated operations, such as cashback credits or transaction fees. For differences between a forced operation and an adjustment, see the comparison table in this guide.

Force operation

To force an operation, use the Force operation endpoint and provide the required account_id, processing_code, and amount. In the request header, you can provide a value for the x-skip-timeline parameter. If set to true, this prevents the generation of timeline events in the customer timeline.

POST <URL>payments/v1/payments/force

Forced credit example

In the following example, the processing_code 090907 defines a credit type. The following payload executes a forced credit operation.

{
	"tracking_id": "ba7f42b9-9bd1-4840-a747-f1b59037b798",
	"account_id": 1234,
	"amount": 40.25,
	"processing_code": "090907",
	"currency": "USD",
	"descriptor": "Forced single credit operation ",
	"metadata": {
		"any-key": "any-value"
	}
}

Sample request details

Sample response details

If the operation is successful (status code 201), the response returns the following three parameters.

{
  "authorization_id": 31812823,
  "tracking_id": "ba7f42b9-9bd1-4840-a747-f1b59037b798",
  "event_date": "2022-02-02T14:05:51.688"
}

If the operation is accepted but there is a delay in processing (status code 202), the response shows the corresponding code and the message. The request will process and finish asynchronously.

If the operation fails (status codes 400, 500), the response returns the code and the corresponding message that describes the error.

If a tracking ID is already in use (status code 409), in addition to the code and the message, the response also returns the related authorizations object.

Cancel forced operation

To cancel a forced operation, use the Cancel forced operation endpoint. This endpoint allows you to cancel the total or partial amount of an existing forced operation.

POST <URL>payments/v1/payments/force/cancel

In the request header, you can provide a value for the x-skip-timeline parameter. If set to true, this prevents generation of timeline events in the customer timeline.

In the request body, provide one of the following required identifiers of the original forced operation:

• authorization_id, the authorization ID which was returned in the forced operation response (v1/payments/force) as authorization_id.
• original_tracking_id, the tracking ID which was returned in the forced operation response (v1/payments/force) as tracking_id.

By default, the request to this endpoint cancels the full amount of the original forced operation. Optionally, you can provide the partial amount to cancel in the amount field. This value should be less than or equal to the amount of the original operation, and greater than 0.

By default, whenever a total or a partial cancellation of an operation with a fee occurs , the platform doesn't cancel this fee automatically (the cancel_fees field is set to false). To cancel the associated fee, set the cancel_fees field to true.

You can also optionally provide the tracking_id, descriptor, and any metadata in the request.

Cancel forced operation examples

The following example request cancels the full amount of the forced credit operation from the previous example.

{
  "authorization_id": 31812823,
  "tracking_id": "1ff51e99-3a05-448a-bc19-7b5c05274174",
  "original_tracking_id": "ba7f42b9-9bd1-4840-a747-f1b59037b798",
  "descriptor": "Cancel forced single credit operation",
  "metadata": {
    "my-custom-key": "my-custom-value"
  }
}

The following example request cancels the partial amount of the forced credit operation and any associated fees.

{
  "authorization_id": 31812823,
  "tracking_id": "1ff51e99-3a05-448a-bc19-7b5c05274174",
  "original_tracking_id": "ba7f42b9-9bd1-4840-a747-f1b59037b798",
  "amount": 20.00,
  "cancel_fees": true,
  "descriptor": "Cancel forced single credit operation",
  "metadata": {
    "my-custom-key": "my-custom-value"
  }
}

Response details

If the cancel forced operation is successful (status code 200), the response returns authorization_id, tracking_id, and event_date of the cancellation.

If the operation is accepted but there is a delay in processing (status code 202), the response shows the corresponding code and the message. The request will process and finish asynchronously.

If the operation fails (status codes 400, 404, 500), the response returns the code and the corresponding message that describes the error.

If a tracking ID is already in use (status code 409) and the operation has been canceled already, the response returns the authorization_id,tracking_id, and event_date of the previously generated cancellation operation.

Forced operation vs. adjustment

Both a forced operation and an adjustment directly impact the amount of money in the customer account either by adding or subtracting funds, but there are important functional differences between them.

For additional information on adjustments, see Adjustments overview.

Related pages

API reference / Force operation
API reference / Cancel forced operation
Guides / Payments and transfers
Guides / Adjustments overview