Payoneer

Payoneer's auth flow uses OAuth 2.0 client credentials — you POST your client_id and client_secret to receive a Bearer access token. This token is what all subsequent payout calls use. In Bubble, the token endpoint is a separate API Connector call from the payout call. In Bubble, click Plugins → Add plugins → search 'API Connector' → Install (free, by Bubble). Click 'Add another API' and name the group 'Payoneer'. For this group, do NOT add shared headers yet — the token endpoint requires a different auth approach than the payout endpoint. Add Call 1 — Get Token: - Name: Get Access Token - Method: POST - URL: https://api.sandbox.payoneer.com/v4/oauth2/token - Content Type: application/x-www-form-urlencoded (important — the token endpoint requires form encoding, not JSON) - Use as: Action - Body parameters: - grant_type: client_credentials (static text) - client_id: your_client_id (mark as Private — this is sensitive) - client_secret: your_client_secret (mark as Private — this is sensitive) - No Authorization header on this call — credentials go in the body For initialization, paste your actual sandbox client_id and client_secret into the body parameters and click Initialize. Payoneer returns a JSON response with access_token (a long JWT string) and expires_in (typically 3600 seconds). Bubble will detect these fields. Note the Content-Type requirement: Payoneer's token endpoint requires application/x-www-form-urlencoded, not application/json. In the API Connector, make sure the body parameters are sent as form data, not JSON. Bubble's API Connector handles this automatically when you set the Content-Type header accordingly.

1// API Connector Group: Payoneer
2
3// Call 1: POST /v4/oauth2/token
4// URL: https://api.sandbox.payoneer.com/v4/oauth2/token
5// Content-Type: application/x-www-form-urlencoded
6// Use as: Action
7
8// Body parameters (all Private):
9{
10  "grant_type": "client_credentials",
11  "client_id": "YOUR_CLIENT_ID",
12  "client_secret": "YOUR_CLIENT_SECRET"
13}
14
15// Payoneer token response:
16{
17  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
18  "token_type": "Bearer",
19  "expires_in": 3600,
20  "scope": "read write"
21}
22
23// Production URL (after partner approval):
24// https://api.payoneer.com/v4/oauth2/token

