Create Whitelabel Checkout

POST /api/v1/payments/whitelabel

{
  "pricing": {
    "base_currency": "USD",
    "amount": "50.00"
  },
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "quote_id": "quote_1a2b3c4d5e6f",
  "payment_method": "bank_transfer",
  "phone_number": "+2348012345678",
  "bank_account_number": "0123456789",
  "success_url": "https://yoursite.com/payment/success",
  "cancel_url": "https://yoursite.com/payment/cancelled",
  "metadata": {
    "order_id": "ORD-12345"
  },
  "expires_in_minutes": 60
}

// Step 1: Get a quote for the payment
const quoteResponse = await fetch('https://api.usesyncpay.com/api/v1/payments/quotes', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_abc123xyz...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pricing: {
      base_currency: 'USD',
      amount: '100.00'
    },
    payment_method: 'bank_transfer',
    to_currency: 'NGN',
    customer_email: 'user@example.com'
  })
});

const quote = await quoteResponse.json();

// Step 2: Show customer the quote amount (NGN 150,000)
displayQuote({
  amount: quote.amount,
  currency: quote.currency,
  exchangeRate: quote.exchange_rate
});

// Step 3: Customer enters bank account number in your UI
const bankAccount = await getUserBankAccount(); // "0123456789"

// Step 4: Create whitelabel checkout and initiate payment
const paymentResponse = await fetch('https://api.usesyncpay.com/api/v1/payments/whitelabel', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_abc123xyz...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pricing: {
      base_currency: 'USD',
      amount: '100.00'
    },
    customer_email: 'user@example.com',
    customer_name: 'Jane Doe',
    quote_id: quote.quote_id,
    payment_method: 'bank_transfer',
    bank_account_number: bankAccount,
    metadata: {
      transaction_id: 'TXN-789'
    }
  })
});

const payment = await paymentResponse.json();

// Step 5: Display payment instructions to customer
displayPaymentInstructions({
  status: payment.status,
  amount: payment.amount,
  currency: payment.currency,
  instructions: payment.payment_instructions,
  reference: payment.provider_reference
});

{
  "checkout_id": "chk_1a2b3c4d5e6f",
  "charge_id": "chr_9x8y7z6w5v",
  "status": "PENDING",
  "amount": "150000.00",
  "currency": "NGN",
  "payment_method": "bank_transfer",
  "payment_provider": null,
  "provider_reference": "REF-12345",
  "payment_instructions": {
    "type": "bank_transfer",
    "bank_name": "Access Bank",
    "account_number": "9876543210",
    "account_name": "SyncPay Collections",
    "reference": "REF-12345",
    "instructions": "Transfer NGN 150,000 to the account above using the reference code"
  },
  "expires_at": "2026-01-24T15:30:00.000Z",
  "created_at": "2026-01-24T14:30:00.000Z"
}

{
  "type": "bank_transfer",
  "bank_name": "Access Bank",
  "account_number": "9876543210",
  "account_name": "SyncPay Collections",
  "reference": "KORA-REF-12345",
  "instructions": "Transfer NGN 150,000 to the account above using the reference code"
}

{
  "type": "mobile_money",
    "provider": "MTN",  // Mobile money provider (customer-facing)
  "phone_number": "+233200123456",
  "reference": "MM-REF-12345",
  "instructions": "Send GHS 620 to the number above with reference MM-REF-12345"
}

{
  "type": "crypto",
  "network": "TRC20",
  "wallet_address": "TXY7GhbJ9kLmN3oPqR5sTuV8wXyZ1aB2cD",
  "amount": "50.00",
  "currency": "USDT",
  "reference": "CRYPTO-REF-12345",
  "instructions": "Send exactly 50.00 USDT (TRC20) to the address above"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "quote_id": "Quote expired or not found. Please get a new quote.",
      "payment_method": "payment_method does not match the quote"
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

// 1. Create whitelabel checkout
const payment = await createWhitelabelCheckout({
  payment_method: 'mobile_money',
  phone_number: '+233200123456',
  // ...
});

// 2. Customer receives mobile money prompt on their phone
// 3. Customer approves payment on their phone
// 4. You receive webhook notification
// 5. Update your UI based on webhook

// 1. Create whitelabel checkout
const payment = await createWhitelabelCheckout({
  payment_method: 'bank_transfer',
  bank_account_number: '0123456789',
  // ...
});

// 2. Display bank account details to customer
displayBankDetails({
  bankName: payment.payment_instructions.bank_name,
  accountNumber: payment.payment_instructions.account_number,
  reference: payment.payment_instructions.reference,
  amount: payment.amount
});

// 3. Customer makes manual bank transfer
// 4. Payment is detected and processed
// 5. You receive webhook notification
// 6. Update customer's order status

// 1. Create whitelabel checkout
const payment = await createWhitelabelCheckout({
  payment_method: 'crypto',
  // ...
});

// 2. Display wallet address and amount
displayCryptoPayment({
  address: payment.payment_instructions.wallet_address,
  amount: payment.payment_instructions.amount,
  currency: payment.payment_instructions.currency,
  network: payment.payment_instructions.network
});

// 3. Customer sends crypto to address
// 4. Blockchain confirms transaction
// 5. You receive webhook notification