Skip to content
API Reference/
Money Transfer
/
/Transaction

Transaction

This section provides the Transaction endpoints required to manage and operate the full lifecycle of resources within the ViaBlocks platform.

These endpoints are designed for secure, auditable, and scalable server-to-server integrations, and support core business operations and compliance workflows.

Operations

/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:

ConditionFlowResponse cancelFlow
is_void = trueVoid"void"
is_void = false, status HOLD/NEWCancelation Request"cancelation-request"
Status DONE or TRANSFEREDOrchestrator"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)
CodeDescription
400000The 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).
400001Field is required. Applies to uuid, transactionContext and transactionContext.cashierId. transactionContext.branchId is optional: the endpoint derives the branch from the stored transaction.
400002Field must be of the correct type: string for uuid, reasonName, reasonId, reasonNotes and the transactionContext members; object for transactionContext.
400003Field does not meet the minimum length. Only uuid can trigger it (minimum 32 characters).
400004Field exceeds the maximum length: uuid (60), transactionContext.branchId (10), transactionContext.cashierId (40), reasonName (255), reasonId (10) or reasonNotes (500).
400417The 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.
502001External 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.
401000Invalid credentials (x-client-id / x-secret-key). Also returned when authentication against the ViaOne service fails.
403001Access to this resource is forbidden for this client: the partner does not have transaction/cancel in its allowed resources.
404000Transaction not found in SQL Server (the status query returned no rows).
404001Transaction not found in DynamoDB for the given uuid.
422001Transaction 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.
422002Transaction already has a pending cancellation request (has_cancellation_req = 1); it cannot be requested twice.
422003Inbound 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.
500000Internal server error (unhandled exception).
Headers
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"
}