The access token expires every ~60 minutes and must be shared across all Bubble workflows that make payout calls. A dedicated 'App Config' data type (a single-row record) is the standard Bubble pattern for application-level state. Go to the Data tab in your Bubble editor. Create a new data type called 'App Config' with these fields: - payoneer_access_token (type: text) — stores the current access token - payoneer_token_expires_at (type: date) — stores the exact datetime when the token expires - payoneer_program_id (type: text) — stores your Payoneer program ID (rarely changes, but useful to have here) Create ONE record of this type manually (via Bubble's Data → App Data → App Config → Create new record). Set payoneer_program_id to your actual program ID from the Payoneer Partner Portal. Leave the token fields empty for now — the first workflow run will populate them. IMPORTANT: Set Privacy Rules for App Config. Go to Data → Privacy → App Config. Because this data type stores an access token that can initiate payouts on behalf of your entire platform, restrict all visibility: - 'Find this in searches': No (never searchable in frontend contexts) - 'View all fields': Only logged-in users with an admin role (or never, if you only access it from Backend Workflows) For accessing the App Config in workflows: use 'Do a search for App Config (all entries): first item' to get the single App Config record. This gives you the payoneer_access_token field. Consider also adding an app-level boolean field 'payoneer_token_refreshing' (yes/no) to prevent race conditions if two workflows try to refresh the token simultaneously — one sets this to 'yes' and checks it before refreshing.

1// Bubble Data Type: App Config (single-row application settings)
2
3// Fields:
4// payoneer_access_token      → Text (long text — JWT can be 500+ chars)
5// payoneer_token_expires_at  → Date
6// payoneer_program_id        → Text
7
8// Privacy Rules for App Config:
9// Find in searches: Never (No)
10// View all fields: Never (access only from Backend Workflows)
11
12// Accessing in workflows:
13// Expression: "Do a search for App Config"'s first item's payoneer_access_token
14
15// NEVER expose the App Config record via:
16// - Public Repeating Groups
17// - Bubble's Data API endpoints
18// - URL parameters
19// - Response from any user-facing workflow

The access token expires in ~3600 seconds (60 minutes). Your platform's payout workflows need a valid token at all times. The solution is a scheduled recurring workflow that refreshes the token every 55 minutes — giving you a 5-minute buffer before expiry. This step requires a paid Bubble plan (Starter $32/month or above) — Bubble's recurring events and Backend Workflows are not available on the Free plan. Go to Backend Workflows in the left sidebar (if you don't see this, go to Settings → API → enable 'This app exposes a Workflow API' first). Create a new Backend Workflow: name it 'payoneer_token_refresh'. Set authentication to 'Not accessible to the user'. Add workflow actions: - Action 1: Call the 'Payoneer - Get Access Token' API Connector action - Action 2: Make changes to 'Do a search for App Config first item' - payoneer_access_token = Result of step 1's access_token - payoneer_token_expires_at = Current date/time + 3595 seconds (use Bubble's 'More' date operator: 'Current date/time + 3595 seconds') Now schedule this workflow to run on a recurring schedule: click 'Schedule' button on the Backend Workflow → 'Create a Recurring Event'. Set the interval to 55 minutes (3300 seconds). The first time the workflow runs, the App Config record gets populated with a valid token. Every 55 minutes after that, the token is refreshed before it can expire. In your payout workflows, add a safety check before calling the payout API: check if 'App Config's payoneer_token_expires_at < Current date/time + 5 minutes'. If yes, call the token refresh workflow first. This handles edge cases where Bubble's scheduler had a delay and the token is close to expiry. RapidDev's team has implemented this OAuth token management pattern for multiple Payoneer integrations on client platforms — if your platform has high-volume payout requirements or complex payee onboarding, a free scoping call at rapidevelopers.com/contact can help you design the architecture.

1// Backend Workflow: payoneer_token_refresh
2// Schedule: Every 55 minutes (3300 seconds)
3
4// Step 1: Call API - Payoneer Get Access Token
5// (POST /v4/oauth2/token with client credentials)
6// Returns: { access_token: "eyJ...", expires_in: 3600 }
7
8// Step 2: Make changes to App Config (first item)
9//   payoneer_access_token = Result of Step 1's access_token
10//   payoneer_token_expires_at = Current date/time + 3595 seconds
11
12// Payout Workflow Safety Check (add before any payout call):
13// Condition: Only when App Config first item's payoneer_token_expires_at
14//            is before Current date/time + 5 minutes
15// Action: Trigger payoneer_token_refresh workflow
16// Then proceed with payout
17
18// WU Cost Estimate:
19// Token refresh = ~1 WU per run × (60 min × 24 hr × 30 days / 55 min)
20// = ~787 WU/month just for token refresh
21// Budget accordingly on your Bubble plan

With the token refresh system in place, add the actual payout call to your API Connector and build the workflow that sends money to payees. In the API Connector → Payoneer group, add Call 2 — Send Payout: - Name: Send Payout - Method: POST - URL: https://api.sandbox.payoneer.com/v4/programs/[program_id]/payments/payout (Replace [program_id] with your actual program_id from the Payoneer Partner Portal) - Use as: Action - Headers (shared or call-level): Authorization: Bearer [token] — but here is the challenge: the token is dynamic (retrieved from the database), not static. You cannot mark a dynamic database value as Private in the traditional sense. The solution for dynamic auth tokens in Bubble: add the Authorization header as a call-level parameter (not a shared header), where the value is set dynamically in the workflow. In the API Connector call, add a Header parameter: key = 'Authorization', value = a placeholder. In your payout workflow, you will pass the actual token value from the App Config record as the header value. Alternatively, use the API Connector's 'Key' parameter mechanism: add a parameter named 'Authorization_header' and use it in the call configuration as a header value reference. When you call this action in a workflow, you pass the stored access_token as the value. Body parameters for the payout call: - payee_id OR payee_email: the recipient's Payoneer account identifier - amount: the payout amount (in decimal format for most currencies — EUR 150.00, not 15000) - currency: currency code (USD, EUR, GBP, etc.) - description: memo text visible to the payee - client_reference_id: your internal reference ID for this payout (use Bubble record's unique ID) After configuring, initialize the call using sandbox test payee values from the Payoneer sandbox documentation. Build the Payout workflow in Bubble: 1. Retrieve the App Config record 2. Check if token is close to expiry → refresh if needed 3. Call Send Payout with the token from App Config 4. Save the returned payment_id to your Bubble database 5. Update the payout record status to 'Pending' (Payoneer processes asynchronously)

1// API Connector: Payoneer group
2// Call 2: Send Payout
3// Method: POST
4// URL: https://api.sandbox.payoneer.com/v4/programs/YOUR_PROGRAM_ID/payments/payout
5
6// Headers (dynamic, set from workflow):
7// Authorization: Bearer [access_token from App Config]
8
9// Body (JSON):
10{
11  "payee_id": "<payoneer_account_id or email>",
12  "amount": "150.00",
13  "currency": "USD",
14  "description": "Payment for Project #12345",
15  "client_reference_id": "bubble_payout_UNIQUE_ID"
16}
17
18// Payoneer payout response:
19{
20  "payment_id": "PAY-ABC123456",
21  "status": "PENDING",
22  "amount": 150.00,
23  "currency": "USD",
24  "payee_id": "payee@email.com",
25  "created_at": "2024-01-15T10:30:00Z"
26}
27
28// Payout Workflow:
29// Step 1: Get App Config first item
30// Step 2: [If token expires soon: call payoneer_token_refresh]
31// Step 3: Call Payoneer - Send Payout
32//         Authorization header = App Config's payoneer_access_token
33//         payee_id = Payee's payoneer_email field
34//         amount = Payee earnings amount
35//         currency = USD
36// Step 4: Make changes to Payout record
37//         payoneer_payment_id = Result's payment_id
38//         status = Pending

Before your platform can pay real contractors, you need to collect and store their Payoneer account information, and you need to complete Payoneer's partner approval process for production access. Payee data model: Create a 'Payee' data type in Bubble (or add fields to your existing Contractor or User type) with: - payoneer_email (text): the email address associated with the payee's Payoneer account - payoneer_payee_id (text): if available, Payoneer's internal payee ID (more reliable than email) - payout_currency (text): the currency this payee prefers to receive payments in - payouts_enabled (yes/no): whether this payee has been validated and can receive payouts Important: Payoneer payees do NOT register through your platform — they create their own Payoneer accounts at payoneer.com independently. Your platform collects their Payoneer email or ID, stores it, and uses it as the recipient when initiating payouts. You cannot programmatically create Payoneer accounts for payees. For production partner approval: go to developer.payoneer.com and click 'Apply for API access'. You will need to provide: - Your platform name and description - Estimated monthly payout volume - Countries you will pay to - Business verification documents (similar to financial institution KYC requirements) Approval typically takes 1–4 weeks. During this time, build and test your complete integration in sandbox. Payoneer sandbox provides test payee IDs that simulate different payout scenarios. For production API calls, change all URLs from https://api.sandbox.payoneer.com to https://api.payoneer.com. Update the client_secret in the token call if Payoneer provides separate production credentials (check your partner portal after approval). WU monitoring: The token refresh workflow runs every 55 minutes regardless of traffic. Budget approximately 800 WU per month for token refresh alone. Add payout calls (each is ~1 WU) based on your expected payout volume. For high-volume platforms, budget for Bubble's Professional plan or higher.

1// Bubble Data Type: Payee
2// Fields:
3// payoneer_email    → Text
4// payoneer_payee_id → Text (optional, more reliable identifier)
5// payout_currency   → Text (default: USD)
6// payouts_enabled   → Yes/No (default: No — enable after verification)
7// user              → User (link to the Bubble user account)
8
9// Privacy Rules for Payee:
10// Find in searches: Only when This Payee's user = Current User
11// View all fields: Only when This Payee's user = Current User
12// (admin users can have separate visibility rules)
13
14// Production Checklist:
15// 1. Partner approval received from Payoneer → update API URLs
16// 2. Token URL: change to https://api.payoneer.com/v4/oauth2/token
17// 3. Payout URL: change to https://api.payoneer.com/v4/programs/{id}/payments/payout
18// 4. Verify client_id / client_secret (may differ for production)
19// 5. Test with a real payout ($1.00 to your own Payoneer account)
20// 6. Set up error notification workflow for 401 responses