/transaction/create

Overview (1.0.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

ViaBlocks API Outbound is a secure, server-to-server REST API that enables regulated partners to create, manage, and track outbound cross-border money transfers from the United States to international destinations through the Viamericas network.

The API supports the full outbound transaction lifecycle, including U.S.-based sender onboarding, international beneficiary onboarding, transaction creation, funding initiation, foreign exchange (FX) handling, payout execution, and end-to-end status monitoring.

Partners interact with the platform through two primary endpoints: POST /transaction/create, used to submit sender, beneficiary, and transfer details to initiate an outbound transaction, and POST /transaction/status, used to retrieve the most recent processing status and lifecycle updates for an existing transaction.

This API is designed for licensed and compliant U.S. partners and abstracts regulatory, compliance, routing, and payout complexities, allowing integrators to focus on building scalable international money transfer experiences.

Overview

Contact

viablocks-support@viamericas.com

Servers

Sandbox environment

https://sandbox-viablocks.viamericas.io

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

Request

Purpose

Creates a new outbound cross-border money transfer and registers it in the ViaBlocks platform.

This request defines the sender, beneficiary, transaction details (amounts, currencies, destination), and the selected funding method.

When to use

Use this endpoint to initiate a new transaction 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 (partner-dependent).
Remote payment funding: Transaction is created in a pending funding state. The sender must complete payment remotely and the transaction will not proceed until funding and risk/compliance review are completed.

Authentication

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

Notes

Request validation is enforced for formats, allowed values, corridor rules, and compliance requirements.
For the remote payment flow, refer to: ../guides/remotepayment.md

Common errors

400 Validation errors (missing/invalid fields)
401 Invalid credentials
404 Sender/beneficiary linkage issues (when applicable)
422 Business-rule rejection (e.g., credit limit)
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

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

sender.firstNamestring[ 2 .. 60 ] charactersrequired

Sender’s given (first) name as it appears on their official identification document. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

sender.middleNamestring[ 2 .. 60 ] characters

Sender’s middle name, if applicable. Error codes: type=400002, minLength=400003, maxLength=400004

sender.lastNamestring[ 2 .. 60 ] charactersrequired

Sender’s primary family name (surname). Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

sender.secondLastNamestring[ 2 .. 60 ] characters

Sender’s second family name, used in some countries. Error codes: type=400002, minLength=400003, maxLength=400004

sender.phonestring[ 10 .. 15 ] charactersrequired

Sender’s phone number without country code. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

sender.phoneCountryCodestring[ 2 .. 4 ] charactersrequired

International dialing code of the sender’s phone number Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

Value"+1"

sender.emailstring(email)[ 5 .. 60 ] charactersrequired

Sender’s email address used for notifications and transaction updates. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, format=400005

sender.addressStreetstring[ 2 .. 60 ] characters^[0-9]+\s[\w\s.,-]+$required

Sender address. Structure: [Description, city name, State ISO2 zipCode, Country ISO3]. Example:'54545 Salo Rd, Hancock, MI 49930, USA' Regular expression: ^[0-9]+\s[\w\s.,-]+$ Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, pattern=400009

sender.addressStatestring[ 2 .. 6 ] charactersrequired

Sender state (ISO 2). https://en.wikipedia.org/wiki/ISO_3166-2 Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

Enum"US-AL""US-AK""US-AZ""US-AR""US-CA""US-CO""US-CT""US-DE""US-FL""US-GA"

sender.addressCitystring[ 2 .. 60 ] charactersrequired

City name of the sender’s residence. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

sender.addressCountrystring[ 2 .. 3 ] charactersrequired

Sender country (ISO 3). https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

Value"USA"

sender.addressZipCodestring[ 5 .. 6 ] charactersrequired

Postal or ZIP code of the sender’s address. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

sender.documentTypestring[ 2 .. 3 ] characters

You can check the types of documents available according to your document country in our catalogs API Catalogs Endpoint Identifications or review the following table with standard document types Type of identification document provided by the sender (e.g., Passport, National ID).

Document types (documentType) — click to expand

Code	Document Type	Description
BD	BORDER CROSSING CARD	Border crossing card used to enter certain countries without a passport.
BF	CPF/CNPJ	Brazilian tax registry for individuals (CPF) and legal entities (CNPJ).
CA	CARTEIRA DE IDENTIDADE	Identity document issued in Brazil.
CC	CÉDULA CIUDADANÍA	Identification document in Colombia.
CE	CÉDULA DE IDENTIDAD Y ELECTORAL	Identity document used in the Dominican Republic.
CI	CÉDULA DE IDENTIDAD	Identity document issued in various Latin American countries.
CL	CREDENCIAL DE ELECTOR	Voter identification document used in Mexico.
CN	CERTIFICATE OF NATURALIZATION	Naturalization certificate that grants citizenship in the U.S. or other countries.
CP	CADASTRO DE PESSOAS FÍSICAS (CPF)	Tax registry for individuals in Brazil.
CR	CREW LANDING PERMIT & BADGE	Landing permit for aircraft crew members.
CV	CÉDULA DE VECINDAD	Identity document in Guatemala.
CZ	CERTIFICATE OF CITIZENSHIP	Citizenship certificate issued by national governments.
DI	DOCUMENTO NACIONAL DE IDENTIDAD (DNI)	Identity document in Argentina, Spain, and other countries.
DL	DRIVER'S LICENSE	Driver's license.
DN	DOCUMENTO NACIONAL	National identity document.
DU	DOCUMENTO ÚNICO DE IDENTIDAD (DUI)	Identity document in El Salvador.
EA	EMPLOYMENT AUTHORIZATION	Employment authorization document in the U.S.
GC	GREEN CARD	Permanent residence card in the U.S.
GI	GOVERNMENT IDENTIFICATION	Identification issued by the government for its citizens.
IC	CÉDULA DE IDENTIDAD CIVIL	Civil identity document in several countries.
ID	IDENTIFICATION CARD	General identification card.
LD	DRIVER'S LICENSE	Driver's license.
LE	LIBRETA ELECTORAL	Electoral document in Peru.
LP	LEARNER PERMIT	Learner's permit for driving.
MC	MATRÍCULA CONSULAR	Identity document issued by consulates to citizens abroad.
MI	MILITARY ID	Military identification.
NN	NONE	No identity document required.
OI	OFFICIAL ID (POLICE, FIRE, ETC)	Official identification for police, firefighters, etc.
OT	OTHER	Other type of identity document.
PA	PASSPORT	Passport issued by a government.
PC	PASSPORT CARD	Passport card used in the U.S. for certain international travel.
PP	PASAPORTE	Passport.
PR	PERMANENT RESIDENT CARD	Permanent residence card in some countries.
RA	RESIDENT ALIEN	Document for a foreign resident.
SI	STATE ISSUED ID	Identification issued by a state or province.
SS	SSN	Social Security Number (U.S.).
TI	TARJETA DE IDENTIDAD	Identity card in some Latin American countries.
TR	TARJETA DE REGISTRO CONSULAR	Consular registration card for citizens abroad.
VI	VISA	Entry visa for a country.

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

sender.documentDescriptionstring[ 0 .. 60 ] characters

Human-readable description of the identification document. Error codes: type=400002, minLength=400003, maxLength=400004

sender.documentNumberstring[ 2 .. 60 ] characters

Identification document number. Error codes: type=400002, minLength=400003, maxLength=400004

sender.documentExpirationDatestring[ 8 .. 10 ] characters

Expiration date of the identification document. Format: YYYY-MM-DD Error codes: type=400002, minLength=400003, maxLength=400004, format=400005

sender.documentCountrystring[ 2 .. 3 ] characters

Sender country (ISO 3). https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 Error codes: type=400002, minLength=400003, maxLength=400004

sender.dateOfBirthstring[ 8 .. 10 ] charactersrequired

Sender’s date of birth, used for identity verification and compliance checks. Format: YYYY-MM-DD Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, format=400005

sender.ssnNumberstring[ 2 .. 60 ] characters

The individual’s Social Security Number (SSN), a nine-digit numeric identifier issued in the United States for tax reporting, employment, and official identification purposes. Error codes: type=400002, minLength=400003, maxLength=400004

sender.industrynumber[ 2 .. 60 ] characters

Unique identifier referencing the industry classification assigned to the entity, as defined in the organization’s official, property or key "id" in our catalogs API \ Catalogs Endpoint Industry Error codes: type=400002, minLength=400003, maxLength=400004

sender.jobnumber[ 2 .. 60 ] characters

Unique identifier representing the specific job or position assigned to the individual, as defined in the organization’s official job catalog, property or key "jobs" It contains a list of items with the "id" property in our catalogs API \ Catalogs Endpoint Industry Error codes: type=400002, minLength=400003, maxLength=400004

sender.occupationstring[ 2 .. 60 ] characters

Sender’s occupation or professional activity, This refers to the name of our list of available jobs based on the industry you select It contains a list of items with the "name" property. in our catalogs API \ Catalogs Endpoint Industry Error codes: type=400002, minLength=400003, maxLength=400004

sender.employerstring[ 2 .. 60 ] characters

Legal name of the organization or individual that employs the person, as registered for official, tax, and administrative purposes. Error codes: type=400002, minLength=400003, maxLength=400004

sender.employerPhonestring[ 2 .. 60 ] characters

Primary contact phone number of the employer, including country and area code, used for official communication and verification purposes.. Error codes: type=400002, minLength=400003, maxLength=400004

sender.proofOfIncomestring[ 2 .. 60 ] characters

Description of the sender’s source of income or supporting documentation. Error codes: type=400002, minLength=400003, maxLength=400004

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

beneficiary.firstNamestring[ 2 .. 60 ] charactersrequired

Beneficiary’s given name. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

beneficiary.middleNamestring[ 2 .. 60 ] characters

Beneficiary’s middle name, if applicable. Error codes: type=400002, minLength=400003, maxLength=400004

beneficiary.lastNamestring[ 2 .. 60 ] charactersrequired

Beneficiary’s primary family name. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

beneficiary.secondLastNamestring[ 2 .. 60 ] characters

Beneficiary’s second family name. Error codes: type=400002, minLength=400003, maxLength=400004

beneficiary.phonestring[ 10 .. 15 ] charactersrequired

Beneficiary’s phone number without country code. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

beneficiary.phoneCountryCodestring[ 2 .. 4 ] charactersrequired

International dialing code of the beneficiary’s phone number. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

Value"+57"

beneficiary.addressStreetstring[ 2 .. 60 ] charactersrequired

Beneficiary address. Structure: [Description, city name, State ISO2 zipCode, Country ISO3]. Example:'54545 Salo Rd, Hancock, MI 49930, USA' Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

beneficiary.addressStatestring[ 2 .. 6 ] charactersrequired

Beneficiary state (ISO 2). https://en.wikipedia.org/wiki/ISO_3166-2 Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

beneficiary.addressCitystring[ 2 .. 60 ] charactersrequired

City name of residence of the beneficiary. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

beneficiary.addressCountrystring[ 2 .. 3 ] charactersrequired

Beneficiary country (ISO 3). https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

beneficiary.addressZipCodestring[ 5 .. 6 ] characters

Postal or ZIP code of the beneficiary’s address. Error codes: type=400002, minLength=400003, maxLength=400004

beneficiary.documentTypestring[ 2 .. 3 ] characters

Document types (documentType) — click to expand

Code	Document Type	Description
BD	BORDER CROSSING CARD	Border crossing card used to enter certain countries without a passport.
BF	CPF/CNPJ	Brazilian tax registry for individuals (CPF) and legal entities (CNPJ).
CA	CARTEIRA DE IDENTIDADE	Identity document issued in Brazil.
CC	CÉDULA CIUDADANÍA	Identification document in Colombia.
CE	CÉDULA DE IDENTIDAD Y ELECTORAL	Identity document used in the Dominican Republic.
CI	CÉDULA DE IDENTIDAD	Identity document issued in various Latin American countries.
CL	CREDENCIAL DE ELECTOR	Voter identification document used in Mexico.
CN	CERTIFICATE OF NATURALIZATION	Naturalization certificate that grants citizenship in the U.S. or other countries.
CP	CADASTRO DE PESSOAS FÍSICAS (CPF)	Tax registry for individuals in Brazil.
CR	CREW LANDING PERMIT & BADGE	Landing permit for aircraft crew members.
CV	CÉDULA DE VECINDAD	Identity document in Guatemala.
CZ	CERTIFICATE OF CITIZENSHIP	Citizenship certificate issued by national governments.
DI	DOCUMENTO NACIONAL DE IDENTIDAD (DNI)	Identity document in Argentina, Spain, and other countries.
DL	DRIVER'S LICENSE	Driver's license.
DN	DOCUMENTO NACIONAL	National identity document.
DU	DOCUMENTO ÚNICO DE IDENTIDAD (DUI)	Identity document in El Salvador.
EA	EMPLOYMENT AUTHORIZATION	Employment authorization document in the U.S.
GC	GREEN CARD	Permanent residence card in the U.S.
GI	GOVERNMENT IDENTIFICATION	Identification issued by the government for its citizens.
IC	CÉDULA DE IDENTIDAD CIVIL	Civil identity document in several countries.
ID	IDENTIFICATION CARD	General identification card.
LD	DRIVER'S LICENSE	Driver's license.
LE	LIBRETA ELECTORAL	Electoral document in Peru.
LP	LEARNER PERMIT	Learner's permit for driving.
MC	MATRÍCULA CONSULAR	Identity document issued by consulates to citizens abroad.
MI	MILITARY ID	Military identification.
NN	NONE	No identity document required.
OI	OFFICIAL ID (POLICE, FIRE, ETC)	Official identification for police, firefighters, etc.
OT	OTHER	Other type of identity document.
PA	PASSPORT	Passport issued by a government.
PC	PASSPORT CARD	Passport card used in the U.S. for certain international travel.
PP	PASAPORTE	Passport.
PR	PERMANENT RESIDENT CARD	Permanent residence card in some countries.
RA	RESIDENT ALIEN	Document for a foreign resident.
SI	STATE ISSUED ID	Identification issued by a state or province.
SS	SSN	Social Security Number (U.S.).
TI	TARJETA DE IDENTIDAD	Identity card in some Latin American countries.
TR	TARJETA DE REGISTRO CONSULAR	Consular registration card for citizens abroad.
VI	VISA	Entry visa for a country.

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

beneficiary.documentNumberstring[ 2 .. 60 ] characters

Identification document number of the beneficiary. Error codes: type=400002, minLength=400003, maxLength=400004

beneficiary.documentDescriptionstring[ 2 .. 60 ] characters

Identification document number of the beneficiary. Error codes: type=400002, minLength=400003, maxLength=400004

beneficiary.documentCountrystring[ 2 .. 3 ] characters

Country that issued the beneficiary’s identification document. Error codes: type=400002, minLength=400003, maxLength=400004

beneficiary.relationShipstring[ 2 .. 60 ] characters

Relationship between sender and beneficiary (e.g., Family, Friend, Business). Error codes: type=400002, minLength=400003, maxLength=400004

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

transactionInformation.deliveryModestring= 1 charactersrequired

Defines the payout execution method and destination details for the transaction.

Specifies how and where the funds will be delivered to the beneficiary (e.g., cash pickup, bank deposit, walletcredit, or home delivery), including all routing and operational parameters required to complete the payout.

Delivery mode

Code	Delivery Mode	Description
P	Cash Pickup	Cash withdrawal at an authorized location.
C	Bank Deposit	Direct deposit to a bank account.
O	Mobile Wallet	Deposit to a mobile wallet.
D	Home Delivery	Cash delivered to the recipient’s address.
U	Undefined	Undefined

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

Enum"O""C""P""D""U"

transactionInformation.deliveryModeDetailsobjectrequired

Contains the bank account and routing information required to execute the payout to the beneficiary. This object defines the destination financial institution and account where the funds will be deposited, including account number, account type, routing number, and bank details. All fields are validated against country-specific banking rules and payout network requirements before the transaction is released for payment. Error codes: required=400001, type=400002

transactionInformation.deliveryModeDetails.accountNumberstring[ 6 .. 60 ] characters

Destination account number. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

transactionInformation.deliveryModeDetails.accountAuxiliaryFieldstring[ 6 .. 60 ] characters

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

transactionInformation.deliveryModeDetails.accountTypestring= 1 characters

Delivery mode used for the transaction.

Account types

Code	Account Type	Description
S	Saving	Savings account
C	Checking	Checking account
U	Undefined	Undefined

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

Enum"S""C""U"

transactionInformation.deliveryModeDetails.routingNumberstring[ 9 .. 60 ] characters

Bank routing or clearing number Error codes: type=400002, minLength=400003, maxLength=400004

transactionInformation.deliveryModeDetails.bankstring[ 6 .. 60 ] characters

Name of the receiving bank. Error codes: type=400002, minLength=400003, maxLength=400004

transactionInformation.fundingobject

Defines the source of funds and funding method used to initiate the transaction. Contains the payment instrument and funding configuration (e.g., cash, debit card, bank account, wallet), and is used to validate, authorize, and register the financial charge before the transaction is processed. Error codes: type=400002

transactionInformation.originationCountryISOstring[ 2 .. 6 ] charactersrequired

Origin country (ISO 3). https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

Value"USA"

transactionInformation.originationStateISOstring[ 2 .. 6 ] charactersrequired

Origin state (ISO 2). https://en.wikipedia.org/wiki/ISO_3166-2 Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

Enum"US-AL""US-AK""US-AZ""US-AR""US-CA""US-CO""US-CT""US-DE""US-FL""US-GA"

transactionInformation.originationLocationCitystring[ 2 .. 60 ] charactersrequired

City where the transaction is initiated. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

transactionInformation.originationAmountnumber>= 0required

Amount of money sent in the origination currency. Error codes: required=400001, type=400002, minimum=400006, decimal=400008

transactionInformation.originationCurrencyISOstring[ 2 .. 6 ] charactersrequired

Origin currency (ISO). https://en.wikipedia.org/wiki/ISO_4217 Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

Value"USD"

transactionInformation.exchangeRatenumber>= 0required

Amount of money sent in the origination currency. Error codes: required=400001, type=400002, minimum=400006, decimal=400008

transactionInformation.feenumber>= 0required

Transaction service fee charged for processing the remittance. Error codes: required=400001, type=400002, minimum=400006, decimal=400008

transactionInformation.deliveryCountryISOstring[ 2 .. 6 ] charactersrequired

Delivery country (ISO 3). https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

transactionInformation.deliveryStateISOstring[ 2 .. 6 ] charactersrequired

Delivery state (ISO 2). https://en.wikipedia.org/wiki/ISO_3166-2 Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

transactionInformation.deliveryAmountnumber>= 0required

Amount to be delivered in the destination currency. Error codes: required=400001, type=400002, minimum=400006, decimal=400008

transactionInformation.deliveryAmountCurrencyISOstring[ 2 .. 6 ] charactersrequired

Delivery currency (ISO). https://en.wikipedia.org/wiki/ISO_4217 Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

transactionInformation.deliveryLocationCodestring[ 2 .. 30 ] charactersrequired

Identifier of the delivery location selected from the list provided by our API catalog. The value must correspond to the idPayer key of the selected item in the catalog response. in our catalogs API Catalogs Endpoint payouts Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

transactionInformation.deliveryLocationNetworkstring[ 2 .. 30 ] charactersrequired

Identifier of the delivery network associated with the selected delivery location. This value is filtered based on the deliveryLocationCode and must correspond to the PaymentLocationCode key of the matching item in the API catalog response. Catalogs Endpoint payouts Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

transactionInformation.deliveryLocationNamestring[ 2 .. 30 ] charactersrequired

Name of the delivery location associated with the selected delivery location. This value is filtered based on the deliveryLocationCode and must correspond to the PaymentLocationName key of the matching item in the API catalog response. Catalogs Endpoint payouts Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, allowedValues=400010

transactionInformation.deliveryLocationCitystring[ 2 .. 60 ] charactersrequired

City where the funds will be delivered. Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

transactionInformation.sourceOfFoundsstring[ 2 .. 60 ] characters

Declared source of funds used to finance the remittance (e.g., salary, savings, business income). This information may be required for compliance (KYC/AML) depending on the client configuration, corridor, or transaction amount thresholds. Identifier representing the origin of the funds, selected from the list provided by the Catalogs Endpoint funds origin API endpoint. The value must correspond to the id key of the selected item in the catalog response. Error codes: type=400002, minLength=400003, maxLength=400004

transactionInformation.remittancePurposestring[ 2 .. 60 ] characters

Declared purpose of the remittance, describing why the funds are being sent (e.g., family support, education, medical expenses, rent, personal transfer). This can be used for compliance classification, reporting, and corridor-specific regulatory requirements. Identifier representing the purpose of the remittance, selected from the corresponding catalog provided by the API. The value must match the id key of the selected item in the catalog response. Catalogs Endpoint wire purpose API endpoint. Error codes: type=400002, minLength=400003, maxLength=400004

channelstring[ 2 .. 60 ] charactersrequired

Identifies the integration channel used to create the transaction (API, Web, Messaging, etc.). Error codes: required=400001, 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

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",
      "middleName": "",
      "lastName": "LESTER",
      "secondLastName": "",
      "phone": "3117852691",
      "phoneCountryCode": "+1",
      "email": "notificationsviablocks@gmail.com",
      "dateOfBirth": "1983-08-25",
      "addressStreet": "1517 1-2 W 12 PL, LOS ANGELES, CA, USA",
      "addressState": "US-CA",
      "addressCity": " LOS ANGELES",
      "addressCountry": "USA",
      "addressZipCode": "90015",
      "documentType": "PA",
      "documentDescription": "PASSPORT",
      "documentNumber": "FF01231167855",
      "documentState": "US-CA",
      "documentCountry": "USA",
      "ssnNumber": 12345789,
      "industry": 7,
      "job": 107,
      "occupation": "DRIVER",
      "employer": "UBER DRIVER",
      "employerPhone": 5201010101,
      "proofOfIncome": "NOT APPLICABLE"
    },
    "beneficiary": {
      "firstName": "Leidy Yuliana",
      "middleName": "",
      "lastName": "Ruiz cardenas",
      "secondLastName": "",
      "phone": "555-555-5555",
      "phoneCountryCode": "+57",
      "email": "notificationsviablocks@gmail.com",
      "addressStreet": "Cra 40t N. 13-34, Medellin, Colombia",
      "addressState": "CO-ANT",
      "addressCity": "MEDELLIN",
      "addressCountry": "COL",
      "addressZipCode": "33131"
    },
    "transactionInformation": {
      "originationCountryISO": "USA",
      "originationStateISO": "US-CA",
      "originationLocationCity": "LOS ANGELES",
      "originationAmount": 1,
      "originationCurrencyISO": "USD",
      "deliveryCountryISO": "COL",
      "deliveryStateISO": "CO-ANT",
      "deliveryAmountCurrencyISO": "COP",
      "deliveryLocationCode": "T060",
      "deliveryLocationNetwork": "BC0001",
      "deliveryLocationName": "BANCOLOMBIA",
      "deliveryLocationCity": "MEDELLIN",
      "deliveryMode": "C",
      "deliveryModeDetails": {
        "accountNumber": "24578183503",
        "routingNumber": 96016930,
        "accountType": "S",
        "bank": "USA BANK"
      },
      "funding": {
        "type": "A",
        "accountNumber": "530000000",
        "routingNumber": 80
      },
      "exchangeRate": 3827,
      "fee": 1.99,
      "deliveryAmount": 3827
    },
    "channel": "WHATSAPP",
    "channelMetadata": {
      "whatsapp_phone": "19257856424"
    }
  }'

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)

