README

A small Laravel-friendly SDK for calling DotaPay APIs:

• customers/*
• payment/*
• settlements/*

Authentication is handled with a Private Key sent as a request header (default: DPPRIVATEKEY).

This package is an SDK (HTTP client). It does not add routes to your application.

Requirements

• PHP 8.1+
• Laravel 10 or 11

Installation

composer require dotapay/laravel-sdk

Publish the config (optional):

php artisan vendor:publish --tag=dotapay-config

Configuration

Add these to .env:

DOTAPAY_BASE_URL=https://YOUR-TENANT-DOMAIN.dotapay.ng
DOTAPAY_API_PREFIX=api/v1
DOTAPAY_PRIVATE_KEY=PRIV_DP_xxxxxx
DOTAPAY_PRIVATE_KEY_HEADER=DPPRIVATEKEY

Usage

Customers

use DotaPay\LaravelSdk\Facades\Dotapay;

// Create (fails if reference exists)
$created = Dotapay::customers()->create([
  'first_name' => 'John',
  'last_name' => 'Doe',
  'bvn' => '12345678901',
  'dob' => '1998-03-17',
  'email' => 'john@example.com',
  'reference' => 'my-app-user-123',
  'type' => 'wallet',
]);

// Create-or-get (idempotent by reference)
$customer = Dotapay::customers()->createOrGetByReference([
  'first_name' => 'John',
  'last_name' => 'Doe',
  'bvn' => '12345678901',
  'dob' => '1998-03-17',
  'email' => 'john@example.com',
  'reference' => 'my-app-user-123',
  'type' => 'wallet',
]);

// Show by id/code/reference
$found = Dotapay::customers()->show('my-app-user-123');

// Balance
$balance = Dotapay::customers()->balance('my-app-user-123');

Payment

$txn = Dotapay::payment()->request([
  'public_key' => 'PUB_DP_xxxxx',
  'order_id' => 'ORDER-10001',
  'customer_email' => 'john@example.com',
  'customer_name' => 'John Doe',
  'items' => [
    ['id' => 'sku-1', 'name' => 'Item 1', 'unit_cost' => 1000, 'quantity' => 1],
  ],
]);

$status = Dotapay::payment()->status($txn['transaction']['data']['reference'] ?? 'REF_...');

Settlements

$list = Dotapay::settlements()->index(['per_page' => 20]);

$withdraw = Dotapay::settlements()->withdraw([
  'wallet_id' => 'WALLET_ABC_live',
  'amount' => 5000, // NGN
  'settlement_bank_id' => 'SETTBANK_...',
]);

$direct = Dotapay::settlements()->withdrawDirect([
  'wallet_id' => 'WALLET_ABC_live',
  'amount' => 5000, // NGN
  'bank_code' => '058',
  'account_number' => '0123456789',
  'reference' => 'WD-'.now()->timestamp,
]);

/**
 * Customer-scoped withdrawals
 * $identifier can be customer id / code / reference (same pattern as customers()->show())
 */

// Customer -> settlement bank (uses customer context)
$customerWithdraw = Dotapay::settlements()->withdrawCustomer('my-app-user-123', [
  'amount' => 5000,
  'settlement_bank_id' => 'SETTBANK_...',
  // 'reference' => 'CWD-'.now()->timestamp,
]);

// Customer -> bank account (direct)
$customerDirect = Dotapay::settlements()->withdrawDirectCustomer('my-app-user-123', [
  'amount' => 5000,
  'bank_code' => '058',
  'account_number' => '0123456789',
  'reference' => 'CWD-'.now()->timestamp,
]);

/**
 * Customer wallet transfer (customer -> wallet)
 * Useful when you want to move funds from a customer's wallet to another wallet (e.g. business wallet)
 */
$customerWalletTransfer = Dotapay::settlements()->withdrawCustomerWallet('my-app-user-123', [
  'amount' => 5000,
  'wallet_id' => 'DEST_WALLET_live', // destination wallet slug/id (as required by your API)
  'reference' => 'CWT-'.now()->timestamp,
]);

/**
 * Bulk direct withdrawals
 */
$bulk = Dotapay::settlements()->withdrawDirectBulk([
  'wallet_id' => 'WALLET_ABC_live',
  'items' => [
    [
      'amount' => 5000,
      'bank_code' => '058',
      'account_number' => '0123456789',
      'reference' => 'WD-'.now()->timestamp.'-1',
    ],
    [
      'amount' => 7500,
      'bank_code' => '011',
      'account_number' => '0001112223',
      'reference' => 'WD-'.now()->timestamp.'-2',
    ],
  ],
]);

Multi-merchant platforms

If your application holds multiple DotaPay private keys, you can swap the key per request:

$dotapay = app('dotapay')->usingPrivateKey($businessPrivateKey);
$customer = $dotapay->customers()->show('my-ref');

Error handling

By default, non-2xx responses throw DotaPay\LaravelSdk\Exceptions\DotapayRequestException. Disable throws via:

DOTAPAY_THROW=false

License

MIT