Internal Foreign Transfer

This powerful feature streamlines international liquidity management, facilitates cross-border operations, and optimizes your global financial strategy.

Use Cases

Transform your international financial operations with these strategic applications:

Cross-Border Portfolio Rebalancing: Dynamically reallocate capital across international client portfolios to capitalize on global market opportunities and maintain strategic investment allocations across multiple countries and jurisdictions.
Global Liquidity Optimization: Centralize and redistribute cash positions across international operational accounts to maximize working capital efficiency and ensure seamless cross-border payments.
Multi-Country Fund Distribution: Automate budget allocation and fund disbursement to international subsidiaries, regional operations, or country-specific projects while maintaining centralized oversight and regulatory compliance.
International Regulatory Compliance: Strategically manage capital reserves and risk buffers across jurisdictions to meet diverse regulatory requirements, maintain adequate liquidity ratios, and ensure compliance with local banking regulations.

Prerequisites

Ensure your setup meets these requirements before initiating internal foreign transfers:

Sufficient Available Balance in your source account with adequate reserves for fees and taxes
Valid API Credentials with internal transfer permissions enabled
Multi-Country Account Verification for both source and destination accounts across different countries

⚠️
Important
Both accounts must be registered in the same curreny.

API Integration

To create Internal Foreign Transfer, send a POST request to the Create Internal Transfer endpoint.

Endpoint

POST https://api.stage.localpayment.com/api/internal-transfer

Authentication

All requests require secure bearer token authentication:

Authorization: Bearer <your_access_token>

Key Request Parameters

Parameter	Type	Description
`externalId`	string	Your unique transaction identifier for tracking
`country`	string	Source account ISO alpha-3 country code
`currency`	string	Source account ISO currency code
`amount`	number	Transfer amount
`transactionType`	string	Must be "InternalForeignTransfer"
`client.from.accountNumber`	string	Source account number
`client.to.accountNumber`	string	Destination account number (different country)

Request Example

curl --request POST \
     --url https://api.stage.localpayment.com/api/internal-transfer \
     --header 'Authorization: Bearer your_access_token' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "externalId": "IFT-2024-033214-05",
  "country": "ARG",
  "currency": "USD",
  "amount": 100.00,
  "transactionType": "InternalForeignTransfer",
  "client": {
    "type": "Client",
    "from": {
      "accountNumber": "032.840.00000005"
    },
    "to": {
      "accountNumber": "068.840.00000001"
    }
  }
}'

Response Handling

Our API provides comprehensive response data for effective transaction management and reconciliation.

Successful Transfer Response

{
  "transactionType": "InternalForeignTransfer",
  "externalId": "IFT-2024-033214-05",
  "internalId": "a70614fe-b76c-4f6c-9a5a-7144f2f7ea1f",
  "country": "ARG",
  "currency": "USD",
  "clientCode": "0001",
  "creationDate": "2024-03-23T00:38:30.828+00:00",
  "errors": [],
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "INTERNAL FOREIGN TRANSFER PROCESSED"
  },
  "amount": 100.00,
  "client": {
    "type": "Client",
    "from": {
      "accountNumber": "032.840.00000005"
    },
    "to": {
      "accountNumber": "068.840.00000001",
      "amount": 95.80
    }
  },
  "fees": {
    "description": "Cross-border transfer fee",
    "currency": "USD",
    "amount": 3.00,
    "account": "032.840.00000005"
  },
  "localTaxes": [
    {
      "code": "0001",
      "percentage": 1.2,
      "description": "International Debit Tax (IDC)",
      "currency": "USD",
      "amount": 1.20,
      "account": "032.840.00000005"
    }
  ],
  "withHoldings": []
}

Key Response Fields

Field	Purpose
`internalId`	System-generated UUID for transaction tracking and support
`status.code`	Transaction outcome: 200 (SUCCESS) or 702+ (ERROR)
`client.to.amount`	Net amount credited after fees and taxes
`fees.amount`	Total processing fees applied to source account
`localTaxes`	Detailed breakdown of applicable jurisdictional taxes
`creationDate`	UTC timestamp for precise transaction timing

Error Response Handling

Robust error handling with detailed diagnostic information:

{
  "externalId": "IFT-ERROR-123",
  "internalId": "fc2c831c-d0f1-41f6-8a59-0ecd426c087d",
  "errors": [
    {
      "code": "702",
      "detail": "Source account not configured for international transfers"
    },
    {
      "code": "703", 
      "detail": "Cross-border transfer requires different country accounts"
    },
    {
      "code": "704",
      "detail": "Insufficient funds: Available balance inadequate for transfer + fees"
    }
  ],
  "status": {
    "code": "702",
    "description": "REJECTED",
    "detail": "Pre-transfer validation failed"
  }
}

Transaction Status Tracking

Monitor your currency exchanges through multiple channels:

Webhooks (Recommended)

Receive real-time notifications when transaction status changes. Most efficient for production environments.

Status API

Query transaction status programmatically using the transaction ID. Perfect for status polling.

Dashboard

Visual monitoring interface with detailed transaction history and analytics.

Status Lifecycle

Code	Status	Description
`100`	InProgress	InProgress
`102`	PendingDebit	Pending Debit
`103`	PendingCredit	Pending Credit
`200`	Completed	INTERNAL TRANSFER
`704`	Rejected	Credited Account Not Exists

🗒️
Complete Reference
View all status codes in our Transaction Status Documentation.

Resources & Next Steps

Maximize your integration success with these essential resources

Webhook Integration

Set up real-time notifications for transaction status updates.

Reporting Dashboard

Access detailed analytics, reporting tools, and reconciliation features.

Transaction Monitoring

Learn to query transaction status and implement comprehensive tracking.

API Reference

Complete endpoint documentation with interactive examples.

✅
Pro Tip
Always test your workflow in our sandbox environment before deploying to production. This ensures your error handling, webhook processing, and status tracking work correctly across all scenarios.

🎧
Need Help?
Contact our support team if you experience any issues or need assistance for integration.