/transaction/create

Request

Creates a new money transfer and registers it in the ViaBlocks platform. Supports both cross-border (international) and domestic (USA to USA) corridors.

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.
Remote payment funding: Transaction is created in a pending funding state. The sender must complete payment remotely.

Domestic Transfers (USA to USA)

This endpoint also supports domestic transfers within the United States. For domestic transfers, both originationCountryISO and deliveryCountryISO are set to USA, both currencies are USD, and the exchange rate is 1.0.

Available delivery modes for domestic USA

Code	Delivery Mode	Description
`A`	ATM Network	Beneficiary withdraws cash at an ATM using a reference code.
`P`	Cash Pickup (Viamericas agencies)	Beneficiary picks up cash at an authorized Viamericas agent location.
`C`	Bank Deposit (any U.S. bank)	Direct deposit to any U.S. bank account. Requires `accountNumber`, `routingNumber`, and `accountType` in `deliveryModeDetails`.
`O`	Mobile Wallet	Deposit to a mobile wallet.

Key differences from cross-border

Exchange rate is always 1.0 (USD ΓåÆ USD)
Both origin and delivery country are USA
deliveryModeDetails.routingNumber is required for bank deposits (mode C)
The system validates routing numbers via ABA checksum and provider verification

Quote Coherence Validation (Outbound ΓÇö USA origin)

For outbound transactions originating from the United States, the system validates that the financial parameters match the most recent quote. This ensures pricing integrity between the quote and the actual transaction.

Validated fields

Field	Validation Rule
`exchangeRate`	Required. Must match the current rate from the pricing engine, or fall within the allowed rate range if ViaTasa is active for the partner.
`fee`	Required. Must exactly match the fee returned by the quote (`feeBreakdown.fee`).
`fundingFee`	Required when > 0 in quote. Must match `feeBreakdown.fundingFee`. If the quote returned a non-zero funding fee, this field is mandatory.
`taxes`	Required when > 0 in quote. Must match `feeBreakdown.taxes`. If the quote returned a non-zero tax, this field is mandatory.
`originationAmount`	Must be within the `minimumAmount` and `maximumAmount` returned by the quote.
`deliveryAmount`	Must be coherent with `originationAmount ├ù exchangeRate`. If a payer delivery limit exists, the delivery amount must not exceed it.

How it works

Request a quote via POST /transaction/quote with the desired parameters.
Use the values from the quote response (exchangeRate, feeBreakdown.fee, feeBreakdown.fundingFee, feeBreakdown.taxes) in your create request.
If the partner has ViaTasa active, the exchangeRate can be modified within the rateRange bounds returned by the quote.
Submit the create request with all validated fields populated.

Important notes

The promoCode field, if provided, is validated before pricing checks. An invalid promo code will reject the transaction.

Routing Number and Account Verification (USA only)

When the transaction includes a routing number for a USA-based bank account (either in funding or deliveryModeDetails), the system performs additional validations:

ABA Checksum: The routing number must pass ABA checksum validation.
Provider Verification: The routing number is verified against external banking providers to confirm it is valid and active.
Account Risk Assessment: If an account number is provided alongside a valid routing, the system verifies the account. If the verification returns HIGH risk or Declined status, the transaction is rejected.

These validations apply exclusively to USA routing numbers. For other countries, routing numbers are not validated against external providers.

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, quote coherence mismatch)
401 Invalid credentials
404 Sender/beneficiary linkage issues
422 Business-rule rejection (e.g., credit limit, amount limits, compliance block)
500 Internal 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.

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

Example:string

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

Bodyapplication/jsonrequired

transactionContextobject

Context of the transaction.

Error codes: type=400002

senderobjectrequired

Contains the personal and identification information of the transaction sender.

All fields are subject to AML, KYC, and compliance validation rules.

This information is used to verify the identity of the person initiating the transaction and to evaluate regulatory and risk requirements.

Error codes: required=400001, type=400002

beneficiaryobjectrequired

Represents the final recipient of the funds in a cross-border transaction.

Contains the personal, identification, and location information required to validate the recipient against AML, sanctions, and regulatory screening rules.

This object is used to ensure the payout can be legally and operationally executed in the destination country.

Error codes: required=400001, type=400002

transactionInformationobjectrequired

Represents the financial, operational, and processing configuration of the transaction.

Contains all parameters required to calculate, validate, route, and execute the transfer, including amounts, currencies, delivery method, funding source, fees, and payout instructions.

All fields are validated against business rules, compliance policies, and operational constraints before the transaction is accepted for processing.

Error codes: required=400001, type=400002

channelstring, [ 2 .. 60 ] characters

Identifies the integration channel used to create the transaction (API, Web, Messaging, etc.).

Error codes: type=400002, minLength=400003, maxLength=400004, allowedValues=400010

Enum:"API""WHATSAPP"

channelMetadataobject

Dynamic / Data considered relevant by the client for informational purposes for internal tracking

