Bulk Currency Conversion

Prerequisites

Before creating currency exchanges, ensure you have:

Valid API credentials with currency exchange permissions .
Active account numbers for both source and destination currencies.
Sufficient balance in your source currency account.

⚠️
Important
You can pre-generate exchange rate quotes using our Currency Exchange Quote API and lock in rates by including the exchangeRateToken in your bulk request.

API Endpoint

To create bulk exchanges, send a POST request to the Create Bulk FX Conversion endpoint.

Endpoint

POST https://api.stage.localpayment.com/currency-exchange

Authentication

Include your access token in all API requests:

Authorization: Bearer <your_access_token>

Key Request Parameters

Parameter	Type	Description
`externalId`	string	Unique identifier for your transaction
`country`	string	ISO country code
`currency`	string	Base currency code
`account.debited`	object	Source account details
`account.credited`	object	Destination account details

Example Request (Argentina)

curl --request POST \
     --url https://api.stage.localpayment.com/currency-exchange \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "country": "ARG",
       "currency": "ARS", 
       "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
       "account": {
         "debited": {
           "currency": "ARS",
           "accountNumber": "111.111.11111111", 
           "amount": 10000
         },
         "credited": {
           "currency": "EUR",
           "accountNumber": "000.111.11111111"
         }
       }
     }'

Response Handling

Success Response

A successful currency exchange returns transaction details:

{
  "transactionType": "CurrencyExchange",
  "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
  "internalId": "8888ad65-aa6e-4643-b9ba-ff62318fd90b", 
  "country": "ARG",
  "currency": "ARS",
  "exchangeRateToken": "",
  "clientCode": "0005",
  "creationDate": "2023-03-21T21:25:14.533+00:00",
  "errors": [],
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "CURRENCY EXCHANGE"
  },
  "account": {
    "debited": {
      "currency": "ARS", 
      "accountNumber": "111.111.11111111",
      "amount": 10000
    },
    "credited": {
      "currency": "EUR",
      "accountNumber": "000.111.11111111", 
      "amount": 44.52
    },
    "appliedFx": 224.54
  }
}

Key Response Fields

Field	Description
`internalId`	System-generated transaction ID for tracking
`status.code`	Current transaction status code
`account.appliedFx`	Exchange rate applied to the conversion
`account.credited.amount`	Final converted amount

Error Response

Insufficient Funds

{
  "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
  "internalId": "6fc7e955-7704-4558-8a05-6f4a2c3d9b45",
  "errors": [
    {
      "code": "101",
      "detail": "Insufficient funds in source account"
    }
  ],
  "status": {
    "code": "101", 
    "description": "REJECTED",
    "detail": "Insufficient funds in source account"
  }
}

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 Endpoint

Query transaction status programmatically. Useful for polling or recovering lost webhook notifications.

Dashboard View

Visual interface for monitoring transactions. Great for manual oversight and detailed transaction analysis.

Status Lifecycle

Code	Status	Description
`103`	APPROVED	The currency exchange was approved
`200`	COMPLETED	The currency exchange was finished
`303`	REJECTED	This exchange rate token has expired.

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

Advanced Features

Using Exchange Rate Quotes

Lock in favorable rates by pre-generating quotes:

Generate Quote: Call the Currency Exchange Quote API
Get Token: Extract the exchangeRateToken from the response
Apply Token: Include token in your bulk exchange request

{
  "exchangeRateToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
  "account": {
    // ... rest of request
  }
}

Bulk Processing Tips

Performance Optimization

Batch requests: Group multiple exchanges into single API calls when possible.
Rate limiting: Implement exponential backoff for high-volume processing.
Webhook handling: Use webhooks instead of polling for status updates.
Error retry logic: Implement smart retry mechanisms for temporary failures.

Testing & Validation

Sandbox Environment

Test your integration in our sandbox environment:

POST https://api.sandbox.localpayment.com/currency-exchange

Test Scenarios

Validate these scenarios before going live:

Successful currency exchange with valid accounts
Error handling for insufficient funds
Exchange rate token expiration
Invalid account number handling
Network timeout scenarios
Webhook notification processing

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.