🐘PHP SDK

The Moneroo PHP SDK is a comprehensive library that enables PHP developers to interact with the Moneroo Payment Orchestration service.

Requirements

• PHP 7.4 and later.

Installation

You can install the package via composer:

composer require moneroo/moneroo-php

Payment

The Moneroo\Payment class provides methods for initialise, verifying, retrieving, and marking payments as processed. You can use it like so:

Initialise Payment

To create a payment, you need to pass an array of payment data to the create method. The array must contain the following keys:

Here are the required fields in a table format:

Field Name	Type	Required	Description
amount	integer	Yes	The payment amount.
currency	string	Yes	The currency of the payment.
description	string	No	Description of the payment.
return_url	string	Yes	Callback URL for payment updates.
customer.email	string	Yes	Customer's email address.
customer.first_name	string	Yes	Customer's first name.
customer.last_name	string	Yes	Customer's last name.
customer.phone	string	No¹	Customer's phone number.
customer.address	string	No¹	Customer's address.
customer.city	string	No¹	Customer's city.
customer.state	string	No¹	Customer's state.
customer.country	string	No¹	Customer's country.
customer.zip	string	No¹	Customer's zip code.
metadata	array	No²	Additional data for the payment.
methods	array	No³	Allowed payment methods.

1. If not provided, the customer can be prompted to enter these details during the payment process based on the selected payment method.

2. There Should be an array of key-value pairs. Only string values are allowed.

3. If not provided, all available payment methods will be allowed. Array should contain only supported payment methods.

Example Usage

$paymentData = [
    'amount' => 100,
    'currency' => 'USD',
    'customer' => [
        'email' => '[e-mail]',
        'first_name' => 'John',
        'last_name' => 'Doe',
        'phone' => '123456789',
        'address' => '123 Main St',
        'city' => 'Los Angeles',
        'state' => 'CA',
        'country' => 'USA',
        'zip' => '90001',
    ],
    'description' => 'Payment for order #123',
    'return_url' => 'https://yourwebsite.com/thanks',
    'metadata' => [
        'order_id' => '123',
        'customer_id' => '456',
    ],
    'methods' => ['card', 'orange_ci'],
];
$monerooPayment = new \Moneroo\Payment($secretKey);
$payment = $monerooPayment->init($paymentData);

// Redirect the customer to the Checkout URL
header('Location: ' . $payment->checkout_url);

The create method returns an object containing the payment details, including the transaction ID, Checkout URL where yous should redirect the customer to complete the payment. You can use this transaction ID to verify the payment later on.

Verify Payment

You can verify a payment by its transaction ID. This is useful when you want to check the status of a payment before processing an order on your end.

$transactionId = 'your-payment-transaction-id';

$monerooPayment = new \Moneroo\Payment($secretKey);
$payment = $monerooPayment->verify($transactionId);

Retrieve Payment

To get details of a payment, use the get method with the transaction ID.

$transactionId = 'your-payment-transaction-id';

$monerooPayment = new \Moneroo\Payment($secretKey);
$payment = $monerooPayment->get($transactionId);

Mark Payment as Processed

This is currently an experimental feature, please use with caution and report any issues you encounter.

This method is useful when you want to mark a payment as processed after you've received a successful callback from the Moneroo API, and you've processed the order on your end. This will also allow you to prevent duplicate orders or store transactions IDs in your database for future reference.

To mark a payment as processed, use the makeAsProcessed method with the transaction ID.

Example usage:

$transactionId = 'your-payment-transaction-id';

$monerooPayment = new \Moneroo\Payment($secretKey);
$payment = $monerooPayment->makeAsProcessed($transactionId);

Payout

The Moneroo\Payout class provides methods for initialise, verifying, and retrieving payouts.

Initialise Payout

To initialise a payout, you need to pass an array of data that meets the specified validation rules. The array must contain the following keys:

Here are the required fields in a table format:

