To integrate Replit with Payoneer, register a program in the Payoneer Partner API portal, store your partner username, API password, and program ID in Replit Secrets (lock icon π), and call the Payoneer REST API from your server to send mass payouts and payment requests. Payoneer uses HTTP Basic Auth for the partner API. Use Autoscale deployment for payout processing endpoints.
Payoneer Partner API for Global Payouts from Replit
Payoneer sits in a different part of the payments ecosystem than consumer-facing processors like Stripe or PayPal. While Stripe helps you collect money from customers, Payoneer helps you send money to a global network of freelancers, service providers, suppliers, and marketplace sellers. This makes Payoneer valuable for platforms that need to pay out to international recipients efficiently and at lower cost than traditional wire transfers.
The Payoneer Partner API is designed for businesses operating payout programs β marketplaces paying their sellers, agencies paying freelancers, affiliate networks paying publishers, or SaaS platforms paying their resellers. To use the API, you register a program with Payoneer that defines your payout use case, get approved, and receive partner credentials. The API supports batch payouts, individual payment requests, payee registration, and balance inquiries.
Payoneer payments differ from bank transfers in that recipients must have an active Payoneer account. When you register a payee via the API, Payoneer sends them an invitation email if they do not already have an account. They complete registration, and then they can receive your payments. Multi-currency support means you can pay in USD, EUR, GBP, and dozens of other currencies with automatic conversion.
Integration method
Payoneer provides a Partner API for businesses to programmatically send payouts to Payoneer account holders. Authentication uses HTTP Basic Auth with your partner username and API password. Your Replit server stores these credentials in Replit Secrets, calls the Payoneer API to register payees, initiate payments, and check payment status. Payoneer is not a consumer checkout flow β it is specifically for platform operators sending mass payouts to vendors, freelancers, or affiliates.
Prerequisites
- A Replit account with a Node.js or Python Repl ready
- A Payoneer business account with Partner API access (apply at payoneer.com/partners)
- An approved Payoneer Partner Program with program ID, partner username, and API password
- Recipient Payoneer account email addresses (recipients must register with Payoneer)
Step-by-step guide
Register a Payoneer Partner Program
Register a Payoneer Partner Program
The Payoneer Partner API is not self-service β you must apply for access and get approved. Navigate to payoneer.com and log into your business account. Look for 'Developer' or 'API' in the main navigation, or contact Payoneer's partner team directly. Submit a program application describing your use case (marketplace payouts, freelancer payments, affiliate commissions, etc.). Payoneer's team will review your application and, if approved, set up a program in their system. You will receive: a Partner Username (your account identifier), an API Password (your authentication credential), and a Program ID (identifies your specific payout program). These three values are required for all API calls. During the approval process, Payoneer sets your program's payment parameters: supported currencies, minimum payment amounts, payout frequency restrictions, and any geographic restrictions based on your business type and compliance status. For testing, Payoneer provides a sandbox environment. Request sandbox access from your Payoneer account manager. The sandbox API uses different credentials and the endpoint URL differs from production. Always test in sandbox before initiating production payments. Note your program's base API URL β it typically follows the format https://api.payoneer.com/v2/programs/{programId}/ for the REST API. Older Payoneer integrations may use the SOAP/XML-based API; the REST API is preferred for new integrations. Payoneer requires that recipients register a Payoneer account to receive payments. You can register them programmatically via the API or direct them to Payoneer's self-registration page with a link that pre-fills your program affiliation.
Pro tip: During the application, clearly explain your expected monthly payment volume and recipient count. Payoneer's underwriting team assesses risk based on this information. Under-representing volume can cause your account to be flagged later when actual volume exceeds projections.
Expected result: Payoneer Partner Program approved. You have a Partner Username, API Password, and Program ID. Sandbox access is available for testing.
Store Payoneer Credentials in Replit Secrets
Store Payoneer Credentials in Replit Secrets
Click the lock icon (π) in the left Replit sidebar to open the Secrets pane. Add the following secrets: PAYONEER_PARTNER_USERNAME: your Payoneer partner username. PAYONEER_API_PASSWORD: your Payoneer API password. PAYONEER_PROGRAM_ID: your Payoneer program ID (numeric string). PAYONEER_API_BASE_URL: the Payoneer API base URL. For production: https://api.payoneer.com/v2/programs/{programId}/. For sandbox: https://api.sandbox.payoneer.com/v2/programs/{programId}/. The API password is the most sensitive credential β it authenticates all payment operations including sending real money. It must never appear in source code. Replit's Secret Scanner monitors for credential patterns but the responsibility is yours to use Secrets from the start. Payoneer Basic Auth is constructed by Base64-encoding username:password. In Node.js, this is Buffer.from('username:password').toString('base64'). In Python, it is base64.b64encode(b'username:password').decode().
1// check-payoneer-secrets.js2const required = ['PAYONEER_PARTNER_USERNAME', 'PAYONEER_API_PASSWORD',3 'PAYONEER_PROGRAM_ID', 'PAYONEER_API_BASE_URL'];4for (const key of required) {5 if (!process.env[key]) {6 throw new Error(`Missing secret: ${key}. Set it in Replit Secrets (lock icon π).`);7 }8}9console.log('Payoneer secrets verified.');10console.log('Program ID:', process.env.PAYONEER_PROGRAM_ID);11console.log('API URL:', process.env.PAYONEER_API_BASE_URL);Pro tip: Keep separate Replit projects (or separate Secret sets) for sandbox and production Payoneer credentials. Mixing up sandbox and production credentials is a common mistake that can cause test payments to be sent as real transactions.
Expected result: All four Payoneer secrets appear in Replit Secrets. The check script prints Program ID and API URL without errors.
Register Payees and Send Payments (Node.js)
Register Payees and Send Payments (Node.js)
Install required packages in the Shell tab: npm install axios express. The Payoneer Partner API v2 is a REST API using HTTP Basic Auth. Construct the Authorization header by Base64-encoding your username and API password. Before you can pay someone, they must be registered as a payee in your program. Use the payees endpoint to register a recipient by email. Payoneer sends the recipient an invitation to create or connect their Payoneer account. Once registered, you reference payees by their Payoneer ID or email for payments. To send a payment, POST to the payments endpoint with the payee ID, amount, currency, description, and a unique payment ID from your system (for idempotency). Payoneer validates the payment, deducts from your program balance, and sends funds to the recipient. Payment statuses progress through: PENDING β UNDER_REVIEW β PROCESSED. Payments can also be REJECTED (failed compliance/fraud checks) or CANCELLED. Always store the Payoneer transaction ID alongside your internal record for reconciliation. For batch payouts (paying many recipients at once), iterate through your payee list and call the payment endpoint for each one. Payoneer does support batch payment files for very large volumes, but the REST API approach with individual calls is simpler for most integrations handling up to a few hundred payments per run. Rate limits apply β implement exponential backoff for any 429 responses.
1// payoneer.js β Payoneer Partner API for Node.js on Replit2const axios = require('axios');3const express = require('express');45const app = express();6app.use(express.json());78// Build Basic Auth header9const credentials = Buffer.from(10 `${process.env.PAYONEER_PARTNER_USERNAME}:${process.env.PAYONEER_API_PASSWORD}`11).toString('base64');1213const payoneerApi = axios.create({14 baseURL: process.env.PAYONEER_API_BASE_URL,15 headers: {16 'Authorization': `Basic ${credentials}`,17 'Content-Type': 'application/json'18 }19});2021// Register a payee (recipient must have or create a Payoneer account)22app.post('/api/payees/register', async (req, res) => {23 const { email, firstName, lastName } = req.body;24 25 if (!email) return res.status(400).json({ error: 'email required' });26 27 try {28 const response = await payoneerApi.post('/payees/', {29 payee_id: email, // Use email as internal payee ID30 type: 'individual',31 registration_url_params: {32 first_name: firstName,33 last_name: lastName,34 email35 }36 });37 res.json({ success: true, payee: response.data });38 } catch (err) {39 res.status(err.response?.status || 500).json({ error: err.response?.data || err.message });40 }41});4243// Send a payment to a registered payee44app.post('/api/payments/send', async (req, res) => {45 const { payeeId, amount, currency = 'USD', description, internalRef } = req.body;46 47 if (!payeeId || !amount || !internalRef) {48 return res.status(400).json({ error: 'payeeId, amount, and internalRef required' });49 }50 51 try {52 const response = await payoneerApi.post('/payments/', {53 client_reference_id: internalRef, // Your unique payment ID for idempotency54 payee_id: payeeId,55 amount: parseFloat(amount),56 currency,57 description: description || 'Payment'58 });59 res.json({60 success: true,61 transactionId: response.data.payment_id,62 status: response.data.status,63 amount: response.data.amount,64 currency: response.data.currency65 });66 } catch (err) {67 res.status(err.response?.status || 500).json({ error: err.response?.data || err.message });68 }69});7071// Check payment status72app.get('/api/payments/:paymentId/status', async (req, res) => {73 try {74 const response = await payoneerApi.get(`/payments/${req.params.paymentId}`);75 res.json({ paymentId: req.params.paymentId, status: response.data.status, details: response.data });76 } catch (err) {77 res.status(err.response?.status || 500).json({ error: err.response?.data || err.message });78 }79});8081// Get program balance82app.get('/api/balance', async (req, res) => {83 try {84 const response = await payoneerApi.get('/balance/');85 res.json({ balance: response.data });86 } catch (err) {87 res.status(err.response?.status || 500).json({ error: err.response?.data || err.message });88 }89});9091app.listen(3000, '0.0.0.0', () => console.log('Payoneer server running on port 3000'));Pro tip: Always include a client_reference_id (your internal payment ID) in every payment request. This is Payoneer's idempotency key β if you retry a payment, the same client_reference_id ensures Payoneer will not send the payment twice. Generate unique IDs from your database transaction ID or a UUID.
Expected result: POST /api/payees/register sends a payee invitation. POST /api/payments/send initiates a payment and returns a Payoneer transaction ID. GET /api/payments/{id}/status returns the payment status.
Python Integration for Payoneer API
Python Integration for Payoneer API
For Python Replit projects, install requests and flask: pip install requests flask. Python's requests library supports Basic Auth natively via the auth parameter β pass a tuple of (username, password) and requests handles the Base64 encoding automatically. The payment initiation flow is identical to Node.js: register payees first, then send payments with unique client_reference_id values for idempotency. For multi-currency payouts, specify the currency field β Payoneer supports USD, EUR, GBP, AUD, CAD, JPY, and many others. For production payout pipelines that process payments at the end of each billing cycle, run the script as a scheduled job. Replit's Reserved VM deployment keeps your server running, and you can add a cron-style scheduler using schedule (pip install schedule) or APScheduler to trigger payouts on a schedule without external cron infrastructure. Always validate your program balance before initiating a batch of payouts. The GET /balance/ endpoint returns your available funds. If balance is insufficient for the planned payout total, pause the batch and alert your team rather than letting individual payments fail unexpectedly.
1# payoneer_api.py β Payoneer Partner API for Python on Replit2import os3import requests4from flask import Flask, request, jsonify56BASE_URL = os.environ['PAYONEER_API_BASE_URL']7USERNAME = os.environ['PAYONEER_PARTNER_USERNAME']8PASSWORD = os.environ['PAYONEER_API_PASSWORD']9PROGRAM_ID = os.environ['PAYONEER_PROGRAM_ID']1011# requests handles Basic Auth encoding with the auth tuple12session = requests.Session()13session.auth = (USERNAME, PASSWORD)14session.headers.update({'Content-Type': 'application/json'})1516app = Flask(__name__)1718@app.route('/api/balance')19def get_balance():20 resp = session.get(f'{BASE_URL}/balance/')21 if not resp.ok:22 return jsonify({'error': resp.text}), resp.status_code23 return jsonify({'balance': resp.json()})2425@app.route('/api/payees/register', methods=['POST'])26def register_payee():27 data = request.get_json()28 payload = {29 'payee_id': data.get('email'),30 'type': 'individual',31 'registration_url_params': {32 'first_name': data.get('firstName', ''),33 'last_name': data.get('lastName', ''),34 'email': data.get('email')35 }36 }37 resp = session.post(f'{BASE_URL}/payees/', json=payload)38 if not resp.ok:39 return jsonify({'error': resp.json()}), resp.status_code40 return jsonify({'success': True, 'payee': resp.json()})4142@app.route('/api/payments/send', methods=['POST'])43def send_payment():44 data = request.get_json()45 payee_id = data.get('payeeId')46 amount = data.get('amount')47 internal_ref = data.get('internalRef')48 49 if not all([payee_id, amount, internal_ref]):50 return jsonify({'error': 'payeeId, amount, and internalRef required'}), 40051 52 payload = {53 'client_reference_id': internal_ref,54 'payee_id': payee_id,55 'amount': float(amount),56 'currency': data.get('currency', 'USD'),57 'description': data.get('description', 'Payment')58 }59 resp = session.post(f'{BASE_URL}/payments/', json=payload)60 if not resp.ok:61 return jsonify({'error': resp.json()}), resp.status_code62 result = resp.json()63 return jsonify({'success': True, 'transactionId': result.get('payment_id'), 'status': result.get('status')})6465@app.route('/api/payments/<payment_id>/status')66def payment_status(payment_id):67 resp = session.get(f'{BASE_URL}/payments/{payment_id}')68 if not resp.ok:69 return jsonify({'error': resp.text}), resp.status_code70 return jsonify(resp.json())7172if __name__ == '__main__':73 app.run(host='0.0.0.0', port=3000)Pro tip: Check your Payoneer program balance before processing batch payouts with session.get(f'{BASE_URL}/balance/'). If the balance is insufficient for the planned payments, alert your team rather than letting individual payments fail silently mid-batch.
Expected result: GET /api/balance returns the program's available balance. POST /api/payments/send initiates a payout and returns the Payoneer transaction ID and status.
Common use cases
Marketplace Seller Payouts
Automatically pay marketplace sellers their earnings at the end of each billing period. Your Replit server calculates each seller's balance from order data, calls the Payoneer API to initiate payments for each seller above a minimum threshold, and records the payment transaction IDs for reconciliation.
Build an Express endpoint that accepts a list of seller IDs and amounts, calls the Payoneer Partner API to send payments to each registered seller, and returns a payout report with transaction IDs and statuses.
Copy this prompt to try it in Replit
Freelancer Payment Automation
Automate payments to a global team of freelancers when their work is approved. When a project milestone is marked complete, trigger a Payoneer payment for the agreed amount. Support multiple currencies based on each freelancer's preferred payment currency.
Create a payment endpoint that sends a Payoneer payment request to a freelancer by email address, specifies the amount and currency, and sends a payment description referencing the completed project.
Copy this prompt to try it in Replit
Affiliate Commission Payouts
Pay affiliate marketing commissions to publishers and influencers via Payoneer. When monthly affiliate reporting closes, batch-process commission payouts for all affiliates above the minimum payout threshold and track each payment's status through to completion.
Build a commission payout script that reads affiliate earnings from a database, filters for balances above the minimum threshold, initiates batch Payoneer payments, and updates the database with transaction IDs.
Copy this prompt to try it in Replit
Troubleshooting
401 Unauthorized on all Payoneer API requests
Cause: PAYONEER_PARTNER_USERNAME or PAYONEER_API_PASSWORD in Replit Secrets contains a typo, extra whitespace, or is missing. Also occurs if the API password has been reset in the Payoneer partner portal.
Solution: Open Replit Secrets (lock icon π), delete and re-enter both PAYONEER_PARTNER_USERNAME and PAYONEER_API_PASSWORD. Verify in the Payoneer partner portal that the API credentials are active and have not been rotated.
1// Debug Basic Auth construction2const creds = `${process.env.PAYONEER_PARTNER_USERNAME}:${process.env.PAYONEER_API_PASSWORD}`;3console.log('Credentials length:', creds.length);4console.log('Base64 preview:', Buffer.from(creds).toString('base64').substring(0, 20) + '...');Payment rejected with PAYEE_NOT_REGISTERED error
Cause: The payee has not completed Payoneer account registration, or the payee_id used in the payment request does not match their registered Payoneer payee ID in your program.
Solution: Verify the payee is registered in your program via GET /payees/{payeeId}. If the payee is not registered or has not completed signup, re-trigger the invitation email via the payee registration endpoint. Ensure you use the exact payee_id used during registration.
1// Check payee registration status2const resp = await payoneerApi.get(`/payees/${payeeId}`);3console.log('Payee status:', resp.data.status);4// Status: UNREGISTERED, REGISTERED, SUSPENDED, BLOCKEDDuplicate payment sent β same recipient paid twice
Cause: The client_reference_id was not set, was not unique, or the same reference ID was accidentally reused across different payment requests. Without a unique client_reference_id, retries create duplicate payments.
Solution: Always include a unique client_reference_id in every payment. Use a UUID or your internal transaction ID. Check that your retry logic passes the same client_reference_id on retries β Payoneer deduplicates based on this field.
1// Generate unique reference ID2const { v4: uuidv4 } = require('uuid');3const clientReferenceId = `payout-${userId}-${Date.now()}-${uuidv4().substring(0, 8)}`;Insufficient balance error when sending payments
Cause: The Payoneer program balance is lower than the payment amount. Payoneer programs require pre-funded balances before payments can be sent.
Solution: Log into the Payoneer partner portal and fund your program balance by initiating a wire transfer or ACH deposit. Check balance via GET /balance/ before processing batch payments and implement a pre-flight check that halts the batch if balance is insufficient.
Best practices
- Store PAYONEER_PARTNER_USERNAME, PAYONEER_API_PASSWORD, PAYONEER_PROGRAM_ID, and PAYONEER_API_BASE_URL in Replit Secrets (lock icon π) β these credentials authorize real money transfers
- Always include a unique client_reference_id in every payment request for idempotency β Payoneer uses this to prevent duplicate payments on retries
- Check your program balance before batch payouts to avoid mid-batch payment failures from insufficient funds
- Use sandbox credentials during development and testing β keep sandbox and production Secrets completely separate
- Store Payoneer transaction IDs in your database alongside internal payment records for reconciliation and customer support
- Implement webhook handlers for Payoneer payment status notifications rather than polling the status endpoint repeatedly
- Deploy as Autoscale for on-demand payout endpoints; use Reserved VM for scheduled payout jobs that process payments on a billing cycle
- Log all payment operations with payee ID, amount, currency, and reference ID β financial audit trails are required for compliance
Alternatives
Stripe Connect handles marketplace payouts to sellers in a checkout-first flow, while Payoneer focuses on B2B global disbursements to freelancers and vendors without a consumer-facing checkout experience.
Worldpay is an enterprise payment processor for accepting global card payments, while Payoneer specifically enables sending payouts to international recipients.
Wave provides accounting and invoicing for small businesses with a free tier, while Payoneer focuses on the payout side for platform operators sending mass payments.
Frequently asked questions
How do I connect Replit to Payoneer?
Apply for Payoneer Partner API access, receive your partner username, API password, and program ID after approval, store them in Replit Secrets (lock icon π), and make HTTP Basic Auth requests to the Payoneer REST API at https://api.payoneer.com/v2/programs/{programId}/. Build the Basic Auth header by Base64-encoding username:password.
Does Replit work with Payoneer?
Yes. The Payoneer Partner API is a standard REST API accessible over HTTPS from any server, including Replit. Use axios (Node.js) or the requests library (Python) with Basic Auth to authenticate. The main prerequisite is obtaining approved Partner API access from Payoneer, which requires an application review.
What is the difference between Payoneer and Stripe?
Stripe is primarily for collecting payments from customers (checkout, subscriptions). Payoneer is for sending payouts to other businesses, freelancers, or platform participants globally. They solve opposite sides of the money flow. Many platforms use Stripe for inbound payments and Payoneer for outbound disbursements.
Can I send payments in multiple currencies with Payoneer?
Yes. The Payoneer API supports multiple currencies β set the currency field to USD, EUR, GBP, AUD, CAD, JPY, and many others in your payment request. Recipients receive payments in their preferred currency, with Payoneer handling the conversion. Your program balance is typically maintained in one base currency.
What deployment type should I use on Replit for Payoneer integrations?
Use Autoscale for on-demand payment processing endpoints where payouts are triggered by user actions. Use Reserved VM for scheduled payout jobs that run at the end of each billing cycle. Most marketplace payout systems combine both: an Autoscale API for immediate payment triggers and a Reserved VM background job for monthly reconciliation and batch processing.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation