Skip to content
API Reference/
Money Transfer
/
/Sender

Sender

This section provides the Sender 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

sender/id-upload

Request

Purpose

Upload sender identification document images (front and optionally back) for KYC processing.

When to Use

Use this endpoint when you need to:

  • Upload the sender's ID document image after creating a transaction
  • Submit both front and back images of the identification document
  • Fulfill KYC requirements for sender verification

Authentication

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

How It Works

  1. The uuid field identifies the sender (idSenderGlobal) — the same UUID returned when creating the sender
  2. The sender is validated against the Customer DynamoDB table
  3. documentType + documentCountry are validated against the KYC identifications catalog to confirm the document is accepted and to determine whether the back image is required
  4. Images are forwarded to the Viacheck processing Lambda for storage and verification
  5. On success, returns a confirmation message

Notes

  • documentType must be a code accepted for documentCountry (e.g., DL, PA, CL)
  • documentCountry is the document's issuing country in ISO 3166-1 alpha-3 format (e.g., USA, MEX)
  • frontImage is always required; backImage is required only when the document type/country requires the back side (per the identifications catalog)
  • Images can be sent as raw base64 or data URI format (data:image/png;base64,...)

Common Errors

  • 400000 - Invalid JSON format or image upload failed
  • 400001 - Missing required field (uuid, documentType, documentCountry, documentNumber, frontImage, or backImage when required)
  • 400010 - documentType is not accepted for the given documentCountry
  • 401000 - Invalid credentials
  • 403001 - Partner not authorized for this endpoint
  • 404002 - Sender not found for the given UUID
  • 500000 - Internal server error
Headers
x-client-idstring, [ 16 .. 64 ] charactersrequired

Unique identifier assigned to the integrating client.

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.

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

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

Sender's unique identifier (idSenderGlobal). This is the same UUID returned when the sender was created via transaction/create. The sender is validated against the Customer table before processing.

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

documentTypestring, [ 1 .. 4 ] characters^[A-Za-z]{1,4}$required

Identification document type code (e.g., DL, PA, CL). Must be a document type accepted for the given documentCountry according to the KYC identifications catalog. Determines whether the back image is required.

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

documentCountrystring, = 3 characters^[A-Za-z]{3}$required

Document country in ISO 3166-1 alpha-3 format (e.g., USA, MEX, COL). Used together with documentType to validate the document and resolve image requirements.

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

documentNumberstring, [ 1 .. 30 ] characters^[A-Za-z0-9\-]+$required

Sender's identification document number (e.g., driver's license, passport, national ID). Must match the documentNumber used in transaction/create.

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

frontImagestring, >= 100 characters^(?:data:image\/[a-zA-Z+]+;base64,)?[A-Za-z0-...required

Front image of the identification document encoded in base64. Accepts raw base64 or data URI (data:image/png;base64,...).

Error codes: required=400001, type=400002, minLength=400003, pattern=400009

backImagestring, >= 100 characters^(?:data:image\/[a-zA-Z+]+;base64,)?[A-Za-z0-...

Back image of the identification document encoded in base64. Optional — required only for document types that need back side capture (e.g., driver's license). Accepts raw base64 or data URI (data:image/png;base64,...).

Error codes: type=400002, minLength=400003, pattern=400009

POST
/sender/id-upload
curl -i -X POST \
  https://sandbox-viablocks.viamericas.io/sender/id-upload \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: string' \
  -H 'x-secret-key: string' \
  -d '{
    "uuid": "4ed19e29-5a6a-433d-908d-23377fabb617",
    "documentType": "PA",
    "documentCountry": "MEX",
    "documentNumber": "PA12345678",
    "frontImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }'

Responses

ID document uploaded successfully.

Bodyapplication/json
statusstring

Request status (success)

messagestring

Descriptive message about the operation result

Response
{
  "status": "success",
  "message": "The ID has been successfully uploaded"
}