# BN_CODE (PayPal Partner Attribution) — README Summary ------- This project sends PayPal API requests with a partner attribution header named `PayPal-Partner-Attribution-Id` (derived from `process.env.BN_CODE`). That header is used to attribute API calls to your PayPal partner application. This README explains why `BN_CODE` is used, what happens if it is missing, what happens if it's wrong, and the current status found in this repository's `.env`. Where `BN_CODE` is used in this codebase -------------------------------------- - Primary implementation: `src/controllers/payment/paymentController.js` (used widely). - Typical PayPal endpoints where the header is added: - POST `/v1/oauth2/token` (get access token) - POST `/v2/checkout/orders` (create order) - POST `/v2/checkout/orders/{orderId}/capture` (capture) - POST `/v1/payments/payouts` (payouts) - POST `/v1/payments/referenced-payouts-items` (referenced payouts) - Refund endpoints (`/v2/payments/captures/{captureId}/refund`) - Partner/referral/onboarding endpoints (`/v2/customer/partner-referrals`, `/v1/customer/partners/.../merchant-integrations`) - Webhook verification (`/v1/notifications/verify-webhook-signature`) — token obtained using BN_CODE Why it is used --------------- - `BN_CODE` (the PayPal Partner Attribution Id) tells PayPal which partner application is making the request. - Effects: - Enables partner-specific features and routing. - May enable partner-level privileges (e.g., third-party onboarding, partner-fee handling, certain payout behaviors). - Provides attribution in PayPal reporting and logs. What happens if `BN_CODE` is NOT used or missing ----------------------------------------------- - PayPal treats requests as non-partner API calls (regular API client behavior). - Partner-only features may be unavailable or behave differently (merchant-integrations/partner referral flows may fail or report merchants as not "onboarded"). - Payout/funding behavior may change — e.g., recipient fees could be applied where partner attribution previously prevented them. - In short: API calls frequently still succeed, but partner attribution and partner-enabled behaviors are lost. What happens if `BN_CODE` is used but WRONG ------------------------------------------- - Requests will be attributed to an incorrect partner or an unrecognized partner id. - PayPal may not apply partner privileges; some endpoints may return errors or incomplete data. - Onboarding checks (payments_receivable) may return different results causing blocked disbursements or changes in fee treatment. - Behavior may be inconsistent across calls (some calls might succeed, others fail or return different fee breakdowns). Observed production symptom (context) ------------------------------------ - The codebase calls PayPal's payout APIs and always sends the full payout amount. The application itself does not subtract a 2.99% payout fee. - If assistant recipients are being charged 2.99% starting in August, the most likely causes are external (PayPal account/funding source change, PayPal policy change, or partner attribution mismatch), not an in-code fee deduction. Current BN_CODE status in this repository ----------------------------------------- - I checked the repository `.env` file at `./.env` and did NOT find a `BN_CODE` key present in that file. - This means `BN_CODE` is not defined in `.env` here. - The application code expects `process.env.BN_CODE` in many places (notably `src/controllers/payment/paymentController.js`). - Possible explanations: - `BN_CODE` is set as an environment variable on the server / CI / container rather than in `.env` (common for secrets). - `BN_CODE` was removed from `.env` or not committed to the repo for security reasons. What you should do next (recommended checklist) ---------------------------------------------- 1. Confirm where `BN_CODE` is set in your runtime environments (staging, production): - On Linux containers, check service environment variables or Docker/Kubernetes secret config. - On Windows (PowerShell) or launched services, check system environment variables or process manager config. 2. If `BN_CODE` is missing in the environment where fees changed, restore the previously working BN_CODE value for that environment (if you have it). 3. Reproduce in Sandbox with the same BN_CODE & funding source to confirm behavior: compare a July-style transaction (no recipient fee) vs a recent one (recipient fee). 4. Log PayPal responses around capture and payout (store the fee fields in `PayoutInfo` / logs) to capture exact fee objects returned by PayPal. 5. Contact PayPal partner support with sample transaction IDs (create/capture/payout) and provide the BN_CODE used — ask if partner attribution or account settings changed that would cause recipient fees. Quick instructions: set BN_CODE locally (PowerShell example) --------------------------------------------------------- - Example (temporary, PowerShell session only): ```powershell $env:BN_CODE = "YOUR-BN-CODE-HERE" # Start your Node server in the same shell so it picks up the env var node app.js ``` - To persist for your service, add `BN_CODE` to the service environment (system environment variables, Docker/Kubernetes secrets, or your cloud provider's configuration) — do NOT commit the value to git. Security note ------------- - BN_CODE identifies your PayPal partner integration. Treat it as sensitive configuration and do not commit it to version control. Use a secrets manager or environment configuration. If you want, I can: - Add a small startup check that fails/alerts if `BN_CODE` is missing. - Add additional logging around payouts to capture PayPal fee objects (helpful for diagnosing who was charged and why). - Create a quick script (sandbox) to reproduce a capture->payout flow and save responses for PayPal support. --- Created on: October 15, 2025 Location: `BN_CODE_README.md` (repo root)