# POST /api/transactions/by-merchant/{merchantId}/{transactionId}/operations Execute a follow-up operation on an existing transaction. A client disconnect does not cancel an operation once the request has been received. The caller needs the permission for the requested operation type: `Transactions.Operations.Void` for Void and Reversal, `Transactions.Operations.Refund` for Refund, `Transactions.Operations.Capture` for Capture, `Transactions.Operations.Adjustment` for OfflineAdjustment and IncrementalAuthorization, `Transactions.Payments.Create` for Repeat and Retry, and `Transactions.PartialApproval.Acknowledge` for AcceptPartialApproval and SplitTender. A Refund, Repeat or Retry creates a new transaction, which also requires `Transactions.Payments.Create`. A caller without the permission receives 403 before the transaction is read, so the response does not reveal whether the transaction exists. **Operation ID:** `transactionOperationsExecuteOperation` ## Authorization No permission required. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | merchantId | path | yes | string(uuid) | The merchant that owns the parent transaction. Required so the parent transaction is read directly rather than searched for. | | transactionId | path | yes | string(uuid) | The transaction to operate on. | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Request Body The operation details (type, optional amount, optional reason). **Content type:** `application/json` Schema: `ExecuteTransactionOperationInput` Properties: - `operationType` (object): The type of operation to execute (e.g., Refund, Reversal, Void, Capture). - `amount` (number(double)): Optional amount for partial operations (refund, reversal). What an omitted value means differs by operation, so it is stated per operation rather than as one rule. Conditional: When Amount is not null. Must be > 0. - `reason` (string): Optional reason or note for the operation. - `idempotencyKey` (string): Optional caller-supplied idempotency key used to deduplicate a retried operation (reversal, void, capture, refund, repeat, retry) after a network timeout. The key is scoped to a single merchant + transaction + operation: submitting the same operation twice with the same key executes once and the second call returns the original operation's outcome (for a spawning operation, the same child transaction id) instead of re-applying it. Conditional: When IdempotencyKey is not empty. Max length: 128. - `offlineAdjustment` (object): Structured field bundle for the `OfflineAdjustment` operation. Required when `operationType` is `OfflineAdjustment`; rejected by the input validator for any other operation type so the wrong shape cannot ride along quietly. Required: When OperationType == OfflineAdjustment. Conditional: When OfflineAdjustment is not null. Conditional: When OperationType != OfflineAdjustment. - `incrementalAuthorization` (object): Structured field bundle for the `IncrementalAuthorization` operation. Required when `operationType` is `IncrementalAuthorization`; rejected by the input validator for any other operation type so the wrong shape cannot ride along quietly. Required: When OperationType == IncrementalAuthorization. Conditional: When IncrementalAuthorization is not null. Conditional: When OperationType != IncrementalAuthorization. - `initiationType` (object): Classification gate for `Repeat`. The caller must declare whether the new charge is being initiated by the cardholder (CIT: cardholder is present and authorizing this specific re-run) or by the merchant (MIT: under prior consent or as a network resubmission of a declined attempt). Required: When OperationType == Repeat. Conditional: When InitiationType is not null. - `mitReason` (object): MIT reason code (Recurring, UnscheduledCOF, Resubmission, etc.) accompanying `initiationType` when it is `MerchantInitiated`. Required: When OperationType == Repeat and InitiationType == MerchantInitiated. Conditional: When MITReason is not null. - `storedCredentialConsentId` (string(uuid)): Identifier of the `StoredCredentialConsent` record that authorizes this MIT. Required for non-resubmission MITs (Recurring, UnscheduledCOF, NoShow, DelayedCharge, Installment, Reauthorization, IncrementalAuth). Ignored for `Resubmission`: resubmissions are authorized by card-network resubmission rules rather than by a consent record. **Content type:** `text/json` Schema: `ExecuteTransactionOperationInput` Properties: - `operationType` (object): The type of operation to execute (e.g., Refund, Reversal, Void, Capture). - `amount` (number(double)): Optional amount for partial operations (refund, reversal). What an omitted value means differs by operation, so it is stated per operation rather than as one rule. Conditional: When Amount is not null. Must be > 0. - `reason` (string): Optional reason or note for the operation. - `idempotencyKey` (string): Optional caller-supplied idempotency key used to deduplicate a retried operation (reversal, void, capture, refund, repeat, retry) after a network timeout. The key is scoped to a single merchant + transaction + operation: submitting the same operation twice with the same key executes once and the second call returns the original operation's outcome (for a spawning operation, the same child transaction id) instead of re-applying it. Conditional: When IdempotencyKey is not empty. Max length: 128. - `offlineAdjustment` (object): Structured field bundle for the `OfflineAdjustment` operation. Required when `operationType` is `OfflineAdjustment`; rejected by the input validator for any other operation type so the wrong shape cannot ride along quietly. Required: When OperationType == OfflineAdjustment. Conditional: When OfflineAdjustment is not null. Conditional: When OperationType != OfflineAdjustment. - `incrementalAuthorization` (object): Structured field bundle for the `IncrementalAuthorization` operation. Required when `operationType` is `IncrementalAuthorization`; rejected by the input validator for any other operation type so the wrong shape cannot ride along quietly. Required: When OperationType == IncrementalAuthorization. Conditional: When IncrementalAuthorization is not null. Conditional: When OperationType != IncrementalAuthorization. - `initiationType` (object): Classification gate for `Repeat`. The caller must declare whether the new charge is being initiated by the cardholder (CIT: cardholder is present and authorizing this specific re-run) or by the merchant (MIT: under prior consent or as a network resubmission of a declined attempt). Required: When OperationType == Repeat. Conditional: When InitiationType is not null. - `mitReason` (object): MIT reason code (Recurring, UnscheduledCOF, Resubmission, etc.) accompanying `initiationType` when it is `MerchantInitiated`. Required: When OperationType == Repeat and InitiationType == MerchantInitiated. Conditional: When MITReason is not null. - `storedCredentialConsentId` (string(uuid)): Identifier of the `StoredCredentialConsent` record that authorizes this MIT. Required for non-resubmission MITs (Recurring, UnscheduledCOF, NoShow, DelayedCharge, Installment, Reauthorization, IncrementalAuth). Ignored for `Resubmission`: resubmissions are authorized by card-network resubmission rules rather than by a consent record. **Content type:** `application/*+json` Schema: `ExecuteTransactionOperationInput` Properties: - `operationType` (object): The type of operation to execute (e.g., Refund, Reversal, Void, Capture). - `amount` (number(double)): Optional amount for partial operations (refund, reversal). What an omitted value means differs by operation, so it is stated per operation rather than as one rule. Conditional: When Amount is not null. Must be > 0. - `reason` (string): Optional reason or note for the operation. - `idempotencyKey` (string): Optional caller-supplied idempotency key used to deduplicate a retried operation (reversal, void, capture, refund, repeat, retry) after a network timeout. The key is scoped to a single merchant + transaction + operation: submitting the same operation twice with the same key executes once and the second call returns the original operation's outcome (for a spawning operation, the same child transaction id) instead of re-applying it. Conditional: When IdempotencyKey is not empty. Max length: 128. - `offlineAdjustment` (object): Structured field bundle for the `OfflineAdjustment` operation. Required when `operationType` is `OfflineAdjustment`; rejected by the input validator for any other operation type so the wrong shape cannot ride along quietly. Required: When OperationType == OfflineAdjustment. Conditional: When OfflineAdjustment is not null. Conditional: When OperationType != OfflineAdjustment. - `incrementalAuthorization` (object): Structured field bundle for the `IncrementalAuthorization` operation. Required when `operationType` is `IncrementalAuthorization`; rejected by the input validator for any other operation type so the wrong shape cannot ride along quietly. Required: When OperationType == IncrementalAuthorization. Conditional: When IncrementalAuthorization is not null. Conditional: When OperationType != IncrementalAuthorization. - `initiationType` (object): Classification gate for `Repeat`. The caller must declare whether the new charge is being initiated by the cardholder (CIT: cardholder is present and authorizing this specific re-run) or by the merchant (MIT: under prior consent or as a network resubmission of a declined attempt). Required: When OperationType == Repeat. Conditional: When InitiationType is not null. - `mitReason` (object): MIT reason code (Recurring, UnscheduledCOF, Resubmission, etc.) accompanying `initiationType` when it is `MerchantInitiated`. Required: When OperationType == Repeat and InitiationType == MerchantInitiated. Conditional: When MITReason is not null. - `storedCredentialConsentId` (string(uuid)): Identifier of the `StoredCredentialConsent` record that authorizes this MIT. Required for non-resubmission MITs (Recurring, UnscheduledCOF, NoShow, DelayedCharge, Installment, Reauthorization, IncrementalAuth). Ignored for `Resubmission`: resubmissions are authorized by card-network resubmission rules rather than by a consent record. ## Responses ### 200 OK **Content type:** `application/json` Schema: `TransactionOperationResultDto` Properties: - `success` (boolean): Whether the operation was successfully submitted to the orchestrator. - `message` (string): Human-readable message describing the result. - `transactionId` (string(uuid)): The original transaction ID the operation was performed on. - `operationType` (object): The operation type that was executed. - `errorCode` (string): Machine-readable error code for programmatic handling. - `timedOut` (boolean): True when the operation was submitted to the orchestrator but completion timed out. The operation may still be processing: the user should check the transaction status. - `newTransactionId` (string(uuid)): The ID of a newly created transaction, set when the operation creates a new transaction (e.g., Repeat). Null for operations that modify the existing transaction in-place. ### 403 Forbidden **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 401 Unauthorized **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 400 Bad Request **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 404 Not Found **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 501 Not Implemented **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 500 Internal Server Error **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. See the error-code reference in this document's description for the values `error.code` can take. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause. A sandbox request whose merchant has spent the plan's transaction allowance is refused with a different `application/json` body: `code` is `USAGE_BUDGET_EXCEEDED`, and `limit` and `used` report the allowance. `Retry-After` is sent only when the allowance resets. An allowance that never resets sends none, and retrying won't help. **Content type:** `application/problem+json` Schema: `RateLimitProblemDetails` Properties: - `type` (string) required: The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. - `title` (string) required: A short, human-readable summary of the problem type. - `status` (integer(int32)) required: The HTTP status code, repeated in the body as the problem-details format defines. - `detail` (string) required: A human-readable explanation of this occurrence of the problem. - `retryAfterSeconds` (integer(int32)) required: How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again. **Content type:** `application/json` Schema type: `object` ## Example request Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key. The request body is a ExecuteTransactionOperationInput. See the Request body section below for its fields. ### cURL ```bash curl -X POST "{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/operations" \ -H "api-key: {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "operationType": {}, "amount": 0, "reason": "", "idempotencyKey": "", "offlineAdjustment": {}, "incrementalAuthorization": {}, "initiationType": {}, "mitReason": {}, "storedCredentialConsentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }' ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $body = @' { "operationType": {}, "amount": 0, "reason": "", "idempotencyKey": "", "offlineAdjustment": {}, "incrementalAuthorization": {}, "initiationType": {}, "mitReason": {}, "storedCredentialConsentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } '@ $response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/operations' ` -Headers $headers -ContentType 'application/json' -Body $body ``` ### TypeScript (SDK) ```bash npm install @winkpg/winkpg-api ``` ```typescript import { Configuration, TransactionsApi } from '@winkpg/winkpg-api'; const api = new TransactionsApi(new Configuration({ basePath: '{{BASE_URL}}', apiKey: '{{API_KEY}}', })); const { data } = await api.transactionOperationsExecuteOperation("3fa85f64-5717-4562-b3fc-2c963f66afa6", "3fa85f64-5717-4562-b3fc-2c963f66afa6", { "operationType": {}, "amount": 0, "reason": "", "idempotencyKey": "", "offlineAdjustment": {}, "incrementalAuthorization": {}, "initiationType": {}, "mitReason": {}, "storedCredentialConsentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/operations', { method: 'POST', headers: { "api-key": "{{API_KEY}}", "Content-Type": "application/json", }, body: JSON.stringify({ "operationType": {}, "amount": 0, "reason": "", "idempotencyKey": "", "offlineAdjustment": {}, "incrementalAuthorization": {}, "initiationType": {}, "mitReason": {}, "storedCredentialConsentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }), }); const data = await response.json(); ``` ### C# (SDK) ```bash dotnet add package WinkPg.Api.Client ``` ```csharp using WinkPg.Api.Client.Api; using WinkPg.Api.Client.Client; using System.Text.Json; var config = new Configuration { BasePath = "{{BASE_URL}}" }; config.AddApiKey("api-key", "{{API_KEY}}"); var api = new TransactionsApi(config); var body = JsonSerializer.Deserialize(""" { "operationType": {}, "amount": 0, "reason": "", "idempotencyKey": "", "offlineAdjustment": {}, "incrementalAuthorization": {}, "initiationType": {}, "mitReason": {}, "storedCredentialConsentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } """); var result = await api.TransactionOperationsExecuteOperationAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), body); ``` ### C# (raw HTTP) ```csharp using System.Text; using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/transactions/by-merchant/{merchantId}/{transactionId}/operations"); request.Headers.Add("api-key", "{{API_KEY}}"); request.Content = new StringContent(""" { "operationType": {}, "amount": 0, "reason": "", "idempotencyKey": "", "offlineAdjustment": {}, "incrementalAuthorization": {}, "initiationType": {}, "mitReason": {}, "storedCredentialConsentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } """, Encoding.UTF8, "application/json"); var response = await http.SendAsync(request); response.EnsureSuccessStatusCode(); var json = await response.Content.ReadAsStringAsync(); ``` ### Python (SDK) ```bash pip install winkpg-api ``` ```python import winkpg_api configuration = winkpg_api.Configuration(host="{{BASE_URL}}") configuration.api_key["ApiKey"] = "{{API_KEY}}" with winkpg_api.ApiClient(configuration) as client: api = winkpg_api.TransactionsApi(client) body = winkpg_api.ExecuteTransactionOperationInput.from_dict({ "operationType": {}, "amount": 0, "reason": "", "idempotencyKey": "", "offlineAdjustment": {}, "incrementalAuthorization": {}, "initiationType": {}, "mitReason": {}, "storedCredentialConsentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }) result = api.transaction_operations_execute_operation("3fa85f64-5717-4562-b3fc-2c963f66afa6", "3fa85f64-5717-4562-b3fc-2c963f66afa6", body) ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", "Content-Type": "application/json", } body = { "operationType": {}, "amount": 0, "reason": "", "idempotencyKey": "", "offlineAdjustment": {}, "incrementalAuthorization": {}, "initiationType": {}, "mitReason": {}, "storedCredentialConsentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } response = requests.request( "POST", "{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/operations", headers=headers, json=body, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal-simpay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.