HomeGuidesRecipesAPI Reference
Guides
Sign in
Start typing to search…

Conversions

Conversions allows you to transfer money across accounts with different currencies in the same country.

When it comes to Foreign Exchange (FX), you have two options:

  • Automated via API:
    • FX on Payment (DCC Dynamic currency conversion): When you operate an account nominated in USD and process payins and payouts in local currencies, the FX will be executed by our API real time 24/7. Use the Generate Currency Exchange Quote API to request an exchange quotation; this service will return a token that you can use later when you generate the currency exchange with the Currency Exchange Bulk API, and your quotation will be preserved in the transaction.
    • FX Bulk: When you operate accounts in multiple currencies, you can generate the currency exchange with the Currency Exchange Bulk API without any quotation, and the currency exchange rate will be taken as the current currency value.

  • Manual FX- Trading Desk (Panel):
    • FX on Settlement: When you operate an account nominated in local currencies to process payins and payouts, we will not perform automated DCC on each payment; debits or credits will occur in the same currency as the account is nominated. When you want to make a cross border (international settlement) deposit or a withdrawal, our trading desk can quote you FX to perform bulk currency exchanges and manage your local currency liquidity. Create a Currency Exchange using the Localpayment panel. The currency exchange rate for this choice is assigned as soon as you begin the conversion and will be available for the given period of time, which is displayed at the bottom of the page.

FX transactions are only available between the local currency and a hard currency, or vice versa. For example, USD to BRL or BRL to AUS.
The hard currencies available for realizing an FX are listed below:

  • AUD - Australian dollar
  • CAD - Canadian dollar
  • CHF - Swiss franc
  • EUR - Euro
  • GBP - Pound Sterling
  • NZD - New Zealand dollar
  • USD - United States dollar

📘

Note

If you need a hard currency that isn't on the list or want to verify if there is foreign exchange between two hard currencies available in a country, please contact your account manager or our support team .


Currency Exchange Quote

¿What is a Currency Exchange Quote?

Use the Generate Currency Exchange Quote API to obtain an exchange quote, and Localpayment will assign you a token that can be used in a subsequent transaction of the same type.

The exchange rate token can be set to have a lifetime ranging from 1 minute to 1 day, based on your Localpayment contract. The expiration is to request a transaction within that time range. The quoted FX will be considered once the transaction is generated using the exchange rate token. Once the payment is generated, it will have its own exchange rate expiration.


Prerequisites

Before requesting a currency exchange quote, you must have completed the following steps:


1. Environment access

You will need to conclude your onboarding process and your Stage login credentials or your Production credentials (if you are already certified) in order to create a payment via API or Panel.

⚠️

Important

To produce a currency exchange quote, make sure you have the appropriate user permissions.


2. Whitelist your IP

Before using the APIs, you must whitelist your IP address in the Panel to ensure secure access to LocalPayment services.


3. Generate an Authentication Token

To interact with LocalPayment's APIs, you need an authentication token.

Send a POST request to the Generate an Acces Token endpoint and include your API credentials in the request; to generate an authentication token.

Request example

curl --request POST \
     --url https://api.stage.localpayment.com/api/token/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "username": "[email protected]",
  "password": "1234"
}
'

Successful response

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNTMxOTkyOSwianRpIjoiZWUxMDE3MTUwY2JhNGM1NTg0MjYyZmRkZTdiOThiNGQiLCJ1c2VyX2lkIjoxMDAwLCJzdXBlcnVzZXIiOnRydWUsImlzX3N0YWZmIjp0cnVlLCJybaCIsImV4cCI62xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkFMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZGUiOiJBNzaW9uTEwiLCJwZXJtaXcyI6W119.6siymomkQ72yMvHGU9sMCO4h-cxpNgQXor",
  "access": "eyJ0eXAiOiJKV1QiLCJhJIUzI1NiJ9.eyJ0b2tlbl90eXBlIbGciOijoiYWNjZXNzIiwiZXhwIjoxNzM1MjMzODI5LCJqdGkiOiJiMDRmNzQ3YWEjOCIsIn4Mjg0YjM0YmMwN2Y4ZjVkOWM0NWFVzZXJfaWQiOjEwMDAsInN1cGVydXNlciI6dHJ1ZSwiaXNfc3RhZmYiOnRy3VudHJpZXMiOljpbIkFsiQUxMIl0sImNvbXBhbnkiOiJBTEwiLCJjbGllbnRfY29kZSI6IkFMTCIsInBlcm1pc3Npb25zIjpdWUsInJvbGVzIMTCJdLlqEnH7GrECJjbbXX0.sWOLKFxCcXQkUcPvTjYceXBp39hDF3-Snc"
}

📘

Info

For security reasons, access tokens are valid for 5 minutes. If your token expires, you can create a new one with a 24-hour validity by using the Refresh the token endpoint.


4. Consult the required code

  • Country:
    To get the Country in ISO format, check the list that is available in the documentation's Countries, choose the country of interest and navigate to the Country Overview section.
  • Currency:
    To get the Currency Code, check the list that is available in the documentation's Countries, choose the country of interest and navigate to the Country Overview section.

Create a Currency Exchange Quote

To create it via the API, send a POST request to the Currency Exchange Quote endpoint with all the required information. The API will respond with a token of the quote.

Request example

curl --request GET \
     --url 'https://api.stage.localpayment.com/api/fx/currency-exchange/payin?sourceCurrency=ARS&quoteCurrency=USD&accountNumber=032.840.00000001&quoteAccountNumber=032.840.00000002' \
     --header 'Authorization: eyJ0eXAiOiJKV1QiLCJhJIUzI1NiJ9.eyJ0b2tlbl90eXBlIbGciOijoiYWNjZXNzIiwiZXhwIjoxNzM1MjMzODI5LCJqdGkiOiJiMDRmNzQ3YWEjOCIsIn4Mjg0YjM0YmMwN2Y4ZjVkOWM0NWFVzZXJfaWQiOjEwMDAsInN1cGVydXNlc' \
     --header 'accept: application/json'

Successful response

{
  "exchangeRateToken": "5c3q89a7-f1bc-4ba5-a3b5-411ba0d144ca",
  "transactionType": "PayIn",
  "accountNumber": "032.840.00000001",
  "sourceCurrency": "ARS",
  "creationDate": "2024-12-27T21:33:32.6513692+00:00",
  "expirationDate": "2024-12-28T05:33:32.6513692+00:00",
  "quotes": [
    {
      "paymentMethodCode": "1005",
      "rate": 0.0008369108482392735,
      "quoteCurrency": "USD"
    },
    {
      "paymentMethodCode": "1023",
      "rate": 0.0008369108482392735,
      "quoteCurrency": "USD"
    },
    {
      "paymentMethodCode": "1000",
      "rate": 0.0008369108482392735,
      "quoteCurrency": "USD"
    },
    {
      "paymentMethodCode": "1004",
      "rate": 0.0008369108482392735,
      "quoteCurrency": "USD"
    },
    {
      "paymentMethodCode": "1002",
      "rate": 0.0008369108482392735,
      "quoteCurrency": "USD"
    }
  ]
}

Currency Exchange Bulk

¿What is Currency Exchange Bulk?

The Currency Exchange Bulk API allows you to create individual or bulk Foreign Exchange (FX).


Prerequisites

Before requesting a currency exchange bulk, you must have completed the following steps:


1. Environment access

You will need to conclude your onboarding process and your Stage login credentials or your Production credentials (if you are already certified) in order to create a payment via API or Panel.

⚠️

Important

To produce a currency exchange bulk, make sure you have the appropriate user permissions.


2. Whitelist your IP

Before using the APIs, you must whitelist your IP address in the Panel to ensure secure access to LocalPayment services.


3. Generate an Authentication Token

To interact with LocalPayment's APIs, you need an authentication token.

Send a POST request to the Generate an Acces Token endpoint and include your API credentials in the request; to generate an authentication token.

