Create Request
The below API use for create Recurring order request by Http POST Method.
Then merchant have to redirect customer to payment page based on response CheckoutUrl.
| Environment | URL |
|---|---|
| Staging | https://stagingpayment.share-commerce.com/CreateCheckout/Recurring |
| Production | https://payment.share-commerce.com/CreateCheckout/Recurring |
Request (Json)
| Field Name | Data Type (Len) | M/O | Description |
|---|---|---|---|
| MerchantID | String (50) | M | Unique merchant's identification assigned to each merchant by Share Commerce. |
| Frequency | Integer | M | Recurring Occurrence. If FrequencyPeriod set as "MONTHLY" and FrequencyInterval set as 1: - Frequency set as 12, it will be charged for 12 months subsequently. *Value 0, it will be kept charging on customer until Merchant terminate the recurring or auto terminate due to maximum retry. |
| FrequencyPeriod | String (15) | M | Recurring Interval : - DAILY - WEEKLY - MONTHLY - YEARLY |
| FrequencyInterval | Integer | M | If FrequencyPeriod set as "MONTHLY" : - FrequencyInterval set as 1, it will be charged by Monthly. - or FrequencyInterval set as 2, it will be charged by Bi-Monthly / Every 2 Months. - or FrequencyInterval set as 3, it will be charged by Quarterly / Every 3 Months. |
| RetryDays | Integer | O | Reserved for future use. Currently must be submitted as 0 - any other value is rejected. |
| MaxContinuouslyFailedCycles | Integer | O | Reserved for future use. Currently must be submitted as 0 - any other value is rejected. |
| EndDate | String | O | Recurring plan end date, format yyyy-MM-dd. Leave blank for no fixed end date. *Required by some acquirer-mode recurring plans; when provided, must be on or after RecurringStartDate. |
| ChargeDayOfMonth | Integer (1-31) | O | Fixed day of month to charge. Only applies when FrequencyPeriod is "MONTHLY" - ignored for any other FrequencyPeriod. |
| AllowRecharge | Boolean | O | Whether a failed cycle may be automatically re-attempted ("recharged") within RechargeWindowDays. Default true. |
| RechargeWindowDays | Integer | O | Number of days after a cycle's due date a re-charge attempt is still allowed. Only relevant when AllowRecharge is true. Default 3. |
| MaxRechargePerCycle | Integer | O | Maximum number of re-charge attempts per failed cycle. Only relevant when AllowRecharge is true. Default 3. |
| SkipFailedCycle | Boolean | O | Whether to skip a cycle that ultimately fails (after any re-charge attempts) and continue on to the next scheduled cycle. Default true. |
| SuspendOnHardDecline | Boolean | O | Whether a hard decline from the acquirer suspends the whole recurring plan. Default true. |
| NotifyMerchantOnFailure | Boolean | O | Master switch for merchant failure notifications on a failed cycle. Default true. |
| AcqMaxChargeAmount | Decimal (18,2) | O | Acquirer-mode only: maximum amount allowed per individual charge. When set, cannot be lower than RecurringAmount. 0 / omitted means no acquirer-side cap is submitted. |
| AcqMaxTotalAmount | Decimal (18,2) | O | Acquirer-mode only: maximum total amount allowed across the whole plan. When set, cannot be lower than RecurringAmount x Frequency. 0 / omitted means no acquirer-side cap is submitted. |
| CurrencyCode | String (5) | M | Recurring currency code. |
| RecurringAmount | Decimal (18,2) | M | Recurring amount. |
| RecurringStartDate | String | M | Recurring 1st cycle payment date. Must be today date onwards with format yyyy-MM-dd. |
| MerchantOrderNo | String (50) | M | Unique identifier or order number generated by merchant, use it to track Recurring and subsequent cycle payment details. |
| MerchantOrderDesc | String (1000) | M | Merchant Order description |
| MerchantRef1 | String (100) | O | Merchant reference |
| MerchantRef2 | String (100) | O | Merchant reference |
| MerchantRef3 | String (100) | O | Merchant reference |
| CustName | String (150) | M | Customer name |
| CustEmail | String (150) | M | Customer email |
| CustPhoneCountryCode | String (5) | O | Customer phone number country code. Eg, Malaysia (60) |
| CustPhoneNo | String (50) | O | Customer phone number |
| CustAddress1 | String (100) | O | Customer address line 1 |
| CustAddress2 | String (100) | O | Customer address line 2 |
| CustAddressPostcode | String (15) | O | Customer address postcode |
| CustCountryCode | String (10) | O | Customer country code |
| CustAddressState | String (150) | O | Customer state |
| CustAddressCity | String (150) | O | Customer city |
| RedirectUrl | String (1000) | M | Merchant redirect URL to direct customer to merchant's confirmation or thank you page. |
| IsSendReceiptToMerchant | Boolean | O | Whether to email a receipt to the merchant after a cycle completes. Default false. |
| IsSendReceiptToCustomer | Boolean | O | Whether to email a receipt to the customer after a cycle completes. Default false. |
| Versioning | Integer | O | API Versioning. Kindly put value as 2 |
| HTTP Header | Data Type (Len) | M/O | Description |
|---|---|---|---|
| SCSign | M | Message sign (Refer to below SCSign Calculation section) |
*Note, field SCSign have to pass in HTTP Header.
Request Sample
{
"MerchantID": "ABCDE12345",
"Frequency": 12,
"FrequencyPeriod": "MONTHLY",
"FrequencyInterval": 1,
"RetryDays": 0,
"MaxContinuouslyFailedCycles": 0,
"EndDate": "",
"ChargeDayOfMonth": 12,
"AllowRecharge": true,
"RechargeWindowDays": 3,
"MaxRechargePerCycle": 3,
"SkipFailedCycle": true,
"SuspendOnHardDecline": true,
"NotifyMerchantOnFailure": true,
"AcqMaxChargeAmount": 0,
"AcqMaxTotalAmount": 0,
"CurrencyCode": "MYR",
"RecurringAmount": 15.00,
"RecurringStartDate": "2023-07-12",
"MerchantOrderNo": "RecurringPayment_001",
"MerchantOrderDesc": "Membership Services",
"MerchantRef1": "",
"MerchantRef2": "",
"MerchantRef3": "",
"CustName": "Neilsa",
"CustEmail": "[email protected]",
"CustPhoneCountryCode": "60",
"CustPhoneNo": "",
"CustAddress1": "",
"CustAddress2": "",
"CustAddressPostcode": "",
"CustCountryCode": "",
"CustAddressState": "",
"CustAddressCity": "",
"RedirectUrl": "https://httpbin.org/anything",
"IsSendReceiptToMerchant": false,
"IsSendReceiptToCustomer": false,
"Versioning": 2
}
Response (Json)
Merchant Server shall examine field RespCode to determine the actual processing response of the request.
*Note, this response is NOT signed - there is no SCSign on this call's response, in the body or in a header.
| Field Name | Data Type (Len) | M/O | Description |
|---|---|---|---|
| RespCode | String (50) | M | Payment response code. (Refer to Appendix 1 - Response code) |
| RespMessage | String (2000) | M | Result description of recurring payment transaction. |
| Result | Object | C | Only available for successful order / request creation. |
| Result.TxnRefNo | String (50) | M | Unique reference of a transaction, generated by system. |
| Result.CheckoutUrl | String | M | Payment checkout page url. |
| Result.RecurringGuid | String | M | Unique identifier of the created recurring mandate, generated by system. |
| Result.RecurringMode | String | M | Recurring processing mode assigned to this plan. |
Response Sample
{
"RespCode": "00",
"RespMessage": "",
"Result": {
"TxnRefNo": "ABCD1111",
"CheckoutUrl": "https://stagingpayment.share-commerce.com/Checkout/Recurring/34dbc85b-de3b-43e7-995c-50ecd16ad66a",
"RecurringGuid": "b1e8c2f0-9a3d-4e7b-8f21-5c6d7a8e9f10",
"RecurringMode": "GATEWAY"
}
}
SCSign Calculation
SCSign signature calculation, will sign with whole json string, and calculate with HMACSHA256 algorithm.
Secret Key : mSuE3Ttn5B8vJhe5ncMutMLV
Sign String (Example)
{"MerchantID":"ABCDE12345","Frequency":12,"FrequencyPeriod":"MONTHLY","FrequencyInterval":1,"RetryDays":0,"MaxContinuouslyFailedCycles":0,"EndDate":"","ChargeDayOfMonth":12,"AllowRecharge":true,"RechargeWindowDays":3,"MaxRechargePerCycle":3,"SkipFailedCycle":true,"SuspendOnHardDecline":true,"NotifyMerchantOnFailure":true,"AcqMaxChargeAmount":0,"AcqMaxTotalAmount":0,"CurrencyCode":"MYR","RecurringAmount":15.00,"RecurringStartDate":"2023-07-12","MerchantOrderNo":"RecurringPayment_001","MerchantOrderDesc":"Membership Services","MerchantRef1":"","MerchantRef2":"","MerchantRef3":"","CustName":"Neilsa","CustEmail":"[email protected]","CustPhoneCountryCode":"60","CustPhoneNo":"","CustAddress1":"","CustAddress2":"","CustAddressPostcode":"","CustCountryCode":"","CustAddressState":"","CustAddressCity":"","RedirectUrl":"https://httpbin.org/anything","IsSendReceiptToMerchant":false,"IsSendReceiptToCustomer":false,"Versioning":2}
SCSign (Calculated Value)
f5b893c4ce4c3ca7fdc14343889b1815231dec59579c24d41ae9b80736463537