> ## Documentation Index
> Fetch the complete documentation index at: https://developers.dwolla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP

> Use Dwolla's SDK for PHP to build applications that interact with the Dwolla API to perform account-to-account payment functions.

`dwolla-php` is available on [Packagist](https://packagist.org/packages/dwolla/dwolla-php) with [source code](https://github.com/Dwolla/dwolla-php) available on our GitHub page.

<Warning> **Beta Release** – This SDK is currently in beta. All API operations are fully supported, and we're gathering feedback from early adopters before making this generally available. Breaking changes may occur as we continue refining the SDK. Please use caution when integrating into production environments. We welcome beta users to integrate, report issues, and help us identify any edge cases. </Warning>

## Getting Started

### Installation

The SDK relies on [Composer](https://getcomposer.org/) to manage its dependencies.

To install the SDK and add it as a dependency to an existing `composer.json` file:

```shell theme={"dark"}
composer require "dwolla/dwolla-php"
```

### Initialization

Before any API requests can be made, you must first determine which environment you will be using, as well as fetch the application key and secret. To fetch your application key and secret, please visit one of the following links:

* Production: [https://dashboard.dwolla.com/applications](https://dashboard.dwolla.com/applications)
* Sandbox: [https://dashboard-sandbox.dwolla.com/applications](https://dashboard-sandbox.dwolla.com/applications)

Finally, you can create an instance of `Dwolla` with your application credentials:

```php theme={"dark"}
declare(strict_types=1);

require 'vendor/autoload.php';

use Dwolla;
use Dwolla\Models\Components;

$sdk = Dwolla\Dwolla::builder()
    ->setSecurity(
        new Components\Security(
            clientID: 'YOUR_CLIENT_ID',
            clientSecret: 'YOUR_CLIENT_SECRET',
        )
    )
    ->build();
```

## Making Requests

Once you've created a `Dwolla` client, you can make requests using the SDK methods.

### High-Level SDK Methods

The PHP SDK provides strongly-typed methods for all Dwolla API operations:

```php theme={"dark"}
// Get root API information
$response = $sdk->root->get();

// List customers
$response = $sdk->customers->list();

// Get customer details
$response = $sdk->customers->get(id: 'customer-id-here');
```

### Authentication

The SDK supports multiple authentication schemes:

#### OAuth2 Client Credentials (Recommended)

```php theme={"dark"}
use Dwolla;
use Dwolla\Models\Components;

$sdk = Dwolla\Dwolla::builder()
    ->setSecurity(
        new Components\Security(
            clientID: 'YOUR_CLIENT_ID',
            clientSecret: 'YOUR_CLIENT_SECRET',
        )
    )
    ->build();
```

#### Application Access Token Creation

When creating application access tokens, you'll need to provide Basic Authentication at the request level:

```php theme={"dark"}
use Dwolla;
use Dwolla\Models\Operations;

$sdk = Dwolla\Dwolla::builder()->build();

$request = new Operations\CreateApplicationAccessTokenRequest(
    grantType: Operations\GrantType::ClientCredentials,
);
$requestSecurity = new Operations\CreateApplicationAccessTokenSecurity(
    basicAuth: 'YOUR_BASIC_AUTH',
);

$response = $sdk->tokens->create(
    request: $request,
    security: $requestSecurity
);

if ($response->object !== null) {
    // handle response
}
```

### Working with Transfers

```php theme={"dark"}
// Initiate a transfer
$response = $sdk->transfers->create(/* transfer parameters */);

// Get transfer details
$response = $sdk->transfers->get(id: 'transfer-id-here');

// Cancel a transfer (if eligible)
$response = $sdk->transfers->cancel(id: 'transfer-id-here');
```

### Working with Funding Sources

```php theme={"dark"}
// List customer funding sources
$response = $sdk->customers->fundingSources->list(id: 'customer-id-here');

// Create a funding source
$customerUrl = "https://api-sandbox.dwolla.com/customers/customer-id-here";
$response = $sdk->customers->fundingSources->create(
    id: 'customer-id-here',
    requestBody: [
        "routingNumber" => "222222226",
        "accountNumber" => "123456789",
        "bankAccountType" => "checking",
        "name" => "My Checking Account"
    ]
);

// Get funding source balance
$response = $sdk->fundingSources->balance->get(id: 'funding-source-id-here');
```

### Error Handling

The SDK provides comprehensive error handling with typed exception classes:

```php theme={"dark"}
use Dwolla;
use Dwolla\Models\Errors;
use Dwolla\Models\Operations;

$sdk = Dwolla\Dwolla::builder()->build();

try {
    $request = new Operations\CreateApplicationAccessTokenRequest(
        grantType: Operations\GrantType::ClientCredentials,
    );
    $requestSecurity = new Operations\CreateApplicationAccessTokenSecurity(
        basicAuth: 'YOUR_BASIC_AUTH',
    );

    $response = $sdk->tokens->create(
        request: $request,
        security: $requestSecurity
    );

    if ($response->object !== null) {
        // handle response
    }
} catch (Errors\UnauthorizedExceptionThrowable $e) {
    // handle unauthorized error
    throw $e;
} catch (Errors\APIException $e) {
    // handle default exception
    throw $e;
}
```

By default, an API error will raise an `Errors\APIException` exception, which has the following properties:

| Property       | Type                                   | Description           |
| -------------- | -------------------------------------- | --------------------- |
| `$message`     | `string`                               | The error message     |
| `$statusCode`  | `int`                                  | The HTTP status code  |
| `$rawResponse` | `?\Psr\Http\Message\ResponseInterface` | The raw HTTP response |
| `$body`        | `string`                               | The response content  |

### Server Selection

You can specify which Dwolla environment to use:

```php theme={"dark"}
use Dwolla;

// Use sandbox environment
$sdk = Dwolla\Dwolla::builder()
    ->setServer('sandbox')
    ->build();

// Use production environment
$sdk = Dwolla\Dwolla::builder()
    ->setServer('prod')
    ->build();

// Use custom server URL
$sdk = Dwolla\Dwolla::builder()
    ->setServerURL('https://api-sandbox.dwolla.com')
    ->build();
```

| Name      | Server                           | Description       |
| --------- | -------------------------------- | ----------------- |
| `prod`    | `https://api.dwolla.com`         | Production server |
| `sandbox` | `https://api-sandbox.dwolla.com` | Sandbox server    |

## Available Resources and Operations

The SDK provides access to the following resources:

* **Root** - API entry point
* **Tokens** - Application access token management
* **Accounts** - Account details, funding sources, transfers, mass payments, and exchanges
* **Customers** - Customer management, beneficial owners, documents, funding sources, transfers, labels, KBA, and exchanges
* **Beneficial Owners** - Beneficial owner management and documents
* **Business Classifications** - Business classification lookup
* **Documents** - Document retrieval
* **Events** - Event listing and retrieval
* **Exchange Partners** - Exchange partner management
* **Exchanges** - Exchange resource management and sessions
* **Exchange Sessions** - Exchange session management
* **Funding Sources** - Funding source management, balances, micro-deposits, and VAN routing
* **KBA** - Knowledge-based authentication
* **Labels** - Label management, ledger entries, and reallocations
* **Mass Payments** - Mass payment initiation and management
* **Transfers** - Transfer initiation, retrieval, cancellation, and fee management
* **Webhooks** - Webhook retrieval and retry management
* **Webhook Subscriptions** - Webhook subscription management
* **Sandbox Simulations** - Bank transfer processing simulation (Sandbox only)

For detailed information on each resource and its operations, see the [SDK documentation on GitHub](https://github.com/Dwolla/dwolla-php/tree/main/docs/sdks).

## Community

* If you have any feedback, please reach out to us on [our forums](https://discuss.dwolla.com/) or by [creating a GitHub issue](https://github.com/Dwolla/dwolla-php/issues/new).
* While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.