Error codes: type=400002

externalTransactionIdstring, [ 2 .. 60 ] characters

A unique identifier assigned to a transaction by an external system. This field is used to track, correlate, and reconcile transactions across different systems.

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

POST

/transaction/create

curl -i -X POST \
  https://sandbox-viablocks.viamericas.io/transaction/create \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: string' \
  -H 'x-secret-key: string' \
  -d '{
    "sender": {
      "firstName": "MARIO",
      "lastName": "LESTER",
      "phone": "3117852691",
      "phoneCountryCode": "+1",
      "email": "sender@example.com",
      "dateOfBirth": "1983-08-25",
      "addressStreet": "1517 W 12 PL, LOS ANGELES, CA, USA",
      "addressState": "US-CA",
      "addressCity": "LOS ANGELES",
      "addressCountry": "USA",
      "addressZipCode": "90015"
    },
    "beneficiary": {
      "firstName": "ANGEL",
      "lastName": "RESTADO",
      "phone": "3057118816",
      "phoneCountryCode": "+57",
      "addressStreet": "Cra 40t N. 13-34, Medellin, Colombia",
      "addressState": "CO-ANT",
      "addressCity": "MEDELLIN",
      "addressCountry": "COL",
      "addressZipCode": "05001"
    },
    "transactionInformation": {
      "originationCountryISO": "USA",
      "originationStateISO": "US-CA",
      "originationLocationCity": "LOS ANGELES",
      "originationAmount": 100,
      "originationCurrencyISO": "USD",
      "deliveryCountryISO": "COL",
      "deliveryStateISO": "CO-ANT",
      "deliveryAmountCurrencyISO": "COP",
      "deliveryLocationCode": "T060",
      "deliveryLocationNetwork": "BC0001",
      "deliveryLocationName": "BANCOLOMBIA",
      "deliveryLocationCity": "MEDELLIN",
      "deliveryMode": "C",
      "deliveryModeDetails": {
        "accountNumber": "24578183503",
        "accountType": "S"
      },
      "funding": {
        "type": "A",
        "accountNumber": "530000000",
        "routingNumber": 80
      }
    }
  }'

Responses

Response success

Bodyapplication/json

statusstring

Request status (success, error, etc.).

messagestring

Descriptive message about the operation result.

transaction_idstring

Unique identifier of the generated transaction.

transaction_uuidstring

Unique identifier of the generated transaction.

status_track_urlstring

URL where the user can track the transaction.

foliostring

Money transfer tracking number (optional)

total_receiverstring

Amount in destin currency that the customer is sending plus fees (optional)

total_pay_receiverstring

Amount in destination currency that the beneficiary is receiving (optional)

ratestring

Exchange rate (optional).

source_currency_amountstring

Amount in source currency that the customer is sending (optional).

payment_urlstring

URL where the user can complete the payment (optional)

required_document_listArray of objects

List of compliance document types required for this transaction to be fully processed. Each item is a code from the compliance engine.

Possible values:

KYC ΓÇö Full Know Your Customer form (identity, employment, document info)
KYC-Short ΓÇö Reduced KYC (document info only, no employer/SSN)
KYC-Long ΓÇö Extended KYC (document + employer, no SSN)
KYC-Gto ΓÇö GTO-specific KYC form
ID ΓÇö Identification document information (type, number, expiration, country)
Copy1ID ΓÇö Front image of the identification document
DOB ΓÇö Date of birth
SSN ΓÇö Social Security Number
SFunds ΓÇö Source of funds declaration
DPA ΓÇö Beneficiary address proof

If this array is empty, no additional documentation is required.

To fulfill these requirements, use the PUT /transaction/update endpoint with the corresponding fields.

document_requirementsArray of objects

Detailed fulfillment status for each compliance requirement. Shows whether each item from required_document_list was already satisfied with the data provided in this create request.

Each object contains:

type: The compliance document code (matches required_document_list)
fulfilled: Boolean indicating if all required fields for this type were provided
status: Human-readable status (completed or pending)
missing: (Only when pending) Array of field paths that were not provided

Use this to determine which fields need to be submitted via PUT /transaction/update.

idSenderGlobalstring

UUID of the sender created/linked for this transaction.

branch_idstring

Branch ID where the transaction was created.

Response

{
  "status": "success",
  "message": "Transaction created successfully",
  "transaction_uuid": "xxxxxx-xxxxx-xxx-xxxx-xxxxx",
  "transaction_id": "xxxxxx-8",
  "folio": "123456789",
  "total_receiver": "46.6200",
  "total_pay_receiver": "46.6200",
  "source_currency_amount": "840.0000",
  "rate": "0.0555",
  "status_track_url": "https://status-track.viamericas.io/?token=xxxxxx-xxxxx-xxx-xxxx-xxxxx",
  "required_document_list": [
    "Copy1ID",
    "DOB",
    "ID"
  ],
  "document_requirements": [
    { … },
    { … },
    { … }
  ]
}