Download the PHP package billie/api-php-sdk without Composer

Billie PHP SDK

The Billie PHP SDK enables you to integrate the REST API of Billie easily and quickly into an existing code base and to use it.

Requirements

• PHP 7.4 or higher
• cURL (included and enabled in a standard PHP distribution)
• OpenSSL (included and enabled in a standard PHP distribution)

You need a Billie account to receive the necessary credentials.

Installation with Composer

You can use the Billie PHP SDK library as a dependency in your project with Composer (preferred technique).

Follow these installation instructions if you do not already have Composer installed. A composer.json file is available in the repository, and it has been referenced from Packagist.

To install the SDK, just execute the following command:

Usage

General usage

For every request there is a

• request service (instance of \Billie\Sdk\Service\Request\AbstractRequest) Knows anything about the request itself (url, method, authorization)
• request model (instance of \Billie\Sdk\Model\Response\AbstractRequestModel) Knows anything about the parameters of the request, and acts as DTO to submit the data to the request service
• response model (instance of \Billie\Sdk\Model\Response\AbstractResponseModel) Knows anything about the response data, and acts as DTO to receives the data from the request service Note: in some cases there is not response. Just a true if the request was successful

Get a \Billie\Sdk\HttpClient\BillieClient-instance

Use the \Billie\Sdk\Util\BillieClientFactory to get a new instance.

The factory will automatically request a new auth-token from the gateway and will store it (with the whole instance) in a static variable. So it will not produce a new request, if you request a new BillieClient-instance.

Provide a boolean as third parameter to define if the request goes against the sandbox or not.

Get an instance of a request service

You can simply create a new instance of the corresponding class.

Example:

You must not provide the BillieClient via the constructor, but you should set it, before calling execute on the request service.

Example:

Models

Request models: Validation

Every field of a request model (not response models) will be validated automatically, during calling its setter. If you provide a wrong value or in an invalid format, an \Billie\Sdk\Exception\Validation\InvalidFieldException will be thrown.

You can disable this automatic validation, by calling the method setValidateOnSet on the model:

The model got validate at least by the request service, to make sure that all data has been provided, and you will get no validation exception through the gateway.

Response models

Every response model is set to be read-only.

You can not set any fields on this model. You will get a BadMethodCallException.

Requests

This documentation should not explain the whole usage of each request. It should only show the main information about each request, and the main usage.

GetTokenRequest

With this service you can create a new auth-token for your credentials.

This service got called automatically, if you use the \Billie\Sdk\Util\BillieClientFactory to get the BillieClient.

This request service is the only one, which do NOT need a BillieClient-instance.

Usage

ValidateTokenRequest

Use this service to verify if your token is still valid. If the token is not valid anymore, you have to request a new auth-token.

If the token is valid, you will get a response. Otherwise, you will get an \Billie\Sdk\Exception\UserNotAuthorizedException.

Usage

Note: the request model does not have any content. Don't be confused.

RevokeTokenRequest

Use this service to revoke the token. The token should be already stored in the Billie-Client instance.

Usage

Note: the request model does not have any content. Don't be confused.

CreateSessionRequest

Use this service to create a new checkout session on the gateway for the customer.

Usage

CheckoutSessionConfirmRequest

If the user has confirmed the payment (through the widget), you can confirm the order.

It will create an order finally on the gateway.

Note: Please have a look into each model, which field has to be submitted.

Usage

GetCheckoutAuthorizationRequest

Use this service to fetch the details about the authorized current checkout-session.

Usage

CreateOrderRequest

This request should be only used, if the seller creates the order manually (telephone, api, ...)

It will create a new order with the initial state of created without displaying a widget to confirm.

Note: Please have a look into each model, which field has to be submitted.

Usage

This service will throw the following exceptions, which should be handled by the integration:

• Billie\Sdk\Exception\OrderDecline\DebtorLimitExceededException - the debtor-limit has been exceeded.
• Billie\Sdk\Exception\OrderDecline\DebtorNotIdentifiedException - the gateway was not able to identify the debtor
• Billie\Sdk\Exception\OrderDecline\InvalidDebtorAddressException - the gateway was not able to verify the address
• Billie\Sdk\Exception\OrderDecline\RiskPolicyDeclinedException - the order got declined for risk reasons
• Billie\Sdk\Exception\OrderDecline\OrderDeclinedException - the order got declined by any other reasons

UpdateOrderRequest

Use this order, to update information about the order. Please have a look into the api documentation, which fields are updatable. Please also have a look into each model, to find out, which fields this sdk can process.

Usage

GetOrderRequest

Use this service to retrieve all order information

Usage

CreateInvoiceRequest

Use this service to retrieve all order information

Usage

GetInvoiceRequest

Use this service to fetch an invoice.

Usage

UpdateInvoiceRequest

Use this service to update the invoice number or url.

Usage

CancelInvoiceRequest

Use this service to cancel the invoice.

Usage

CreateCreditNoteRequest

Use this service to add a (partial) refund/credit-note to an invoice

Usage

ConfirmPaymentRequest

Use this request to notify the gateway about a received payment.

Usage

CancelOrderRequest

Use this request to cancel the order completely.

GetLegalFormsRequest

Use this request to get all legal forms supported by Billie.

Note: This request is always cached. So you can use it anytime without making a new request against the gateway. The cache will be automatically flushed.

Usage

Note: the request model does not have any content. Don't be confused.

Integration utilities

AddressHelper

Class: \Billie\Util\AddressHelper Use this class to separate the house number from the street name.

Usage

Further features

Automatic tax amount calculation

Model: \Billie\Sdk\Model\Amount

The model has field called tax. It contains the tax-amount of the line-item/order

To keep the calculations as simple as possible, you can omit the parameter tax. So you must not provide all information. The model will calculates itself.

Example 1:

Example 2:

Example 3:

Example 4:

Example 4 (wrong usage):

If you set the tax manually the model will not calculate the values. It will submit the values, as you provide it.

This will end up, that the gateway will give you an error, cause invalid data.

Symfony services

If you use a Symfony based system, you can use the request services as a service. So you can inject it very easily. Just register the request services in your services.xml (or yaml)

You can just inject the request services to your classes.

Example:

Create BillieClient via a factory

Do not forget to define a factory for your \Billie\Sdk\HttpClient\BillieClient-instance to get the Client injected into the request service:

Provide BillieClient via setter

If you can not use the factory to create an instance of \Billie\Sdk\HttpClient\BillieClient, you can also set the BillieClient manually to the request service:

Logging

You can enable logging for all API requests (we may extend this functionality to log additional events in the future).

To activate logging, simply provide us with an instance of \Psr\Log\LoggerInterface. A commonly used logger is the monolog/monolog package.

Please note that only loggers implementing the mentioned interface can be passed. If you are using a custom logger, ensure that it implements the LoggerInterface. Also, don't forget to install the psr/log package if it’s not already included.

Important: Do not configure a debug logger in production, as this will log all requests (successful and failed). If you only want to log failed requests, configure the logger to handle only ERROR level events.

Example: