Skip to content
API Reference/
/
/
/transaction/cancel

/transaction/cancel

Request

Inbound transactions represent money arriving from external sources into the system.

Purpose

Cancels a pending inbound transaction.

When to Use

Use this endpoint when you need to:

  • Void an inbound transaction within the allowed time window (automatic if is_void flag is active)
  • Cancel an inbound transaction that is still in process (status I)
  • Cancel an inbound transaction that is on hold (status H)
  • Submit a cancelation request with a reason for transactions that require approval

What Happens Next

After a successful cancellation request:

  • Void flow: The transaction is immediately voided. Status changes to VOID. No further action is required.
  • Cancelation Request flow: A cancellation request is submitted for approval. The transaction remains in its current status until an administrator approves or rejects the request. Once approved, the transaction status changes to CANCEL.

Authentication

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

Cancel Flows

The system determines the cancellation flow based on the is_void flag in the transaction details:

ConditionFlowResponse cancelFlow
is_void = trueVoid"void"
is_void = falseCancelation Request"cancelation-request"

Void

Immediate cancellation within the allowed time window. The transaction is voided directly without requiring approval.

Cancelation Request

Submits a cancellation request with a reason for approval. The transaction remains active until the request is approved.

Notes

  • Only transactions with id_flag_receiver = I (in process) or H (on hold) can be cancelled.
  • Transactions with status CANCEL, PAID, VOID, or RETURNED are considered terminal and cannot be cancelled.
  • A transaction that already has a pending cancellation request cannot be cancelled again.
  • The branchId must have permission to cancel the transaction.
  • The reasonName and reasonId fields are required for the cancelation-request flow (not required for void).
  • The transactionContext object with branchId is required.
  • If the transaction has is_void = true, the void flow is executed automatically regardless of other fields.
  • Before calling this endpoint, retrieve available cancellation reasons from: Catalogs Endpoint Cancel Reasons

Common Errors

  • 400000 - Invalid JSON format
  • 400001 - Missing or invalid required fields
  • 400417 - Branch ID does not have permission to cancel this transaction
  • 401000 - Invalid credentials (verify x-client-id and x-secret-key headers)
  • 403001 - Partner not authorized for this endpoint
  • 404001 - Transaction not found
  • 422001 - Transaction cannot be cancelled due to its current status
  • 422002 - Transaction already has a pending cancellation request
  • 422003 - Inbound transaction can only be cancelled when status is I or H
  • 502001 - External API error during cancellation
  • 500000 - Internal server error
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.

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.

Example:xxxx987654321xxs
Bodyapplication/jsonrequired
uuidstring, [ 32 .. 60 ] charactersrequired

Unique identifier of the transaction to cancel.

Example:"b9e59b4a-0540-453a-86ca-cb6efa062b96"
transactionContextobjectrequired

Transaction context with branch and cashier information.

reasonNamestring, <= 255 characters

Cancellation reason text. Required for cancelation-request flow. Available reasons can be retrieved from Cancel Reasons Catalog.

Example:"CAMBIO DE BENEFICIARIO"
reasonIdstring, <= 10 characters

Cancellation reason ID. Required for cancelation-request flow. Available reasons can be retrieved from Cancel Reasons Catalog.

Example:"2"
reasonNotesstring, <= 500 characters

Additional notes or comments about the cancellation reason.

Example:"Customer requested beneficiary change"
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": "b9e59b4a-0540-453a-86ca-cb6efa062b96",
    "transactionContext": {
      "branchId": "I99984",
      "cashierId": "ADMIN"
    }
  }'

Responses

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

Bodyapplication/json
statusstring

Request status (always 'success').

Example:"success"
transaction_uuidstring

Unique identifier of the cancelled transaction.

Example:"b9e59b4a-0540-453a-86ca-cb6efa062b96"
cancelFlowstring

Cancellation flow used:

  • void: Transaction was voided immediately (is_void=true)
  • cancelation-request: Cancellation request submitted for approval
Enum:"void""cancelation-request"
Example:"cancelation-request"
messagestring

Descriptive message about the operation result.

Example:"Cancelation request submitted"
Response
{
  "status": "success",
  "transaction_uuid": "b9e59b4a-0540-453a-86ca-cb6efa062b96",
  "cancelFlow": "void",
  "message": "Transaction voided successfully"
}