Set up cross-border payments (Ethereum & EVM)

Process cross-border payments with FX conversion on EVM networks using DFNS wallets, stablecoins, and policy-controlled treasury operations.

International payments require burning a source currency, applying an exchange rate, and minting the destination currency to the receiver, coordinating multiple actors (bank, sender, FX provider) across each step. This solution blueprint shows how to orchestrate that flow on-chain with DFNS wallets handling the key management and transaction signing.

Get the code

Clone the repository to follow along.

The system involves three main actors:

Bank

Deploys contracts, mints tokens, manages roles, and sets the FX rate for each payment

Sender

Initiates payments in the source currency (e.g., iEUR)

Receiver

Receives funds in the destination currency (e.g., iAUD)

Setup: The Bank deploys two stablecoins (iEUR and iAUD) and the CrossBorderPayment contract.

Payment flow:

1. The Sender initiates a payment, specifying the receiver and amount in iEUR
2. The Bank sets the conversion rate (how much iAUD the receiver gets)
3. The Sender executes the payment. iEUR is burned from the sender and iAUD is minted to the receiver

Prerequisites

1. Clone the cross-border-payments solution
2. Create a DFNS organization if you don’t have one already, and note the organization id
3. Create a service account for API access (see the service account guide)
4. Create 3 wallets: Bank, Sender and Receiver on an EVM-compatible network (e.g.: Ethereum Sepolia)
5. Fund the Bank and Sender wallets with Testnet ETH for gas fees (see using testnets)
6. Make sure you have installed Node.js v18+

Project Structure

contracts/
  StableCoin.sol              ERC-20 stablecoin with mint, burn, pause, and role-based access
  CrossBorderPayment.sol      Multi-step payment contract with FX conversion

dfns/
  DfnsCommon.ts               Shared DFNS API client and blockchain configuration
  DeployCrossBorderPayment.ts Deploy the full system (2 stablecoins + payment contract)
  SenderCLI.ts                CLI for the sender: init payment, execute payment, approve tokens
  ReceiverCLI.ts              CLI for role management (grant MINTER_ROLE, etc.)
  FXProviderCLI.ts            CLI for the FX provider: set exchange rates

test/
  CrossBorderPayment.ts       End-to-end tests for the payment flow

Configuration

1. Clone and install

   cd cross-border-payments
   npm install
   
2. Set up environment variables

   Copy the example environment file and fill in your values:

   cp .env.example .env
   

   .env

   # DFNS API Configuration
   DFNS_API_URL=https://api.dfns.io
   DFNS_ORG_ID=or-xxx-xxx
   DFNS_AUTH_TOKEN=eyJ...
   DFNS_CRED_ID=xxx
   DFNS_PRIVATE_KEY="-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----"
   
   # DFNS Wallet IDs
   BANK_WALLET_ID=wa-xxx-xxx
   SENDER_WALLET_ID=wa-xxx-xxx
   RECEIVER_WALLET_ID=wa-xxx-xxx
   
   # Blockchain Configuration
   BLOCKCHAIN_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
   

   Variable	Description
   DFNS_API_URL	DFNS API base URL (https://api.dfns.io)
   DFNS_ORG_ID	Your organization ID
   DFNS_AUTH_TOKEN	Service account auth token
   DFNS_CRED_ID	Credential ID for the signing key (found in Settings > Service Accounts)
   DFNS_PRIVATE_KEY	Private key for request signing (PEM format)
   BANK_WALLET_ID	Wallet ID for the bank/admin role
   SENDER_WALLET_ID	Wallet ID for the payment sender
   RECEIVER_WALLET_ID	Wallet ID for the payment receiver
   BLOCKCHAIN_RPC_URL	RPC endpoint for the target blockchain

3. Compile contracts

   npx hardhat compile
   

Deploy the System

npm run deploy

This script:

1. Deploys iEUR (source stablecoin)
2. Deploys iAUD (destination stablecoin)
3. Deploys the CrossBorderPayment contract
4. Transfers iAUD ownership to the payment contract (so it can mint on settlement)
5. Mints 1000 iEUR to the Sender wallet

Save the three contract addresses from the output.

End-to-End Payment Flow

1. Grant the MINTER_ROLE to the CrossBorderPayment contract

   The payment contract needs permission to mint iAUD when settling payments:

   npm run receiver-cli grantRole MINTER_ROLE <iAUD_ADDRESS> <CBP_ADDRESS>
   
2. Initiate a payment (Sender)

   The sender initiates a 100 iEUR payment to the receiver. This approves the token transfer and calls initPayment in one step:

   npm run sender-cli init <CBP_ADDRESS> <iEUR_ADDRESS> <RECEIVER_ADDRESS> 100
   

   Note the Payment ID from the output.

3. Set the FX rate (FX Provider)

   The FX provider sets how much iAUD the receiver will get. For example, 150 iAUD for 100 iEUR (1.5x rate):

   npm run fx-cli set-rate <CBP_ADDRESS> <PAYMENT_ID> 150
   
4. Execute the payment (Sender)

   The sender confirms and executes the payment. This burns iEUR from the sender and mints iAUD to the receiver:

   npm run sender-cli execute <CBP_ADDRESS> <PAYMENT_ID>
   
5. Verify balances

   • Sender: 900 iEUR (100 burned)
   • Receiver: 150 iAUD (150 minted)

Run the Test Suite

The test suite verifies the full payment flow on a local Hardhat network (no DFNS credentials needed):

npx hardhat test

Settle to fiat with Payouts

If your cross-border flow ends in fiat bank deposits rather than on-chain tokens, use Payouts to convert stablecoins (USDC, USDT, EURC) to local currency across 94 countries and 63 currencies. See the usage guide or developer guide.