Skip to content
API Reference/
/
/
/transaction/create

/transaction/create

Request

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
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": "JAMES",
      "lastName": "WHITFIELD",
      "dateOfBirth": "1988-07-22",
      "documentType": "PA",
      "documentDescription": "PASSPORT",
      "documentNumber": "GBR987654321"
    },
    "beneficiary": {
      "firstName": "SARAH",
      "lastName": "THOMPSON",
      "addressStreet": "742 Evergreen Terrace, Springfield, IL 62704, USA",
      "addressState": "US-IL",
      "addressCity": "SPRINGFIELD",
      "addressCountry": "USA",
      "addressZipCode": "62704"
    },
    "transactionInformation": {
      "originationCountryISO": "GBR",
      "originationAmount": 800,
      "originationCurrencyISO": "GBP",
      "deliveryCountryISO": "USA",
      "deliveryStateISO": "US-IL",
      "deliveryAmountCurrencyISO": "USD",
      "deliveryMode": "C",
      "deliveryModeDetails": {
        "accountNumber": "8812345670",
        "routingNumber": "071000013",
        "bank": "JPMORGAN CHASE"
      },
      "funding": {
        "type": "C"
      }
    },
    "externalTransactionId": "tx-012345"
  }'

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.

branch_idstring

Internal identifier for a specific branch within an organization.

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 strings

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
{
  "status": "success",
  "message": "Transaction created successfully",
  "transaction_uuid": "xxxxxx-xxxxx-xxx-xxxx-xxxxx",
  "transaction_id": "I99984-8",
  "branch_id": "I99984",
  "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"
}