Submit Settlement Proof

Upload an Excel file to bulk import settlement data for a drawdown intent. The system parses the Excel file and automatically creates:

• Drawdown intents
• Corridors
• Routes
• Settlement proofs

This endpoint only accepts Excel files (.xlsx or .xls).

Important Validation Rules

• Drawdown ID Match: The drawdown_id (loan_request_id) value in the Excel file’s Drawdowns sheet must exactly match the drawdownId parameter in the URL path.
• Amount Consistency: The drawdown intent amount in the Excel file must match the amount of the corresponding loan request.
• Amount Reconciliation: The sum of all allocation_amount values across corridors, and the sum of all amount values across routes, must equal the total drawdown amount.

Required Excel Sheets

The Excel file must contain exactly four sheets with the following structure:

1. Drawdowns Sheet

Column	Description
intent_submission_id	Unique identifier for the intent submission
drawdown_id (loan_request_id)	The drawdown ID (must match path parameter)
amount	Drawdown amount
currency	Currency code (e.g., USD, EUR)

2. Corridors Sheet

Column	Description
corridor_id	Unique identifier for the corridor
intent_submission_id	Reference to the drawdown
intent_code	Intent code
origin_country	Origin country code
destination_country	Destination country code
allocation_amount	Amount allocated to this corridor
allocation_currency	Currency for the allocation
expected_settlement_at	Expected settlement timestamp (ISO-8601)
additional_fields	Optional JSON object with extra data

3. Routes Sheet

Column	Description
route_id	Unique identifier for the route
corridor_id	Reference to the corridor
rail_type	Type of payment rail
provider	Payment provider
source_instrument	Source instrument (JSON or “type:id” format)
dest_instrument	Destination instrument (JSON or “type:id” format)
source_currency	Source currency code
dest_currency	Destination currency code
amount	Route amount
expected_at	Expected completion timestamp

4. Docs Sheet

Column	Description
proof_id	Unique identifier for the proof (idempotency key)
route_id	Reference to the route
doc_type	Document type (see supported types below)
mime_type	MIME type of the document
url	URL where the document is stored
recorded_at	Timestamp when proof was recorded (ISO-8601)
hash_sha256	Optional SHA-256 hash for integrity verification
metadata	Optional JSON object with extra data

Supported Document Types

The doc_type column in the Docs sheet accepts these values:

• MT103 - SWIFT MT103 payment message
• WIRE_RECEIPT - Wire transfer receipt
• ACH_STATEMENT - ACH transaction statement
• SEPA_CONFIRMATION - SEPA transfer confirmation
• RTGS_ADVICE - Real-Time Gross Settlement advice
• MOBILE_EXPORT - Mobile money transaction export
• CARD_PROCESSOR_REPORT - Card processor report
• BLOCK_EXPLORER - Blockchain explorer screenshot/export
• BANK_STATEMENT - Bank account statement
• CEP - Comprobante Electronico de Pago (Mexican electronic payment receipt)

POST /api/v1/liquidity/utilization/upload-document/{drawdownId}

Submit Settlement Proof

cURL

curl --request POST \
  --url https://api.mansafinance.co/api/v1/liquidity/utilization/upload-document/{drawdownId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'

201

{
  "message": "Settlement data uploaded successfully",
  "drawdowns_created": 1,
  "corridors_created": 3,
  "routes_created": 5,
  "docs_created": 5
}

Authorizations

Authorization · string · header · required

JWT token following RFC001 specification

Path Parameters

drawdownId · string<uuid> · required

Unique identifier for the drawdown (UUID format). This ID must exist in the Drawdowns sheet of the uploaded Excel file.

Body

multipart/form-data

file · file · required

Excel file containing settlement data. Only the following formats are accepted:

• .xlsx (Excel 2007+)
• .xls (Excel 97-2003)

Other file types (PDF, PNG, JPG, etc.) will be rejected with a 400 error.

Response

201

application/json

Settlement data uploaded successfully

message · string · required

Success message confirming the upload

Example:

"Settlement data uploaded successfully"

drawdowns_created · integer · required

Number of drawdown records created from the Excel file

Example:

1

corridors_created · integer · required

Number of corridor records created from the Excel file

Example:

3

routes_created · integer · required

Number of route records created from the Excel file

Example:

5

docs_created · integer · required

Number of settlement proof documents created from the Excel file

Example:

5