Response

application/json

{
  "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"
}

/transaction/status

Request

Purpose

Retrieves the latest status and processing details for a previously created transaction.

When to use

Use this endpoint to:

Poll for lifecycle updates (funding confirmation, compliance holds, payout progression)
Display current transaction state in your UI or partner system
Retrieve hold reasons and required documents (when applicable)

Authentication

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

How to identify the transaction

Provide the uuid query parameter. The uuid is returned by /transaction/create.

Notes

Responses may include holds and requiredDocumentList when compliance or operational review is required.
Status values reflect internal processing and payout execution steps.

Common errors

400 Missing/invalid uuid
401 Invalid credentials
404 Transaction not found
500 Internal error

Query

uuidstring[ 32 .. 60 ] charactersrequired

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

Example: uuid=xxxxxx-xxxxx-xxx-xxxx-xxxxx

Headers

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

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

Example: xxxx123456789

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

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

Example: xxxx987654321xxs

curl -i -X GET \
  'https://sandbox-viablocks.viamericas.io/transaction/status?uuid=xxxxxx-xxxxx-xxx-xxxx-xxxxx' \
  -H 'x-client-id: xxxx123456789' \
  -H 'x-secret-key: xxxx987654321xxs'

Responses

Response success

Bodyapplication/json

statusstring