Request example

curl --request POST \
     --url https://api.stage.localpayment.com/api/token/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "username": "[email protected]",
  "password": "1234"
}
'

Successful response

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNTMxOTkyOSwianRpIjoiZWUxMDE3MTUwY2JhNGM1NTg0MjYyZmRkZTdiOThiNGQiLCJ1c2VyX2lkIjoxMDAwLCJzdXBlcnVzZXIiOnRydWUsImlzX3N0YWZmIjp0cnVlLCJybaCIsImV4cCI62xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkFMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZGUiOiJBNzaW9uTEwiLCJwZXJtaXcyI6W119.6siymomkQ72yMvHGU9sMCO4h-cxpNgQXor",
  "access": "eyJ0eXAiOiJKV1QiLCJhJIUzI1NiJ9.eyJ0b2tlbl90eXBlIbGciOijoiYWNjZXNzIiwiZXhwIjoxNzM1MjMzODI5LCJqdGkiOiJiMDRmNzQ3YWEjOCIsIn4Mjg0YjM0YmMwN2Y4ZjVkOWM0NWFVzZXJfaWQiOjEwMDAsInN1cGVydXNlciI6dHJ1ZSwiaXNfc3RhZmYiOnRy3VudHJpZXMiOljpbIkFsiQUxMIl0sImNvbXBhbnkiOiJBTEwiLCJjbGllbnRfY29kZSI6IkFMTCIsInBlcm1pc3Npb25zIjpdWUsInJvbGVzIMTCJdLlqEnH7GrECJjbbXX0.sWOLKFxCcXQkUcPvTjYceXBp39hDF3-Snc"
}

📘

Info

For security reasons, access tokens are valid for 5 minutes. If your token expires, you can create a new one with a 24-hour validity by using the Refresh the token endpoint.


4. Consult the required code

  • Country:
    To get the Country in ISO format, check the list that is available in the documentation's Countries, choose the country of interest and navigate to the Country Overview section.
  • Currency:
    To get the Currency Code, check the list that is available in the documentation's Countries, choose the country of interest and navigate to the Country Overview section.

Create a Currency Exchange Bulk

To create it via the API, send a POST request to the Currency Exchange Bulk endpoint with all the required information. The API will respond with the transaction information.

⚠️

Important

Keep in mind that you can previously generate Currency Exchange Quote with the API, and it will be considered by assigning the given quote token in the exchangeRateToken field of the Currency Exchange Bulk request.


Request example

curl --request POST \
     --url https://api.stage.localpayment.com/currency-exchange \
     --header 'Authorization: eyJ0eXAiOiJKV1QiLCJhJIUzI1NiJ9.eyJ0b2tlbl90eXBlIbGciOijoiYWNjZXNzIiwiZXhwIjoxNzM1MjMzODI5LCJqdGkiOiJiMDRmNzQ3YWEjOCIsIn4Mjg0YjM0YmMwN2Y4ZjVkOWM0NWFVzZXJfaWQiOjEwMDAsInN1cGVydXNlc' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "country": "ARG",
  "currency": "EUR",
  "externalId": "11112222",
  "account": {
    "debited": {
      "currency": "EUR",
      "accountNumber": "111.111.11111111",
      "amount": 10
    },
    "credited": {
      "currency": "USD",
      "accountNumber": "000.000.00000000"
    }
  }
}
'

Successful response

{
  "transactionType": "CurrencyExchange",
  "externalId": "",
  "internalId": "X11111XX-11X1-111X-X11X-111111X1X1XX",
  "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": 40
    },
    "credited": {
      "currency": "EUR",
      "accountNumber": "000.111.11111111",
      "amount": 0.18
    },
    "appliedFx": 224.54
  }
}

📘

Info

Check the posible transaction status that you may obtein as response.


Webhooks/Callbacks

If you have your notifications enabled, you will receive a message (webhook) to let you know when the status of your currency exchange bulk changes. Look for some webhook examples.

Updated 18 days ago