Field Name	Type	Required	Description
amount	integer	Yes	The payout amount.
currency	string	Yes	The currency of the payout.
description	string	Yes	Description of the payout.
customer.email	string	Yes	Customer's email address.
customer.first_name	string	Yes	Customer's first name.
customer.last_name	string	Yes	Customer's last name.
return_url	string	Yes	Callback URL for payout updates.
customer.phone	string	No	Customer's phone number.
customer.address	string	No	Customer's address.
customer.city	string	No	Customer's city.
customer.state	string	No	Customer's state.
customer.country	string	No	Customer's country.
customer.zip	string	No	Customer's zip code.
metadata	array	No	Additional data for the payout.
method	string	Yes¹	Payout method
request_confirmation²	bool	No	If you want to require confirmation from customer.

1. Should be a Moneroo supported payout methods
2. This feature is currently in the experimental phase and is not available to all users/applications. It allows you to request confirmation from a customer before proceeding with payment. Moneroo will send an e-mail to the customer containing a confirmation code. The customer is then directed to a confirmation page where they can check the payment amount and account details. If the information is correct, the customer can enter the confirmation code to approve or reject the payment request. This function is a valuable tool for avoiding incorrect information or fraudulent transactions. If the user does not respond within 15 minutes, the payment request will be automatically cancelled.

In addition to the above information, you need to add payout methods required fields for account details. For example, if the payment method is mtn_bj, you should provide msisdn fields in recipient object.

This is different from user information, it accounts where money will be paid. For more information, please check the required fields for each payout method.

$payoutData = [
    'amount' => 100,
    'currency' => 'USD',
    'customer' => [
        'email' => '[e-mail]',
        'first_name' => 'John',
        'last_name' => 'Doe',
        // other customer details...
    ],
    'description' => 'Salary payment',
    'method' => 'mtn_bj',
    'recipient => [
        'msisdn' => '22912345678', // required field for mtn_bj payout method
    ],
   'metadata' => [
        'payout_id' => '123',
        'customer_id' => '456',
    ],
];

$monerooPayout = new Moneroo\Payout($secretKey);
$payout = $monerooPayout->init($payoutData);

The create method returns an object containing the payout details, including the transaction ID, and the payout status. You can use this transaction ID to verify the payout later on.

Verify Payout

You can verify a payout by its transaction ID.

$transactionId = 'your-payout-transaction-id';

$monerooPayout = new Moneroo\Payout($secretKey);
$payout = $monerooPayout->verify($transactionId);

Retrieve Payout

To get details of a payout, use the get method with the transaction ID.

$transactionId = 'your-payout-transaction-id';

$payout = new \Moneroo\Payout($secretKey);
$payout = $payout->get($transactionId);

Exception Handling

The SDK comes with a number of custom exceptions to help you manage potential errors that may occur when using the Moneroo API. These exceptions are as follows:

• InvalidPayloadException: This exception is thrown when the payload sent to the API does not meet the expected criteria.

• ForbiddenException: This exception is thrown when an action is attempted that the authenticated user does not have the necessary permissions for.

• InvalidResourceException: This exception is thrown when a request is made to a non-existent or invalid resource.

• ServerErrorException: This exception is thrown when there is an error on the server's side.

• NotAcceptableException: This exception is thrown when the client request's content characteristics are not acceptable according to the Accept headers sent in the request.

• ServiceUnavailableException: This exception is thrown when the service is currently unavailable, perhaps due to maintenance or load issues on the server.

• UnauthorizedException: This exception is thrown when the request lacks valid authentication credentials for the target resource.

For each exception, you can access the error message by calling $exception->getMessage(), and the error code (if available) by calling $exception->getCode().

Support

If you have any questions or need help, feel free to contact us.

We are always happy to help you with any questions you may have.

Security Vulnerabilities

If you discover a security vulnerability within Moneroo PHP SDK, please send an e-mail to Moneroo Security via [e-mail].

All security vulnerabilities will be promptly addressed.

License

The Moneroo PHP SDK is open-sourced software licensed under the MIT license.