Transaction status

Status	Description
VOID	The transaction has been voided and is no longer valid.
CANCEL	The transaction was cancelled before completion.
EXPIRED	The transaction was not completed within the allowed time window and has expired.
HOLD	The transaction is temporarily on hold due to compliance or operational review.
DONE	The transaction has completed its internal processing flow successfully.
SENDTOBANK	The transaction has been sent to the bank for processing.
PAID	The funds have been paid out to the beneficiary.
TRANSFERRED	The funds have been transferred to the payout network or external institution.

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

total_receiverstring

Amount in destin currency that the customer is sending plus fees

total_pay_receiverstring

Amount in destination currency that the beneficiary is receiving

ratestring

Exchange rate

source_currency_isostring

ISO currency code of the source (sending) amount. Represents the currency in which the sender funds the transaction.

currency_receiver_isostring

ISO currency code of the destination (receiving) amount. Represents the currency in which the beneficiary will receive the funds.

holdsArray of objects

List of compliance or operational holds applied to the transaction.

Each hold represents a restriction or review requirement that must be resolved before the transaction can proceed.

requiredDocumentListArray of objects

List of documents required to resolve compliance or regulatory requirements for the transaction.

This list is typically populated when the transaction requires additional verification or is placed on hold.

Response

application/json

{
  "transaction_uuid": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
  "status_track_url": "https://status-track.viamericas.io/?token=xxxxx-xxxx-xxxx-xxxx-xxxxx",
  "status": "HOLD",
  "folio": "1234567890",
  "source_currency_amount": 84000,
  "source_currency_iso": "MXN",
  "total_receiver": 84000,
  "total_pay_receiver": 4662,
  "currency_receiver_iso": "USD",
  "rate": 0.0555,
  "holds": [
    { … },
    { … },
    { … }
  ],
  "requiredDocumentList": [
    "Copy1ID",
    "Copy2ID",
    "DOB",
    "ID",
    "KYC",
    "SFunds",
    "SSN"
  ]
}

Catalogs

This section provides the **Catalogs** endpoints required to retrieve reference and configuration data necessary to construct and validate outbound money transfer transactions within the ViaBlocks platform.
Catalog endpoints expose corridor-specific operational data including supported countries, currencies, delivery methods, payout networks, payout locations, identification document types, industries, remittance purposes, and source-of-funds classifications.
These endpoints are read-only and must be consumed prior to transaction creation to ensure:

Compliance with country-specific regulatory requirements
Correct validation of amounts, currencies, and payout configurations
Dynamic population of UI selection fields
Alignment with real-time operational rules and payout network constraints

Partners should not hardcode catalog values and should instead retrieve them programmatically to maintain synchronization with configuration updates, compliance changes, and corridor availability.

Operations

Overview (1.0.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Transaction

/transaction/create

Request

Purpose

When to use

What happens next

Authentication

Notes

Common errors

Delivery mode

Account types

Responses

Was this helpful?

/transaction/status

Request

Purpose

When to use

Authentication

How to identify the transaction

Notes

Common errors

Responses

Was this helpful?

Catalogs

Overview (1.0.0)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

Transaction

/transaction/create

RequestExpand all

Purpose

When to use

What happens next

Authentication

Notes

Common errors

Delivery mode

Account types

Responses

Was this helpful?

/transaction/status

Request

Purpose

When to use

Authentication

How to identify the transaction

Notes

Common errors

Responses

Was this helpful?

Catalogs

Overview (1.0.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Request