Skip to main content
RapidDev - Software Development Agency
replit-integrationsStandard API Integration

How to Integrate Replit with Payoneer

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.

What you'll learn

  • How to register and configure a Payoneer Partner API program for your business
  • How to authenticate Replit requests to the Payoneer API using HTTP Basic Auth
  • How to register payees and initiate payment requests to Payoneer accounts
  • How to check payment status and handle Payoneer webhook notifications
  • Differences between Payoneer's partner payout API and consumer payment processors like Stripe
Book a free consultation
4.9Clutch rating ⭐
600+Happy partners
17+Countries served
190+Team members
Intermediate13 min read30 minutesPaymentMarch 2026RapidDev Engineering Team
TL;DR

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

Standard API Integration

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

1

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.

2

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().

check-payoneer-secrets.js
1// check-payoneer-secrets.js
2const 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.

3

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.

payoneer.js
1// payoneer.js β€” Payoneer Partner API for Node.js on Replit
2const axios = require('axios');
3const express = require('express');
4
5const app = express();
6app.use(express.json());
7
8// Build Basic Auth header
9const credentials = Buffer.from(
10 `${process.env.PAYONEER_PARTNER_USERNAME}:${process.env.PAYONEER_API_PASSWORD}`
11).toString('base64');
12
13const payoneerApi = axios.create({
14 baseURL: process.env.PAYONEER_API_BASE_URL,
15 headers: {
16 'Authorization': `Basic ${credentials}`,
17 'Content-Type': 'application/json'
18 }
19});
20
21// 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 ID
30 type: 'individual',
31 registration_url_params: {
32 first_name: firstName,
33 last_name: lastName,
34 email
35 }
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});
42
43// Send a payment to a registered payee
44app.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 idempotency
54 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.currency
65 });
66 } catch (err) {
67 res.status(err.response?.status || 500).json({ error: err.response?.data || err.message });
68 }
69});
70
71// Check payment status
72app.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});
80
81// Get program balance
82app.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});
90
91app.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.

4

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.

payoneer_api.py
1# payoneer_api.py β€” Payoneer Partner API for Python on Replit
2import os
3import requests
4from flask import Flask, request, jsonify
5
6BASE_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']
10
11# requests handles Basic Auth encoding with the auth tuple
12session = requests.Session()
13session.auth = (USERNAME, PASSWORD)
14session.headers.update({'Content-Type': 'application/json'})
15
16app = Flask(__name__)
17
18@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_code
23 return jsonify({'balance': resp.json()})
24
25@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_code
40 return jsonify({'success': True, 'payee': resp.json()})
41
42@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'}), 400
51
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_code
62 result = resp.json()
63 return jsonify({'success': True, 'transactionId': result.get('payment_id'), 'status': result.get('status')})
64
65@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_code
70 return jsonify(resp.json())
71
72if __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.

Replit Prompt

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.

Replit Prompt

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.

Replit Prompt

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.

typescript
1// Debug Basic Auth construction
2const 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.

typescript
1// Check payee registration status
2const resp = await payoneerApi.get(`/payees/${payeeId}`);
3console.log('Payee status:', resp.data.status);
4// Status: UNREGISTERED, REGISTERED, SUSPENDED, BLOCKED

Duplicate 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.

typescript
1// Generate unique reference ID
2const { 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

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.

RapidDev

Talk to an Expert

Our team has built 600+ apps. Get personalized help with your project.

Book a free consultation

Need help with your project?

Our experts have built 600+ apps and can accelerate your development. Book a free consultation β€” no strings attached.

Book a free consultation

We put the rapid in RapidDev

Need a dedicated strategic tech and growth partner? Discover what RapidDev can do for your business! Book a call with our team to schedule a free, no-obligation consultation. We'll discuss your project and provide a custom quote at no cost.