# 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.

## /transaction/create

 - [POST /transaction/create](https://docs2-viablocks.viamericas.io/apis/inbound/transaction/paths/~1transaction~1create/post.md): Creates a new inbound cross-border money transfer and registers it in the ViaBlocks platform.

## Purpose
Initiates a new remittance transaction with sender, beneficiary, and financial details.

## When to use
Use this endpoint when you are ready to submit:
- Sender onboarding details (KYC/AML fields)
- Beneficiary details and payout configuration
- Origination and delivery amounts/currencies
- Funding configuration (cash or remote payment)

## What happens next
Next steps depend on the funding method:
- Cash funding: Transaction may proceed directly into processing.

## Authentication
Requires x-client-id and x-secret-key headers.

## Notes
- Request validation is enforced for formats, allowed values, corridor rules, and compliance requirements.

## Common errors
- 400 Validation errors (missing/invalid fields)
- 401 Invalid credentials
- 404 Sender/beneficiary linkage issues
- 422 Business-rule rejection (e.g., credit limit)
- 500 Internal error

## /transaction/status

 - [GET /transaction/status](https://docs2-viablocks.viamericas.io/apis/inbound/transaction/paths/~1transaction~1status/get.md): Retrieves the current status and details of a transaction.

## Purpose
Returns the real-time status, financial details, compliance information, and tracking data for a specific transaction.

## When to use
Use this endpoint to:
- Check the current processing status of a transaction
- Retrieve hold information and compliance requirements
- Get the transaction tracking URL
- Monitor transaction lifecycle (creation, confirmation, payment, cancellation)

## What happens next
1. Validates the transaction exists in DynamoDB
2. Retrieves real-time status from SQL Server
3. Combines DynamoDB and SQL Server data into a unified response
4. Returns status, holds, compliance requirements, and financial details

## Authentication
Requires x-client-id and x-secret-key headers.

## Notes
- The required_document_list field indicates what compliance documents are still needed (e.g., KYC, ID, SSN).
- Hold information includes active holds that may be blocking the transaction.

## Common errors
- 400 Missing or invalid UUID
- 401 Invalid credentials
- 404 Transaction not found
- 500 Internal error

## /transaction/cancel

 - [DELETE /transaction/cancel](https://docs2-viablocks.viamericas.io/apis/inbound/transaction/paths/~1transaction~1cancel/delete.md): 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:

| Condition | Flow | Response cancelFlow |
|-----------|------|----------------------|
| is_void = true | Void | "void" |
| is_void = false | Cancelation 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