Force operation

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

FieldTypeOptional or requiredDescription
tracking_idstringoptionalThe unique 36-character identifier of the forced operation. If you don't provide an identifier, the Pismo platform generates one for you.
account_idintegerrequiredThe unique identifier of an account in the Pismo platform.
amountfloat numberrequiredThe credit or debit amount.
processing_codestringrequiredThe 6-character processing code that identifies the credit or debit operation.
currencystringoptionalCurrency code of the requested operation, in ISO 4217.
descriptorstringoptionalThe description of the created operation.
metadataobjectoptionalAny valid JSON key-value object that allows you to add complementary custom information.

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"
}
FieldTypeDescription
authorization_idintegerThe generated identifier for the authorization.
tracking_idstringThe unique 36-character identifier for the forced operation. If you didn't provide an identifier, then the Pismo platform automatically generates and includes one in the response.
event_datestringThe date and time of the transaction, in the UTC-0 (RFC3339) format.

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.

Forced operationAdjustment
A forced operation is an anticipated operation that happens in a regular operational scenario. For example, it can be a cashback credit or a transaction fee.An adjustment is a tool for you to adjust values when something outside of the normal operational scenarios happens. For example, it can be used to correct minor inconsistencies in values due to different rounding numbers methods from one platform to another.
A request to the force endpoint generates an authorization with a new authorization identifier, which in turn generates a transaction and triggers all expected events and data workflows.A request to the adjustment endpoint does not generate an authorization but generates an adjustment with a new adjustment identifier.
A forced operation is implemented using a processing_code.An adjustment is implemented using an adjustment_type.
A forced operation does not validate account status, account balance, or flex controls.An adjustment does not validate account status or flex controls but can be configured to validate account balance.
A processing_code can be configured to integrate with the Pismo processes to perform certain rate calculations.An adjustment_type can be configured in a variety of ways to customize the flow, for example, whether an adjustment affects credit limit, impacts statement balance, or is sent to accounting.
The Force operation API is recommended for new implementations and is slated for future enhancements.The Adjustments API is supported in maintenance mode.

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