Toyyibpay Better Documentation (Unofficial) (1.0.0)
Download OpenAPI specification:Download
Based on official Toyyibpay API Reference (https://toyyibpay.com/apireference/), I created this documentation because the official documentation are showing only PHP example.
Any API should use curl as example, because curl showing most basic way API calling. From the basic API documentation programmers can use it as reference to use with any language the prefer such as JavaScript (node.js), PHP, Phyton and others.
So, I hope with this documentation, it will make my job easier to refer and use Toyyibpay API. This is created for own used, but I believe this can help others too. So, I make it public.
...
[ WARNING ]
This documentation is not complete, I wrote API that I usually use only. Unless Toyyibpay (the company) willing to sponsor (in shape of cash), I might spend my times to complete this documentation.
...
When developing software, you will want to test your code is working or not. At this time, you do not want to really pay real money.
So, that is why Toyyibpay have an Sandbox Mode. Always use sandbox mode when you are on development.
How to use sandbox mode
- Create an account at
https://dev.toyyibpay.com. - Use
https://dev.toyyibpay.comurl for testing. You can create dummy bills and payments.
For online banking transaction tests, use banks:
SBI BANK A (for success transaction)
SBI BANK B (for fail transaction; insufficient fund)
SBI BANK C (for Pending Return / Callback from bank - 30 min)
...
Username : 1234
Password : 1234...
You can use admin dashboard at https://dev.toyyibpay.com, similar way with real Toyyibpay production at https://toyyibpay.com.
Your customer need a bill to make a payment. So, you have to create a bill, then send the bill detail to your customer. But, bill MUST belong to a Category which is a group of bills. So, if there is no Category yet, you need to create a Category then only after that you can create the bill.
Toyyibpay payment flow:
- Customer visits your site.
- Customer chooses to make payment.
- Your site (on the backend for better security) creates a Bill via API call.
- Toyyibpay API returns Bill's code.
- Your site redirects the customer to Bill's URL.
- Customer makes payment through Toyyibpay website. They can choose their payment option of choice.
- ToyyibPay sends a server-side update (Payment Completion) to your site on Bill's status on payment failure or success.
- Your site can check payment status via API call.
Most API Toyyibpay need userSecretKey as a key to identified who are making the request.
Your userSecretKey will look like this: j2d2v697-603c-4a2e-0yxz-ktyi448gp153
! WARNING Never share userSecretKey to other people you do not trust. NEVER make it publicly available. It means you SHOULD NOT use the userSecretKey on client side software.
How to get userSecretKey
Login ToyyibPay or sandbox ToyyibPay (dev.toyyibpay.com).
Find your userSecretKey at the bottom left of main page (dashboard).
Create bill
Bill serves as an invoice to your customer. In the example below, we will show you how to create a Bill. You need to pass the following parameters to generate category code.
Request Body schema: application/x-www-form-urlencoded
| userSecretKey required | string User secret key |
| categoryCode required | string Category code |
| billName required | string <= 30 characters Bill name. Only alphanumeric characters, space and underscore ( |
| billDescription required | string <= 100 characters Bill description. Only alphanumeric characters, space and underscore ( |
| billPriceSetting required | number Enum: 0 1 Bill price setting. For fixed amount bill, set it to 1 and insert bill amount. Fixed amount bill means as you set the price. For dynamic bill (user can insert the amount to pay), set it to 0. Dynamic bill means your customer decides how much they want to pay. |
| billAmount required | number Bill amount. The amount is in cent. For example, for RM 1 set it |
| billPayorInfo | number Enum: 0 1 If you want to create open bill without require payer information, set it to 0. If you need payer information, set it to 1 |
| billReturnUrl | string Nullable URL to redirect customer after payment complete. |
| billCallbackUrl | string URL to redirect customer after successful payment. |
| billExternalReferenceNo | string Your own system bill reference number. You can use this reference number to check the payment status for the bill. |
| billTo | string Customer name. |
| billEmail | string Customer email. |
| billPhone | string Customer phone number. |
| billPaymentChannel | number Enum: 0 1 2 Set payment method allow for the bill. |
| billSplitPayment | number Enum: 0 1 Set 1 if you want the payment to be splitted to other ToyyibPay users. |
Array of objects JSON for split payment. | |
| billDisplayMerchant | number Enum: 0 1 Display merchant info in your customer's email. Set |
| billContentEmail | string Additional messages by sending an extra email to your customer. |
| billChargeToCustomer | number Enum: 0 1 2 Leave blank to set charges for both FPX and Credit Card on bill owner. |
Responses
Request samples
- curl
- JavaScript (ExpressJS)
curl -d "userSecretKey=j2d2v697-603c-4a2e-0yxz-ktyi448gp153&categoryCode=2405114m&billName='Daging kambing perap'&billDescription='Daging kambing perap'&billPriceSetting=1000" -X POST https://dev.toyyibpay.com/index.php/api/createBill
Get bill transactions
Check bill payment status by submitting Bill Code and Bill Payment Status(Optional).
Request Body schema: application/x-www-form-urlencoded
| billCode required | string Bill code. |
| billpaymentStatus | string Bill payment status. |
Responses
Request samples
- curl
curl -d "userSecretKey=j2d2v697-603c-4a2e-0yxz-ktyi448gp153&billCode=28mfcu8s" -X POST https://dev.toyyibpay.com/index.php/api/getBillTransactions
When your created bill had billReturnUrl, your customer will redirect to that URL with query parameters as the following:
- status_id : Payment status. 1 = success, 2 = pending, 3 = fail.
- billcode : Your billcode / permanent link.
- order_id : Your external payment reference no, if specified
billExternalReferenceNowhen you create the bill.
Example:
<your-return-url>/?status_id=1&billcode=90uf2fe&order_id=TRF20200923-XX021When your created bill had billCallbackUrl, your customer will redirect to that URL with query parameters as the following:
- refno : Payment reference no
- status : Payment status. 1= success, 2=pending, 3=fail
- reason : Reason for the status received
- billcode : Your billcode / permanent link
- order_id : Your external payment reference no, if specified
- amount : Payment amount received
Example:
<your-return-url>/?refno=fawfw&status=1&billcode=90uf2fe&order_id=TRF20200923-XX021&reason=lorem-ipsum&amount=1150Create a Category
Create a Category. Category is a group of bills.
Request Body schema: application/x-www-form-urlencoded
| catname required | string Category name |
| catdescription required | string Category description |
| userSecretKey required | string User Secret Key. |
Responses
Request samples
- curl
curl -d "userSecretKey=j2d2v697-603c-4a2e-0yxz-ktyi448gp153&catname=Kubus%20Official&catdescription=Fund%20for%20Kubus%20Official" -X POST https://dev.toyyibpay.com/index.php/api/createCategory
Response samples
- 200
[- {
- "CategoryCode": "od708wve"
}
]Get category
Get category detail information
Request Body schema: application/x-www-form-urlencoded
| userSecretKey required | string User Secret Key. |
| categoryCode required | string Category code. |
Responses
Request samples
- curl
curl -d "userSecretKey=j2d2v697-603c-4a2e-0yxz-ktyi448gp153&categoryCode=2405114m" -X POST https://dev.toyyibpay.com/index.php/api/getCategoryDetails