{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab","admonition"]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay is the groundbreaking payment gateway that lets you integrate with the future of payments.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"tutorial-white-label-payment-solution","__idx":0},"children":["Tutorial: White-label payment solution"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-you-will-build","__idx":1},"children":["What you will build"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A reseller platform that:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Creates merchant accounts under your reseller client"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configures processor integrations for each merchant"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Processes payments on behalf of merchants"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reports on transactions across your merchant portfolio"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"architecture","__idx":2},"children":["Architecture"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TD\n A[Your Platform
type: reseller] --> B[Merchant A
type: merchant]\n A --> C[Merchant B
type: merchant]\n A --> D[Merchant C
type: merchant]\n B --> E[Users / API keys]\n B --> F[Integrations
TSYS, Vericheck]\n B --> G[Transactions]\n C --> H[Users / API keys]\n C --> I[Integrations]\n C --> J[Transactions]\n","diagramHtml":"

Your Platform
type: reseller

Merchant A
type: merchant

Merchant B
type: merchant

Merchant C
type: merchant

Users / API keys

Integrations
TSYS, Vericheck

Transactions

Users / API keys

Integrations

Transactions

","diagramHtmlDark":"

Your Platform
type: reseller

Merchant A
type: merchant

Merchant B
type: merchant

Merchant C
type: merchant

Users / API keys

Integrations
TSYS, Vericheck

Transactions

Users / API keys

Integrations

Transactions

"},"children":["flowchart TD\n A[Your Platform
type: reseller] --> B[Merchant A
type: merchant]\n A --> C[Merchant B
type: merchant]\n A --> D[Merchant C
type: merchant]\n B --> E[Users / API keys]\n B --> F[Integrations
TSYS, Vericheck]\n B --> G[Transactions]\n C --> H[Users / API keys]\n C --> I[Integrations]\n C --> J[Transactions]\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-concepts","__idx":3},"children":["Key concepts"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Concept"},"children":["Concept"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reseller client"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Your platform's account — the parent for all merchants you onboard"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant client"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Each merchant account, created as a child of your reseller"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant API key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Each merchant gets their own API key for transaction processing"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Parent visibility"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Resellers can view and manage all child merchants and their data"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For details on the account model, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/account-hierarchy/clients-and-resellers"},"children":["Clients and resellers"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":4},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A reseller-type client account with Paradise Gateway"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your reseller API key — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/how-tos/setup/obtain-credentials"},"children":["Obtain API credentials"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Processor credentials (TSYS Merchant ID, Vericheck details) for each merchant"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-onboard-a-new-merchant","__idx":5},"children":["Step 1: Onboard a new merchant"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a merchant client under your reseller account."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests, os\n\nRESELLER_API_KEY = os.environ[\"PARADISE_RESELLER_API_KEY\"]\nBASE = os.environ.get(\"PARADISE_BASE_URL\", \"https://api.dev.paradisegateway.net\")\nHEADERS = {\"Content-Type\": \"application/json\", \"APIKEY\": RESELLER_API_KEY}\n\ndef create_merchant(dba: str, parent_id: str, contact: dict) -> dict:\n resp = requests.post(f\"{BASE}/v1/clients\", headers=HEADERS, json={\n \"dba\": dba,\n \"parent_id\": parent_id,\n \"type\": \"merchant\",\n \"admin_contact_details\": {\n \"first_name\": contact[\"first_name\"],\n \"last_name\": contact[\"last_name\"],\n \"email\": contact[\"email\"],\n \"phone\": contact.get(\"phone\", \"\"),\n \"time_zone\": contact.get(\"time_zone\", \"America/New_York\"),\n },\n })\n resp.raise_for_status()\n return resp.json()\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const RESELLER_API_KEY = process.env.PARADISE_RESELLER_API_KEY;\nconst BASE = process.env.PARADISE_BASE_URL || \"https://api.dev.paradisegateway.net\";\nconst headers = { \"Content-Type\": \"application/json\", \"APIKEY\": RESELLER_API_KEY };\n\nasync function createMerchant(dba, parentId, contact) {\n const resp = await fetch(`${BASE}/v1/clients`, {\n method: \"POST\",\n headers,\n body: JSON.stringify({\n dba,\n parent_id: parentId,\n type: \"merchant\",\n admin_contact_details: {\n first_name: contact.firstName,\n last_name: contact.lastName,\n email: contact.email,\n phone: contact.phone || \"\",\n time_zone: contact.timeZone || \"America/New_York\",\n },\n }),\n });\n if (!resp.ok) throw new Error(`Create merchant failed: ${resp.status}`);\n return resp.json();\n}\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-create-a-merchant-user-and-api-key","__idx":6},"children":["Step 2: Create a merchant user and API key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each merchant needs at least one user account, then an API key for processing."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import base64\n\ndef create_merchant_user(client_id: str, user_data: dict) -> dict:\n resp = requests.post(f\"{BASE}/v1/users\", headers=HEADERS, json={\n \"client_id\": client_id,\n \"first_name\": user_data[\"first_name\"],\n \"last_name\": user_data[\"last_name\"],\n \"email\": user_data[\"email\"],\n \"password\": user_data[\"password\"],\n \"time_zone\": user_data.get(\"time_zone\", \"America/New_York\"),\n })\n resp.raise_for_status()\n return resp.json()\n\ndef get_merchant_api_key(email: str, password: str) -> str:\n credentials = base64.b64encode(f\"{email}:{password}\".encode()).decode()\n resp = requests.post(\n f\"{BASE}/v1/auth/keys\",\n headers={\n \"Content-Type\": \"application/json\",\n \"Authorization\": f\"Basic {credentials}\",\n },\n )\n resp.raise_for_status()\n return resp.json()[\"key\"]\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"async function createMerchantUser(clientId, userData) {\n const resp = await fetch(`${BASE}/v1/users`, {\n method: \"POST\",\n headers,\n body: JSON.stringify({\n client_id: clientId,\n first_name: userData.firstName,\n last_name: userData.lastName,\n email: userData.email,\n password: userData.password,\n time_zone: userData.timeZone || \"America/New_York\",\n }),\n });\n if (!resp.ok) throw new Error(`Create user failed: ${resp.status}`);\n return resp.json();\n}\n\nasync function getMerchantApiKey(email, password) {\n const credentials = btoa(`${email}:${password}`);\n const resp = await fetch(`${BASE}/v1/auth/keys`, {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n Authorization: `Basic ${credentials}`,\n },\n });\n if (!resp.ok) throw new Error(`Get API key failed: ${resp.status}`);\n const body = await resp.json();\n return body.key;\n}\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Store credentials securely"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store each merchant's API key in your secrets manager — never in your database in plain text. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/security/secure-api-keys"},"children":["Secure API keys"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-configure-processor-integration","__idx":7},"children":["Step 3: Configure processor integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a TSYS integration so the merchant can process card transactions."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"def add_tsys_integration(merchant_api_key: str, config: dict) -> dict:\n merchant_headers = {\"Content-Type\": \"application/json\", \"APIKEY\": merchant_api_key}\n resp = requests.post(f\"{BASE}/v1/integrations\", headers=merchant_headers, json={\n \"name\": \"tsys\",\n \"is_active\": True,\n \"configuration\": {\n \"mid\": config[\"mid\"],\n \"tid\": config[\"tid\"],\n \"industry_type\": config.get(\"industry_type\", \"e_commerce\"),\n \"settlement_time\": config.get(\"settlement_time\", \"23:59:00\"),\n },\n })\n resp.raise_for_status()\n return resp.json()\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"async function addTsysIntegration(merchantApiKey, config) {\n const resp = await fetch(`${BASE}/v1/integrations`, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\", \"APIKEY\": merchantApiKey },\n body: JSON.stringify({\n name: \"tsys\",\n is_active: true,\n configuration: {\n mid: config.mid,\n tid: config.tid,\n industry_type: config.industryType || \"e_commerce\",\n settlement_time: config.settlementTime || \"23:59:00\",\n },\n }),\n });\n if (!resp.ok) throw new Error(`Add integration failed: ${resp.status}`);\n return resp.json();\n}\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-process-payments-on-behalf-of-merchants","__idx":8},"children":["Step 4: Process payments on behalf of merchants"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant's"]}," API key (not the reseller key) for transaction processing."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"def process_merchant_payment(merchant_api_key: str, amount: int, card: dict) -> dict:\n merchant_headers = {\"Content-Type\": \"application/json\", \"APIKEY\": merchant_api_key}\n resp = requests.post(f\"{BASE}/v1/transactions\", headers=merchant_headers, json={\n \"type\": \"card_sale\",\n \"amount\": amount,\n \"card\": {\n \"pan\": card[\"pan\"],\n \"expiry_month\": card[\"expiry_month\"],\n \"expiry_year\": card[\"expiry_year\"],\n \"cvv\": card[\"cvv\"],\n \"cardholder_name\": card[\"name\"],\n },\n })\n resp.raise_for_status()\n return resp.json()\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-portfolio-reporting","__idx":9},"children":["Step 5: Portfolio reporting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As a reseller, query transactions and merchants across your portfolio."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"def list_merchants() -> list:\n resp = requests.get(f\"{BASE}/v1/clients\", headers=HEADERS)\n resp.raise_for_status()\n return resp.json()[\"data\"]\n\ndef list_merchant_transactions(merchant_api_key: str, skip: int = 0, take: int = 50) -> dict:\n merchant_headers = {\"Content-Type\": \"application/json\", \"APIKEY\": merchant_api_key}\n resp = requests.get(\n f\"{BASE}/v1/transactions?skip={skip}&take={take}\",\n headers=merchant_headers,\n )\n resp.raise_for_status()\n return resp.json()\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-onboarding-flow","__idx":10},"children":["Complete onboarding flow"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"---\nconfig:\n theme: 'neutral'\n---\nsequenceDiagram\n participant Platform as Your Platform\n participant PG as Paradise Gateway\n Platform->>PG: POST /v1/clients (create merchant)\n PG-->>Platform: client_id\n Platform->>PG: POST /v1/users (create merchant user)\n PG-->>Platform: user_id\n Platform->>PG: POST /v1/auth/keys (Basic Auth)\n PG-->>Platform: merchant_api_key\n Platform->>PG: POST /v1/integrations (TSYS config)\n PG-->>Platform: integration_id\n Note over Platform: Merchant is ready to process\n","diagramHtml":"Paradise GatewayYour PlatformParadise GatewayYour PlatformMerchant is ready to processPOST /v1/clients (create merchant)client_idPOST /v1/users (create merchant user)user_idPOST /v1/auth/keys (Basic Auth)merchant_api_keyPOST /v1/integrations (TSYS config)integration_id","diagramHtmlDark":"Paradise GatewayYour PlatformParadise GatewayYour PlatformMerchant is ready to processPOST /v1/clients (create merchant)client_idPOST /v1/users (create merchant user)user_idPOST /v1/auth/keys (Basic Auth)merchant_api_keyPOST /v1/integrations (TSYS config)integration_id"},"children":["---\nconfig:\n theme: 'neutral'\n---\nsequenceDiagram\n participant Platform as Your Platform\n participant PG as Paradise Gateway\n Platform->>PG: POST /v1/clients (create merchant)\n PG-->>Platform: client_id\n Platform->>PG: POST /v1/users (create merchant user)\n PG-->>Platform: user_id\n Platform->>PG: POST /v1/auth/keys (Basic Auth)\n PG-->>Platform: merchant_api_key\n Platform->>PG: POST /v1/integrations (TSYS config)\n PG-->>Platform: integration_id\n Note over Platform: Merchant is ready to process\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":11},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automate onboarding"]}," — script the full create-client → create-user → get-key → add-integration flow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Separate API keys per merchant"]}," — never share keys across merchants."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store keys in a secrets manager"]}," — not in your database in plaintext."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use reseller key for management, merchant key for transactions"]}," — this enforces proper data isolation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Monitor across your portfolio"]}," — track approval rates and error rates per merchant to identify issues early."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":12},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/how-tos/clients-users/onboard-client"},"children":["Onboard a new client"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/how-tos/integrations/add-integration"},"children":["Add an integration"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/how-tos/reports/client-reports"},"children":["Client reports"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/account-hierarchy/users-and-roles"},"children":["Users and roles"]}]}]}]},"headings":[{"value":"Tutorial: White-label payment solution","id":"tutorial-white-label-payment-solution","depth":1},{"value":"What you will build","id":"what-you-will-build","depth":2},{"value":"Architecture","id":"architecture","depth":2},{"value":"Key concepts","id":"key-concepts","depth":3},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Onboard a new merchant","id":"step-1-onboard-a-new-merchant","depth":2},{"value":"Step 2: Create a merchant user and API key","id":"step-2-create-a-merchant-user-and-api-key","depth":2},{"value":"Step 3: Configure processor integration","id":"step-3-configure-processor-integration","depth":2},{"value":"Step 4: Process payments on behalf of merchants","id":"step-4-process-payments-on-behalf-of-merchants","depth":2},{"value":"Step 5: Portfolio reporting","id":"step-5-portfolio-reporting","depth":2},{"value":"Complete onboarding flow","id":"complete-onboarding-flow","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Tutorial: White-label payment solution","shortTitle":"White-label payments","intro":"Build a white-label payment platform using Paradise Gateway's multi-tenant client hierarchy. Onboard merchants under your brand, process payments on their behalf, and manage the full lifecycle programmatically.","type":"tutorial","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/tutorials/integration-patterns/white-label-solutions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}