/transaction/cancel

Request

Purpose

Cancels a pending transaction. Uses the Strategy pattern to apply different validation rules based on transaction type (Outbound vs Inbound).

Transaction Types

Outbound (branch starts with A, E, etc.)

Agency sends money abroad. Supports three flows:

Void: Immediate cancellation within time window (is_void = true)
Cancelation Request: Submit request with reason for approval
Orchestrator: Route to PayerProxy for DONE/TRANSFERED status

Inbound (branch starts with I)

Money arrives from external sources. Additional validation:

Only transactions with id_flag_receiver = I (in process) or H (on hold) can be cancelled
Status RETURNED is also considered terminal (not cancellable)

When to Use

Use this endpoint when you need to:

Cancel a transaction that has not been completed yet
Void a transaction within the allowed time window
Submit a cancelation request with a reason for transactions that require approval

Authentication

Requires x-client-id and x-secret-key headers for partner authentication.

Integration with Cancel Reasons Catalog

Before calling this endpoint, retrieve available cancellation reasons from our catalogs API:

Catalogs Endpoint Cancel Reasons

The catalog returns objects with reasonId and reasonName — use those values directly in this request body.

Cancel Flows

The system determines the cancellation flow based on the transaction status and the IS_VOID flag:

Condition	Flow	Response `cancelFlow`
`is_void = true`	Void	`"void"`
`is_void = false`, status HOLD/NEW	Cancelation Request	`"cancelation-request"`
Status DONE or TRANSFERED	Orchestrator	`"orchestrator"`

Business Rules

Outbound

Transactions with status CANCEL, PAID, or VOID cannot be cancelled
A transaction that already has a pending cancellation request cannot be cancelled again

Inbound

Only transactions with id_flag_receiver I or H can be cancelled (422003 otherwise)
Transactions with status CANCEL, PAID, VOID, or RETURNED cannot be cancelled
A transaction that already has a pending cancellation request cannot be cancelled again

Common

The reasonName and reasonId fields are required for cancelation request flow. You can check the available reasons in our catalogs API: Catalogs Endpoint Cancel Reasons
The transactionContext object is required (contains cashierId); branchId within it is optional because the branch is always derived from the stored transaction
If you do send transactionContext.branchId, it must match the branch that owns the transaction, otherwise the request is rejected with 400417. Use it as a safety check when the caller already knows the branch

Common Errors

400 Validation errors, malformed JSON, or transaction belonging to another partner
401 Invalid credentials
403 Access forbidden for this client
404 Transaction not found
422 Business-rule rejection (terminal status, duplicate request, inbound flag)
500 Internal error
502 External service error (ViaOne / orchestrator)

Error codes (click to expand)

Code	Description
`400000`	The body of the request is required, or the JSON format is invalid. Also returned when the x-client-id or x-secret-key header is missing, and when the branch of the transaction does not belong to the authenticated partner (details contains the offending branchId).
`400001`	Field is required. Applies to uuid, transactionContext and transactionContext.cashierId. transactionContext.branchId is optional: the endpoint derives the branch from the stored transaction.
`400002`	Field must be of the correct type: string for uuid, reasonName, reasonId, reasonNotes and the transactionContext members; object for transactionContext.
`400003`	Field does not meet the minimum length. Only uuid can trigger it (minimum 32 characters).
`400004`	Field exceeds the maximum length: uuid (60), transactionContext.branchId (10), transactionContext.cashierId (40), reasonName (255), reasonId (10) or reasonNotes (500).
`400417`	The transactionContext.branchId sent in the request does not match the branch that owns the transaction. Only raised when the caller sends that field, since it is optional; the comparison ignores case and padding.
`502001`	External API error during cancellation: the ViaOne service or the PayerProxy orchestrator failed. When ViaOne rejects the request with HTTP 400, 404 or 422 that status is propagated, but the payload keeps code 502001.
`401000`	Invalid credentials (x-client-id / x-secret-key). Also returned when authentication against the ViaOne service fails.
`403001`	Access to this resource is forbidden for this client: the partner does not have transaction/cancel in its allowed resources.
`404000`	Transaction not found in SQL Server (the status query returned no rows).
`404001`	Transaction not found in DynamoDB for the given uuid.
`422001`	Transaction cannot be cancelled because of its current status. Outbound: CANCEL, PAID or VOID. Inbound: CANCEL, PAID, VOID or RETURNED. The message includes the current status.
`422002`	Transaction already has a pending cancellation request (has_cancellation_req = 1); it cannot be requested twice.
`422003`	Inbound only: the transaction can be cancelled only while id_flag_receiver is I (in process) or H (on hold). The message includes the current flag.
`500000`	Internal server error (unhandled exception).

x-client-idstring, [ 16 .. 64 ] charactersrequired

Unique identifier assigned to the integrating client. It determines the validation rules, allowed values, compliance policies, and operational limits applied to the request.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example:xxxx123456789

x-secret-keystring, [ 32 .. 128 ] charactersrequired

Secret authentication key associated with the client. It is used to authorize the request and must be kept strictly confidential.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example:xxxx987654321xxs

Bodyapplication/jsonrequired

uuidstring, [ 32 .. 60 ] charactersrequired

Unique identifier of the transaction to cancel

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

transactionContextobjectrequired

Transaction context. The branchId is derived internally from DynamoDB; cashierId identifies who requested the cancellation.

Error codes: required=400001, type=400002

reasonNamestring, <= 255 characters

Cancellation reason text. You can check the available cancellation reasons in our catalogs API Catalogs Endpoint Cancel Reasons

Error codes: type=400002, maxLength=400004

reasonIdstring, <= 10 characters

Cancellation reason ID. You can check the available cancellation reasons in our catalogs API Catalogs Endpoint Cancel Reasons

Error codes: type=400002, maxLength=400004

reasonNotesstring, <= 500 characters

Additional notes or comments about the cancellation reason

Error codes: type=400002, maxLength=400004

DELETE

/transaction/cancel

curl -i -X DELETE \
  https://sandbox-viablocks.viamericas.io/transaction/cancel \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: xxxx123456789' \
  -H 'x-secret-key: xxxx987654321xxs' \
  -d '{
    "uuid": "e2459eec-f25d-4450-8776-5b172cc7dc33",
    "transactionContext": {
      "cashierId": "CASHIER01"
    }
  }'

Responses

Transaction cancelled successfully. The cancelFlow field indicates which cancellation path was used.

Bodyapplication/json

statusstring

Request status (always 'success')

cancelFlowstring

Cancellation flow used: 'void', 'cancelation-request', or 'orchestrator'

messagestring

Descriptive message about the operation result

Response

{
  "status": "success",
  "transaction_uuid": "e2459eec-f25d-4450-8776-5b172cc7dc33",
  "cancelFlow": "void",
  "message": "Transaction voided successfully"
}