Get Token Integration Update

A. What is senangPay Tokenization API?

Tokenization allows merchant to charge customer’s credit card without the need to enter the credit card details (name, card number, expiry and cvv). To get this feature in your dashboard, you can notify us by sending a ticket from the dashboard or guide page. This application shall be subjected to senangPay approval which we will review at our own discretion. Merchant must provide us the Terms of Contract between merchant and the other party user

 

B. How does it works?

Merchant’s customers will enter their credit card details one time only. During this one time process, senangPay will validate the card to make sure the card is valid by charging an amount of RM1 to the card. Not to worry that this amount will be voided later. Meaning that the transaction will never appeared on the customer’s credit card statement.

If senangPay failed to charge the card, meaning that the card is not valid. Once validated, the card’s info will be stored in senangPay’s server (PCI-DSS certified).

 

C. API List

1. Get token

We have developed a new secure way of generating token for our tokenization payment. In this new feature, card holder is required to pass the OTP (3D secure) check before able to get the payment token. Also, there are few extra layers been added to ensure no non authorised card being used for this tokenization payment feature.

The old (current) way of getting the payment token will be discontinued and no more access will be granted.

Get token (3D Get Token) -Will be replacing the former 2D token*

Get token (Will be deprecated on 31st December 2019)

ItemDetail
URL endpoint (POST)https://app.senangpay.my/apiv1/get_payment_token
 
1.1  Authorization Header (Basic Auth)
TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.
 
1.2 Request Parameter (all is mandatory)
Parameter NameParameter value/description
nameYour customer name. Maximum length is 100.
Eg. Abu Bin Ali
emailYour customer email.
Eg. ahmad@google.com
phoneYour customer phone number.
Eg. 0109876543
cc_numberYour customer credit card number.
cc_expYour customer credit card expiration date in MMYY format.
Eg. if the card expires on January 2017, you need to send 0117
cc_cvvYour customer credit card CVV number.
Eg. 123
 
1.3  Response Parameter
Parameter NameParameter value / description
statusYour transaction status. 1 if success. 0 if failed.
tokenIf card validation succeed, token will be generated. The token will be used for future payment on the card.
msgCard validation status message. If it was successful you will receive ‘Card successfully verified, the generated token can be used for future payment.’. If the validation failed, you will receive the error message in this parameter for further checking.

 

2. Pay credit card using token

ItemDetail
URL endpoint (POST)https://app.senangpay.my/apiv1/pay_cc
 
2.1 Authorization Header (Basic Auth)
TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.
 
2.2 Request Parameter (All Mandatory)
Parameter NameParameter value/description
nameYour customer name. Maximum length is 100.
Eg. Abu Bin Ali
emailYour customer email.
Eg. ahmad@google.com
detailYour order detail. Maximum length is 100. Eg. Order for product id #4
phoneYour customer phone number.
Eg. 0109876543
order idYour order id. Can be number or string. Other character is invalid. Eg. 123
amountYour order amount in integer format. Convert from decimals as necessary.
Eg. if the amount is RM 2.00, you need to send 200.
tokenGenerated token from Get Token API
hashA string hashed with your secret key (from your profile setting page) in HMAC hashing algorithm with SHA256 in the following format:
< your merchant id >< name >< email >< phone >< detail >< order_id >< amount >
*without the < > character
 
2.3 Response Parameter
Parameter NameParameter value / description
statusYour transaction status. 1 if successful. 0 if failed.
transaction_idYour transaction ID number.
order_idYour original order ID.
amount_paidAmount transacted from the credit card in integer format.
E.g., if the amount transacted is RM 2.00, it will output 200.
msgTransaction status message. If it was successful you will receive ‘Payment was successful’. If the transaction failed, you will receive the error message in this parameter for further checking.
hash

A string hashed with your secret key (from your profile setting page) in HMAC hashing algorithm with SHA256 in the following format:

< your merchant id >< status_id >< order_id >< transaction_id >< amount_paid >< msg >

*without the <  > character

2.4 Sample Response
{
   "status":1,
   "transaction_id":"14951544812820",
   "order_id":"1234",
   "amount_paid":1000,
   "msg":"Payment was successful",
   "hash":"99b6e99bb0aa663101b1e4f6f8d69c2efb41ef81a5a7aa030bf76a098a03d233"
}

 

3. Enable/disable credit card

ItemDetail
URL endpoint (POST)https://app.senangpay.my/apiv1/update_token_status
 
3.1 Authorization header (Basic Auth)
TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.
 
3.2 Request Parameter (All Mandatory)
Parameter NameParameter value / description
tokenGenerated token from Get Token API
 
3.3 Response Parameter
Parameter NameParameter value/description
msgMessage for the token is successfully disabled or enabled.
tokenGenerated token from Get Token API that has been disabled or enabled.

 

4. Validate payment token

ItemDetail
URL endpoint (POST)https://app.senangpay.my/apiv1/validate_token
 
4.1 Authorization header (Basic Auth)
TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.
 
4.2 Request Parameter (All Mandatory)
Parameter NameParameter value / description
tokenGenerated token from Get Token API
 
4.3 Response Parameter
Parameter NameParameter value/description
statusToken validation status. 1 if success. 0 if failed.
msgToken validation status message. If it was successful you will receive ‘Card has been successfully verified.’. If the validation failed, you will receive the error message in this parameter for further checking.
tokenGenerated token from Get Token API that has been disabled or enabled. The token will still be the same, nothing changed. We just return the same token here.