ratapay/ratapayphp

Ratapay PHP Integration

Maintainers

Details

github.com/Ratapay/ratapayphp

Homepage

Source

Issues

Installs: 273

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 1

Forks: 2

Open Issues: 0

v1.0.16 2022-11-14 03:12 UTC

Requires

Requires (Dev)

MIT 96057600ebcf153a556505e05f7f362e446cfffd

  • Ratapay <tech.woop@ratapay.co.id>

ratapayratapayphp

This package is auto-updated.

Last update: 2024-09-14 07:15:49 UTC

README

A simple library to integrate laravel with your PHP Code. Be aware that this library is in the very early stage of development, only the most fundamental features available and no thorough test has been carried out to ensure reliable functionality.

Install

Via Composer

$ composer require ratapay/ratapayphp

Then require the autoload in your project

require_once "vendor/autoload.php";

The above require usually not necessary when using a framework such as Laravel. As the framework already has their package loader in place.

Usage

1. Keys and Secrets

Before you can use this library, you need to have a Ratapay account with at least Personal level Account.

The Keys and Secrets can be obtained from the account page -> profile -> view credentials menu

2. Invoice

Invoice is the primary requirement to create transaction in Ratapay. The transaction will be created with just the invoice being defined.

Instantiated with

$invoice = new \ratapay\ratapayphp\Invoice($data);

where $data is an array with key value format containing the data defined in the properties below

Properties

The first_period, second_period, and refund_threshold use a period format defined as:

[1-9][D/M/Y]

where the first part is the nominator and the second part is the unit in either day (D), month (M), or Year (Y)

for example a 7 day period would be 7D

To see the list of available Payment System ID (paysystem) send a GET request to https://api.ratapay.co.id/v2/gateway/list for production or https://dev.ratapay.co.id/v2/gateway/list for sandbox

Method

3. Item

Item defines the content of the invoice in more detail.

Instantiated with

$item = new \ratapay\ratapayphp\Item($data);

where $data is an array with key value format containing the data defined in the properties below

Properties

4. Beneficiary

Beneficiary defines who will get the share from the invoice transaction.

Instantiated with

$beneficiary = new \ratapay\ratapayphp\Beneficiary($data);

where $data is an array with key value format containing the data defined in the properties below

Properties

5. Client

Client will process the request to Ratapay

Instantiated with

$client = new \ratapay\ratapayphp\Client($merchant_id, $merchant_secret, $api_key, $api_secret, $sandbox);

Data on each parameter except $sandbox can be obtained from point 1. Keys and Secrets.

Whereas the $sandbox is a flag to define wether to use sandbox mode or not, default is true.

A. Creating Transaction

$result = $client->createTransaction($invoice);

Where $invoice is an invoice object which already been defined before

The $result will be an object which contain data as follow:

  1. status : success or failed, indicating transaction creation result status
  2. message : an error message of the reason why the transaction creation failed, only available if status is failed
  3. payment_url : url for the payment process for the payer, only available if status is success
  4. data : array of string indicating which invoice that the transaction is based on, containing: invoice_id, note, and ref as the reference number from Ratapay, only available if status is success

B. Listing Transaction

$result = $client->listTransaction($reference = '', $invoice_id = '', $creation_time = [], $paid_time = [], $offset = 0, $limit = 5);

The $result will be an object which contain data as follow:

  1. status : success or failed, indicating transaction listing result status
  2. list : list of retrieved transaction data
  3. count : total count of transaction records with specified conditions
  4. totalAmount : total amount of transaction records retrieved

C. Execute Split

Normally, the refundable invoice fund will be split automatically if it is already past the refund threshold. However, if there is need to split it earlier, this function can be used.

$result = $client->confirmSplit($reference, $item_ids = []);

If item_ids is specified, only item matched item will be splitted.

D. Extend Refund

It can be used to extend the refund threshold.

$result = $client->extendRefund($reference, $period, $item_ids = []);

If item_ids is specified, only item matched item will have its refund threshold extended.

E. Execute Refund

It can be used to execute refund before refund threshold.

$result = $client->confirmRefund($reference, $params);

The $result will be an object which contain data as follow:

  1. status : success or failed, indicating refund request status

If doing full refund, the params is not used. But if doing partial refund, the params should be filled using these structures:

  • params structure to refund partially for the whole invoice, use item ID 0
$params = [
        0 => [
            'type' => {% or $}
            'value' => {value}
        ]
]
  • params structure to refund partially for each specific item
$params = [
        {item_id_1} => [
            'type' => {% or $} // optional, default $, will be ignored if specified but using qty
            'value' => {value}, // required if no qty specified
            'qty' => {qty} // required if no value specified
        ],
        {item_id_n} => [
            'type' => {% or $}, // optional, default $, will be ignored if specified but using qty
            'value' => {value}, // required if no qty specified
            'qty' => {qty} // required if no value specified
        ]
]

% means in percentage, maximum 100,

$ means in value, up to item subtotal value

F. Getting Own Account Info

$result = $client->getAccount();

The $result will be an object which contain data as follow:

  1. status : success or failed, indicating account info fetching status
  2. account : account info details

G. Registering New Account

$result = $client->registerAccount(['email'=>$email,'name'=>$name,'password'=>$password]);

The $result will be an object which contain data as follow:

  1. status : success or failed, failed means account with the email already exist
  2. account : account info details if account creation status is success
  3. error : short info about the error
  4. message : long error message info

H. Getting Another Account Info

$result = $client->getAccount(['email' => $email]);

The $result will be an object which contain data as follow:

  1. status : success or failed, indicating account info fetching status
  2. account : account info details if request status is success
  3. error : short info about the error
  4. message : long error message info

If the error is 'none' or 'waiting' then you have to ask user consent to link their account to your merchant data by executing following method

$result = $client->linkAccount($email, $username);

$username is optional, it can be used to track the user if your system identify user by their username and the user change their email. The $result will be an object which contain data as follow:

  1. status : success or failed, indicating account info fetching status
  2. link : link to ratapay consent page to approve the linkage
  3. error : short info about the error
  4. message : long error message info

I. Add New Beneficiaries

New beneficiaries can only be added to an existing invoice item. Hence, make sure to prepare item that have left over share amount or item specifically prepared for new beneficiaries.

$result = $client->addBeneficiaries($ref, $beneficiaries);

$ref is the transaction reference code

$beneficiaries is the list of new beneficiaries data to be added

The $result will be an object which contain data as follow:

  1. status : success or failed

Sandbox

When using sandbox mode, the payment can be simulated by visiting Sandbox Payment Simulation Page.

Enter the payment reference number then click pay to simulate the transaction payment.

The default payment method will use Ratapay balance, so if the tested account did not have balance in their account, the payment will fail. Hence, open the payment instruction first by visiting payment_url defined in transaction creation result, then choose the preferred payment method before attempting to simulate the payment.

Callback

Ratapay sends a POST callback on certain event which contains these data:

To verify the data againts the hash, use hash_hmac function with sha256 algo and merchant secret as the hash key.

example:

$valid = hash_equals($_POST['hash'], hash_hmac('sha256', $_POST['data'], $merchant_key));

The data contains following information

*Action List

Testing

$ phpunit

Contributing

Please see CONTRIBUTING for details.

Credits

License

The MIT License (MIT). Please see License File for more information.