Ratapay PHP Library

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

Property	type	Required	Length	Default	Note
note	String	Y	255 Char	Null	General note of the invoice
email	String	Y	64 Char	Null	Payer email address
invoice_id	String	Y	25 Char	Null	Merchant invoice ID
amount	Integer	Y	8 Bytes	Null	Payment amount
name	String	N	64 Char	Null	Payer name
paysystem	String	N	16 Char	Null	Payment System ID which will be used for this invoice
second_amount	Integer	N	8 Bytes	0	Total amount of each recurring payment
first_period	String	N	4 Char	Null	Period between the initial payment with the first recurring payment
second_period	String	N	4 Char	Null	Period between each recurring payment
rebill_times	Integer	N	4 Bytes	0	How many recurring payment will occur
refundable	Boolean	N	1 Byte	False	Is the invoice will be refundable
refund_threshold	String	N	4 Char	Null	How long will the invoice be refundable after successful payment
url_callback	String	N	255 Char	Null	Merchant URL where Ratapay will send notification data about the invoice activity
url_success	String	N	255 Char	Null	URL where user will be redirected after succesful payment
url_failed	String	N	255 Char	Null	URL where user will ber redirected if the payment failed or cancelled
expired_time	String	N	32 Char	Null	Time the invoice expired in iso 8601 format, e.g. 2022-01-01T10:00:00+07:00

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

Method	Parameter	Return	Note
addItem	Item Object	Boolean	Add Item to Invoice
addItems	Array	Boolean	Add Multiple Items at once to the Invoice, each item data must conform to Invoice data requirements
clearItem	None	Boolean	Clear Invoice items
addBeneficiary	Beneficiary Object	Boolean	Add Beneficiary to Invoice
addBeneficiaries	Array	Boolean	Add Multiple Benficiaries at once to the Invoice, each beneficiary data must conform to Beneficiary data requirements
clearBeneficiary	None	Boolean	Clear Invoice beneficiaries
getAmount	String	Integer	Get Invoice amount, use 'first' as parameter for amount and 'second' for second_amount
getBeneficiaries	None	Array of Beneficiary Object	Get all Invoice beneficiaries
getItems	None	Array of Item Object	Get all Invoice items
payload	None	Array of Mixed Data	Generate array formatted Invoice data that will be submitted

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

Property	Type	Required	Length	Default	Note
id	String	Y	32 Char	Null	ID of the item in merchant system
qty	Integer	Y	4 Bytes	1	Item quantity in the invoice
subtotal	Integer	Y	8 Bytes	Null	Subtotal amount of the item with all the qty
name	String	Y	128 Char	Null	Item Name
type	String	N	64 Char	Null	Item Type
category	String	N	64 Char	Null	Item Category
brand	String	N	64 Char	Null	Item Brand
refundable	Boolean	N	1 Byte	false	Is Item Refundable
refund_threshold	String	N	4 Char	Null	Item Refund Period

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

Property	Type	Required	Length	Default	Note
email	String	Y	64 Char	Null	Beneficary Email
name	String	Y	64 Char	Null	Beneficary Name
username	String	N	64 Char	Null	Beneficary Username in merchant system
share_amount	Integer	Y	8 Bytes	Null	Beneficary share on payment
rebill_share_amount	Integer	N	8 Bytes	Null	Beneficary share on recurring payment
share_item_id	Integer	Conditional	4 Bytes	Null	item_id related to this share, required if item is defined in invoice

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);

Property	Type	Required	Default	Note
reference	String	N	''	Transaction reference code
invoice_id	String	N	''	Merchant Invoice ID
creation_time	String	N	[]	range of transaction creation time in seconds [start_time, end_time] example [1622540704, 1623663904]
paid_time	Integer	N	[]	range of transaction paid time in seconds [start_time, end_time] example [1622540704, 1623663904]
offset	Integer	N	0	listing offset
limit	Integer	N	5	listing limit, maximum 30

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 = []);

Property	Type	Required	Default	Note
reference	String	Y	''	Transaction reference code
item_ids	Array	N	[]	List of specific invoice item id to be splitted

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 = []);

Property	Type	Required	Default	Note
reference	String	Y	''	Transaction reference code
period	String	Y	''	How long is the extension, format [1-9][D/M/Y], e.g. 7D
item_ids	Array	N	[]	List of specific invoice item id to extend its refund threshold

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

Property	Type	Required	Default	Note
reference	String	Y	''	Transaction reference code
params	Array	N	null	Specify refund rules

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:

property	type	note
data	String	A json encoded data of the callback
hash	String	Hash of the 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

Property	Type	Note
action	Integer	Refer to Action List below*
invoice_id	String	Invoice ID from merchant system
paysystem	String	Payment channel used to pay the transaction
amount	Integer	Amount of payment
unique_code	Integer	Unique code applied to payment
gateway_charge	Integer	Gateway charge applied to payment
merchant_id	Integer	Merchant ID
ref	String	Transaction reference number

*Action List

Action	Event
1	Payment Success
2	-
3	-
4	Recurring Payment Failed
5	Recurring Payment Success
6	Refund Success
7	Split Fund Success

Testing

$ phpunit

Contributing

Please see CONTRIBUTING for details.

Credits

• Ratapay
• All Contributors

License

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