Straight2Bank Pay

Straight2Bank Pay is a payment gateway for powering our client's online collections at the point of payment checkout by buyer / consumer. It aggregates multiple payment methods via partnerships with leading players (PSP - Payment Service Provider) in the payments space across our footprint markets. The purpose of this document is to provide technical guidance for Client (Merchant) to integrate with Straight2Bank Pay.


  • Version: 8.0
  • Update: January, 2021

If you have any questions that are beyond the scope of this documentation, Please feel free to contact us.


Integration Options

Merchant can choose any one of the following Integration Options to present the Payment Method for their buyer on the checkout/payment page.

  1. Java Script Plugin Integration
  2. Re-direct integration
  3. Payment Link Integration
  4. API Integration

Java Script Plugin Integration

In this integration type, UI (User Interface) will be taken care of by Straight2Bank Pay Java Script. Merchant needs to make a call to s2bpay.js (resides in Straight2Bank Pay's server) from buyer's browser, s2bpay.js will get downloaded, takes care of rendering the button to bring up lightbox (overlay popup) with the enabled Payment Methods, facilitates buyer to choose preferred Payment Method till payment authorization, then shows the final status, passes control back to Merchant's page with the status at end of buyer's user journey. The following diagram depicts the minimum integration required for this type.

Click here for more details

JS


API Integration

In this integration type, Straight2Bank Pay is not involved in rendering UI on merchant page, but offers API services for Payment Method which is not required to re-direct the buyer to PSP page. Merchant to invoke API of Straight2Bank Pay as server-to-server call (collect) to perform on-line collection. For such Payment Method, buyer authorizes the payment in Mobile App, eg. UPI for India, PayNow for Singapore, etc. In case, PSP offers their service only via browser re-direction (eg. eNETS, BillDesk, etc), then Merchant needs to re-direct the user to Straight2Bank Pay URL (bcollect) with the payload as part of https FORM via buyer's browser, Straight2Bank Pay does another re-direction to PSP page which allows the buyer to authorize the payment on PSP page. The following diagram depicts the minimum integration required for this type.

API


Pre-requisites

  1. 'Straight2Bank Pay - Corporate Profile' form to be filled-up and submitted to Implementation Manager to setup a profile. Profile form contains all the configurations related to customize light box, list of PSPs to be enabled, any merchant data required to interface with each PSP, report scheduling and account to which the collected fund to be credited. Other mandatory data to be provided in the form:
    • Merchant needs to generate RSA-2048 key pair as given in section key pair generation and share public key to Bank. Merchant required to keep private key securely. Public key value needs to be populated in the form.
    • Merchant portal's URL (Domain name) to be filled in the form. If Straight2Bank Pay JavaScript (s2bpay.js) is requested from different URL, then the Straight2Bank Pay button will not be shown on the page.
  2. If Merchant wants to receive real-time notification, then Merchant needs to host a REST API. API end-point URL and SSL certificate (root, intermediary) to be submitted to Bank.
  3. Implementation Manger will submit the form internally and arrange to create a profile and assign a 'Corp ID' (Corporate Id). As part of Profile creation, Straight2Bank Pay will send a secret key to Merchant via email. Two emails will be sent containing: (Merchant required to keep Secret key securely)
    • PDF attachment (PDF is protected with a password)
    • Password to access the PDF

Once a profile has been successfully setup, then merchant can start the testing.


Java Script Plugin integration

Java Script Plugin integration requires Merchant Server to construct the payload and send to buyer's browser which in turn calls s2bpay.js from Straight2Bank Pay server. As a result, s2bpay.js will get downloaded and will be part of merchant page, shows the button to bring lightbox and takes care of remaining user journey. Once the buyer has authorized or rejected the payment, s2bpay.js will pass the control back to merchant page by calling either s2bPayClose() or s2bPayNotify().

JS

How it works

Buyer checks out

While loading merchant's payment page, s2bpay.js is called with the required parameters which will render Straight2Bank Pay Button if all validation is successful. Refer to s2bpay.js for more details.


Buyer clicks on Straight2Bank Pay button

While loading merchant's payment page, s2bpay.js is called with the required parameters which will render Straight2Bank Pay Button if all validation is successful. Refer to s2bpay.js for more details.

  1. The lightbox will have the details of the transaction such as amount and other details passed by merchant.
  2. Based on the country and currency provided, the buyer will be shown various payment methods that are enabled in the profile.
  3. If buyer closes the lightbox without choosing any payment method, then s2bpay.js will call a function, named as 's2bPayClose()' with an object containing the status and unique reference number. The Merchant can define the function 's2bPayClose()' on their webpage and taken appropriate action, if required. Refer s2bPayClose

Buyer selects a 'Payment Method' from the lightbox

Straight2Bank Pay connects with the respective PSPs via one of the following options:

  1. Redirects the buyer to PSP's page by passing the required details as part of browser redirection.
  2. Makes an API call and then redirects the buyer to PSP's page.
  3. Prompts the required details from the buyer and makes an API call with the PSP. No redirection for this option

Redirection to the PSP's page will happen in the child window. The parent window (Merchant page) will be in "Processing" state when the child window is open and no change is permitted on the parent window. Once the child window is closed, the parent window will show the appropriate status to the buyer.


Straight2Bank Pay provides the payment status to Merchant via the following options:

If buyer closes the lightbox after payment method selected, s2bpay.js will call a JavaScript function 's2bPayNotify()' with an object containing the status and unique reference number of the payment. The Merchant is expected to define the function 's2bPayNotify' on their webpage and take appropriate action based on the payment status. Refer s2bPayNotify

  1. Straight2Bank Pay notifies successful payment status to Merchant's server in real-time via reverse API. Refer Notifications
  2. Merchant can call Query API of Straight2Bank Pay to get the status of the transaction. Refer Query

Sequence Diagram

JS


s2bpay.js

Merchant needs to construct payload as described in this section at Merchant's server at the point of checkout and send this payload to Buyer's browser page, so that browser downloads s2bpay.js from Straight2Bank Pay server.

To construct payload, server needs to have Merchant's private key and shared Secret Key, hence the payload needs to be constructed only at Merchant's server, sensitive data (private and secret key) should not be sent to the browser.

URL

Production https://s2bpay.sc.com/s2bpay/resources/merchant/js/s2bpay.js
Test https://test-s2bpay.sc.com/s2bpaysit/resources/merchant/js/s2bpay.js

Sample Java Script snippet to be constructed in Merchant's server and sent to browser page.

							<!-- calling s2bpay.js from merchant's page-->
<script id="s2bpay-button-script" class="s2bpay-button"
   src="https://s2bpay.sc.com/s2bpay/resources/merchant/js/s2bpay.js"
   src="https://s2bpay.sc.com/s2bpay/resources/merchant/js/s2bpay.js"
   data-corpid="CN000002" data-encstr=" s+1BOZb+mVwx6l9IbYH2iYjzkc15sT4zAPhKP0Lu8L5HV272C6jJ6yzTwrYlGpbXvsMJAj/q/diA1MMdYpw6Q6jRNJLKA6XkxSEQGxrwt2OfQQY9B45PmbEncYb7o1zWBB1VIyXiao9b3kq2k7bJMDLjVxw1CbZ6R200gly0paVkzDGwQ6myfOSmnA2oVuyecyuZJrre8W+LeCRL9EavUmMgnCjou8XuhikxejP0nVuRiyYhza8CBeSBoyT0uTHUzTpdtNoU8+xN2bPqC3G+9JNn7UIon3HfYaFymkjfh8XqlQtNFexYGp7qfhX0Wa0RvOBe3H8+I1fMnuBx3+0x7TT2mRUDbU3teLtKr8lofOoDGGmWdlgzG/sbE5ROr+WH83QmklWzUuFiINLosbrZAS8f8vwXcl/EW05F0Dgn7hxhRKO5KoTi3fFue1K58DSubiin/ZO/sGxYa870EHLIGNPQ/V6mP9CW2gVkNJCJxYc2CUYV7s0AbwO0m9fAhKa+qj/Lg/V52LP/TDZz5E7037XBB9tHjdkXIwUjFopN8A8LBGEYPMqVU/xFdkrnu9YVGbeZ2uUzfqMhSWvynDiJhQ==">
</script>
						

The value in data-encstr is AES-256 CBC encrypted using the secret key and base64 encoded. Refer AES256 encryption/decryption The plain string looks like below: Refer to Request Parameters for description of each field of payload

							amt=1&corpid=CN000002&country=SG&currency=SGD&datetime=23072018150241&ref1=23072018145641&sign=pDW/SIqZstGY5xwE3zGPSUn/E3iXK15Nh9RXNlsMmis/4skng4BMniv+bNgVKLlsWB3EoeNctCKqZeONoIYMQL7zgpJZZoLqJ5AwzJ5Ug8CheTYt3lTizIx13CK3QHS4mIoT2J8h4KMkrSjaRLFQ9AprnTs6nQ3J5TTAx7HxZzySuTic5M0Z2NdEv5mwTf9GQybd6LNToXRkFPKzym5dkiC67VbWCMcmVYLBaPFgFToYlJONcjEx2UNnw92Im+1rimibSD9yAASM5JaoJl3dpPfOyhOkommCVFbLm9j4yjSLCwb7x6et/1wASBcUGa+k/vrVQqKk6O+QEMpjSB7H1Q==
						

Request Parameters

Seq Num Key Name M/O/C Type & Length Remarks
P1 corpid M X(8) Corp ID of Merchant
P2 amt M N(16,3) 13 integer digits and a precision of 2 decimals
P3 country M X(2) 2 character country code
P4 currency M X(3) 3 character currency code. Only domestic currency is supported.
P5 ref1 O X(100) Reference Number 1.
This value can be shown in lightbox with the configured label.Please refer 'Unique Reference' rule.
P6 ref2 O X(100) Reference Number 2.
This value can be shown in lightbox with the configured label.Please refer 'Unique Reference' rule.
P7 ref3 O X(100) Reference Number 3.
This value can be shown in lightbox with the configured label.Please refer 'Unique Reference' rule.
P8 ref4 O X(100) Reference Number 4.
This value can be shown in lightbox with the configured label.Please refer 'Unique Reference' rule.
P9 ref5 O X(100) Reference Number 5.
This value can be shown in lightbox with the configured label.Please refer 'Unique Reference' rule.
P10 datetime M N(14) Format: DDMMYYYYHH(24)MMSS (GMT+08:00)
The encrypted string is valid only for 5 minutes from the created time.
P11 pspid C X(8) PSP for which payment is being initiated. Eg: BDSSLNET, BDSSLCRD, BDSSLNET.
PSP IDs to be obtained from Implementation Manager.
Mandatory for bcollect URL & collect API and not applicable for s2bpay.js.
P12 rurl C X(1000) Return URL needs to be populated if Merchant portal does not want Straight2Bank Pay to open another Browser Window to re-direct the buyer to PSP page but instead wants to use the current browser window to be used to re-direct the buyer to PSP page. On this user journey, Straight2Bank Pay uses this URL to re-direct the buyer back to merchant page, as part of this re-direction, Straight2Bank Pay includes the payload to provide the status. Payload parameters will be same as described in section Notification Request

Merchant may need to populate rurl value for their mobile app integration with Straight2Bank Pay since opening multiple pages on a webview instance is not recommended.
Mandatory for bcollect URL, Optional for s2bpay.js, qrCollect and not applicable for collect API.
P13 sign M X(5000) Signature of entire key-value pair using Merchant's Private key.
Algorithm to be used : RS256
Refer to Generation of Digital Signature

Unique Reference Rule

Any one of the fields ref1 to ref5 can be chosen to be configured as 'Unique Reference' in Profile. This reference should be unique across for all transaction including refunds and should be maximum 16 characters long. Straight2Bank Pay will reject a transaction if any transaction contains same unique reference that was used earlier for a successful transaction. This duplicate check is performed based on last 365 days data. The assigned 'Unique Reference' field's value will be populated in 'corpref' field of messages that will be sent from Straight2Bank Pay to Merchant (eg. Notification, Query Response, etc). In case, 'Unique Reference' rule is not configured in profile, then 'corpref' will carry the value of Straight2Bank Pay generated transaction ID.


Customization of Straight2Bank Pay Button

To customize, Straight2Bank Pay button on merchant page which is rendered by s2bpay.js, Merchant can pass height, width, and label as part of parameter to s2bpay.js. The parameters are as follows:

Data Attributes Remarks
data-s2bpay-button-text Button Label to be displayed. Default Label is "Straight2Bank Pay"
data-s2bpay-button-height Height of button. Unit is in number of pixels.
data-s2bpay-button-width Width of button. If label requires more width than specified pixels, label length takes the priority. Unit is in number of pixels.

JS snippet with additional attributes:

							<script id="s2bpay-button-script" class="s2bpay-button"
   src="https://s2bpay.sc.com/s2bpay/resources/merchant/js/s2bpay.js"
   data-corpid="CN000002"data-encstr="vcFiGsEJafwoeVco//CgVCLMAE9/wJKQfz4oi4UllNdRwDFM2cf+1T/yHr11PXMxwzZKRXLPcKCZvN2dtjuFbasLrAOh7DK0ZIgPC221C99zKltQfUnCYsnPYdFh6iCgTsLIbGzLJ4Ep6NTJEpRjTbN/Y43Au88l2v0EZObve21EmuXDHn4rMt5Lv8DHGj46TA5DKWDWxTTRsUBqKITWHUlPB7Kf+636nZQF8u7hrjXzQa8QZLJgT59q51n2Gy9exm+iLN+AvrOn4ZhWWxIEQ4jtl1PDtJ9GVdgxQT4gWdDPVf93QxwzwoVJZcfX3V72X2mryP71EPNdiy4phR9qTA=="
   data-s2bpay-button-text="Proceed with Payment"data-s2bpay-button-height="50" data-s2bpay-button-width="50">
</script>
						

JS Functions

s2bPayButtonLoad ()

When Merchant Page calls s2bpay.js, the script gets downloaded into the browser, performs few validations and passes the payload to Straight2Bank Pay server. If server responds with successful status, then the Straight2Bank Pay button will be shown on the page. If server responds with any error, then Straight2Bank Pay button will not be shown. But Merchant Page is not being informed about the status of the button display. If Merchant Page needs to know about this event, then Merchant can implement JavaScript function with the name 's2bPayButtonLoad' to receive 'buttonLoadStatus' object. This event can be utilized to show the respective message to the buyer for both positive and negative scenario.

The 'buttonLoadStatus' object will have following attributes:

Seq Num Key Name M/O/C Type & Length Remarks
1 status M X(10) Possible values:
  • success
  • fail
2 statusmsg O X(200) Failure reason for why the button is not displayed.

Sample:

								{status: "success"}
{status: "fail", statusmsg: "INVALID DOMAIN"}
								

Sample Code for Developer reference - s2bPayButtonLoad ()

							function s2bPayButtonLoad (buttonLoadStatus) {
// buttonLoadStatus.status, buttonLoadStatus.statusmsg
         if (buttonLoadStatus.status === "fail") {
               // TODO- Merchants Business logic in case of fail if any
         } else {
               // TODO- Merchants Business logic in case of success if any
         } }
							

s2bPayButtonClick ()

If buyer clicks on Straight2Bank Pay button, then s2bpay.js brings up the lightbox. If Merchant page wants to receive this event to disable any part of the page or menu, then Merchant an implement JavaScript function with the name 's2bPayButtonClick', s2bpay.js does not pass any parameter for this function.

s2bPayClose ()

Once s2bpay.js has displayed Straight2Bank Pay button on Merchant Page, s2bpay.js brings up lightbox if buyer clicks on the button. There might be a situation that buyer can close the lightbox without proceeding with the payment by choosing the payment method shown on the lightbox. This event will be notified back to merchant page by this callback function, called as s2bPayClose.

Merchant can implement JavaScript function with the name 's2bPayClose' to receive 'paymentCloseStatus' object from s2bpay.js and decide what kind of messages or next step to be shown to the buyer.

s2bpay.js calls s2bPayClose function of merchant page only if buyer closes the lightbox without selecting any Payment Method, otherwise s2bpay.js will call the function s2bPayNotify function (please refer next section).

The 'paymentstatus' object will have following attributes:

Seq Num Key Name M/O/C Type & Length Remarks
1 status M X(10) Possible values:
  • closed
2 corpref M X(100) The unique ref field value will be populated here.

Sample:

								{status: "closed", corpref: "12345678"}
							

Sample Code for Developer reference - s2bPayButtonClose ()

								function s2bpayClose(paymentCloseStatus) {
// paymentCloseStatus.status, paymentCloseStatus.corpref
         if (paymentCloseStatus.status === "closed") {
               // TODO- Merchants Business logic in case of closed
         } else {
               // TODO- Merchants Business logic in case of failure
         } }
							

s2bPayNotify ()

The Merchant page which calls 's2bpay.js' must implement a JavaScript function with the name as 's2bPayNotify'.

This function will be called by 's2bpay.js' when event occurs to pass the control back to Merchant page. s2bpay.js passes an object with the name of 'paymentstatus' as parameter to 'S2bPayNotify' function, this object contains the following data.
Seq Num Key Name M/O/C Type & Length Remarks
1 status M X(10) Possible values:
  • success
  • fail
  • pending

Note: 'pending' status provided via s2bPayNotify may not be the final status. For certain PSP e.g. UPI, the user may close the lightbox first, which returns pending status, and then authorize the payment later in mobile device using UPI app. PSP which supports collection from Corporate Banking portal, 'pending' status will be sent once Maker has created the payment, 'success' status will be sent to Merchant server via API once checker has approved the payment in Corporate Banking portal.

2 scbTxnId M X(16) Straight2Bank Pay generated unique transaction ID for this transaction.
3 corpref M X(100) The unique ref field value will be populated here.
4 dateTime M X(8) Datetime stamp when the transaction is made. Format:DDMMYYYYHH(24)MMSS (GMT+08:00)
5 hash M X(200) HMAC Hash value of entire key-value pair string. Straight2Bank Pay uses HMACSHA256 algorithm by passing Secret key. Merchant needs to verify this Hash usingVerification of Hash Valueat Merchant Server, it should not be performed in Browser for security reason. If computed Hash value does not match with the hash value in the message, then Merchant Server needs to reject the message.
6 partnerTxnId O X(100) PSP assigned Transaction ID if available.

Sample for Pending status

								{corpref:"8000083522", dateTime:"02012018123535",
hash:"9e3ce1b5d5d0bb83dae10ca2480529ec3efcf4735e200213f6b09b80ab895749", partnerTxnId:undefined,
scbTxnId:"8000083522", status:"pending"}
							

Sample for Success status

								{corpref:"8000083524", dateTime:"02012018125517",
hash:"3b3e983ed1c8c9f9894a52b62bbfc86677d24915e51fe312ffac4070c8ef2f2c", partnerTxnId:"1",
scbTxnId:"8000083524", status:"success"}
							

Sample for Fail status

								{corpref:"8000083525", dateTime:"02012018125932",
hash:"a389501270772168a55fb877efc83fdf8de298235cf27214a45b2b6e2e527497", partnerTxnId:"0",
scbTxnId:"8000083525", status:"fail"}
							

Sample Code for Developer reference - s2bPayNotify

								function s2bPayNotify(paymentstatus) {
// paymentstatus.status, paymentstatus. scbTxnId, paymentstatus.corpref, paymentstatus. partnerTxnId, paymentstatus.hash, paymentstatus.dateTime
         if (paymentstatus.status === "success") {
               // TODO- Merchants Business logic in case of success
         } else {
               // TODO- Merchants Business logic in case of failure
         } }
							

Try it out

Input Fields
corpid
amt
country
currency
ref1
ref2
ref3
ref4
ref5
datetime
rurl
Button Generation
Button Text
Button Height
Button Width
Merchant Keys
AES Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
Request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/resources/merchant/js/s2bpay.js
  
S2BPay Button

JS Function Response
Status
SCB Transaction ID
Partner Transaction ID
Unique Reference
DateTime
Hash

Re-direct Integration

In this integration type, the payment method option needs to be on the merchant portal. Once payment method is selected, Merchant needs to re-direct the user to Straight2Bank Pay URL (bcollect) with the payload as part of https FORM via buyer's browser, Straight2Bank Pay shows payment page or does another re-direction to PSP page which allows the buyer to authorize the payment. The following diagram depicts the minimum integration required for this type.

redirect

bCollect

Merchant can re-direct the buyer to bcollect URL of Straight2Bank Pay with the payload as part of https FORM. Straight2Bank Pay does the following:

  1. Validates the request, records it and re-directs the buyer to PSP page based on PSP ID sent in the payload.
  2. Buyer will be authorizing or rejecting the payment in PSP page.
  3. PSP re-directs the buyer back to Straight2Bank Pay registered URL along with the payment status.
  4. Straight2Bank Pay records the status and re-directs the buyer back to Merchant's URL that was provided as part of bcollect. Straight2Bank Pay sends Notification message in HTTP FORM variable, notification message structure is described in section Notification Request
  5. bCollect supports Instant Payment QR / RTP (Request to Pay) payment methods (like PayNow QR for Singapore, FPS QR for Hong Kong, UPI QR & UPI RTP for India, Thai QR for Thailand, VNPAY QR for Vietnam, etc) where there is no PSP involved. Straight2Bank Pay page shows QR or prompt data for RTP and takes care to show the final status.

bCollect Request (Merchant Server to Straight2Bank Pay via user's browser)

Protocol

HTTPS POST (Browser re-direction)

Message Format

FORM

Communication Layer level security

TLSv1.2

Security Algorithm

Request: RS256 Signature , AES-256 CBC encryption

Response: HMAC-SHA256 hashing, AES-256 encryption, RSA2048 Encryption

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/bcollect

Prod: https://s2bpay.sc.com/s2bpay/bcollect

Event

Whenever Merchant needs to re-direct the user to PSP page to authorize.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 bcollect_req M X(2000)

Key-value payload needs to be constructed as described in section Request Parameters, then payload needs to be AES-256 CBC encrypted using shared secret key, encrypted string needs to be base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view the sample code to perform AES encryption.

Each key-value pair used to construct payload string for 'bcollect_req' tag is concatenated using & (ampersand) character.


bCollect Response (Straight2Bank Pay to Merchant Server via user's browser)

Straight2Bank Pay receives bCollect request, decrypts, validates the signature and stores the transaction if request is valid, then re-directs the buyer to PSP page to allow the buyer to authorize the payment. PSP redirects the buyer back to Straight2Bank Pay along with the status. Straight2Bank Pay server saves the status and then re-directs the buyer to Merchant URL that was provided in bcollect request message. As part of this re-direction back to Merchant URL, https FORM will have the following payload.

Message Specification

Message and Payload specification are same as Notification Request, will be sent as part of HTTPS FORM.

Exception Scenarios

Straight2Bank Pay gets any of the following error during the validation of bCollect request, then buyer will be shown with error.jsp of Straight2Bank Pay with the details of the error and will not be re-directed back to Merchant page since Straight2Bank Pay does not correct URL of Merchant.

Error Error Message shown in error.jsp
If corpid is invalid Invalid Corporate Id
If bcollect_req is empty or unable to decrypt Invalid Request
If sign does not match Invalid Request
If rurl is empty or invalid URL or URL is not registered in Profile Invalid Return URL

For remaining validation error, Straight2Bank Pay will re-direct the buyer to Merchant's URL (as mentioned in rurl tag) with the payload. Following error message is possible to send statusdesc field.

  • Invalid Amount
  • Currency code invalid
  • Country code invalid
  • Invalid Date time in Request
  • UniqueId invalid
  • PSPid invalid
  • Server Error Occurred. Please try again Later

Request and Response Samples

bCollect Request - Sample Message

Clear-text value for 'bcollect_req' tag:

amt=1&corpid=CN000002&country=BD&currency=BDT&datetime=18012019125809&ref1=18012019125809&rurl=https://test-s2bpay.sc.com/s2bpaysit/testredirect&sign=gvudGHnQd6MgS4jmNutZ0nU4jcQrJrQO4PAsY7FReGMooQ5bJe/xDZhy2jtRdbLTmRfgZP9MnFjffOLq61rg81zuL2yeH+ISRPCxVoidwo0VBQizKWxmUNWaV7ntqiUuGZfCrszp4LPcYvUV4AKxDqgyQxmvapGzF/KyC7XCUeM2SyAzzzOTHLYF0Bw8MebnPfFpuHrZz481RXzdVJ5Ca03RR9kgO7d8RIcXeU5z2rzyPbaviZ9d42NwLcNtChn5keO69bgQDx5eoSENffU/60z5+oMyczOdweEpU0OX06ns2lUtzVzAibCgs+ON8JPBjYvL8wtD6A2uRyS2frrgyw==

Sample FORM:

								<form id="s2bpay-bcollect-form" name = "s2bpay-bcollect-form" action="https://test-s2bpay.sc.com/s2bpaysit/bcollect" method="post">
<input name="corpid" type="hidden" value="CN000002"/>
<input name="bcollect_req" type="hidden"
value="K2cZTduF8sX/oOX68nKd8xalYj13N/uotrzRpZCyMugikBHGVVZwwV7IhfZWhk1sDBjpg=="/>
</form>
							

bCollect Response - Sample Message

Clear-text value for 'notifyreq' tag for SUCCESS status:

amt=1.00&ccy=BDT&corpid=CN000002&corpref=18012019134643&ctry=BD&date=18012019135039&optxnid=19011811512712XcIqZw6DbQvdO&ref1=18012019134643&status=SUCCESS&txnid=9000114697&txntype=NEW&hash=2CC3605474A8D5B4669FDAB5AB47F672F9BB8B979A61B66BAF52FDE39030EB04

Clear-text value for 'notifyreq' tag for REJECTED status:

amt=1&ccy=SGD&corpid=CN000002&corpref=18012019112152&ctry=SG&date=18012019132220&ref1=18012019112152&status=REJECTED&statusdesc=Invalid Date time in Request&txntype=NEW&hash=F0CEA40FF1ABEC5545BF9BDD0B6DE34DE87806C6E4B598D4155986CCC212598A

Sample HTTP Form:

								<form id="s2bpay-notify-form" method="post"  action="<merchant rurl>" >
<input type="hidden" name="corpid" value="CN000002" />
<input type="hidden" name="notifyreq" value="GVevAY3SkH0o17RA9gIX8zGb1q5EW1K/CQCg6pmfWM7ppyiIyIX1f/fGACAGtbdPtU4wrMHBi9MtfEvHS/BFC0SQFhQ9qVbi7pml8Dzi7Z03WADFWo3i/6EZi2WVgUTlcAx2etq65Q0CLMNQqIWl7bon6bTeIBWlLnluQR+Io5ve9uBWigtDoPPbjsm6tvbxPcBKZUAfLt6klEr3Njf3PXlZZRLlPFVyUvTFSRRrsWrmovfhiOSPHpZlKUugaBUSND8fvF7wCBupvIZpi6jHkGN5+K74lbcq3oJAn6nWHaSIZ+tX9x4DpP3Xi9P5oR/dDPbe0sQpqsisJ73mYMbSgA==" />
<input type="hidden" name="enc_key" value="UqIbevGgjNMHkWON9c2nd6gYys2QA84HeT2LFrLtvx1e157UONQ4ycePH8b+abxUmJrY5S64LNTX1PIrasH9hUrPzWjOC/ixnnNA/XS33arFJbD84YivPojj3y21U6LU6J0a5l5Cc8qzvCjUR1ZLSI8wZeCIEkfuxQ41XwPaQORBPGnG8am4cUahNB3MyELPxdSoHsPffODn5nRlJ4m24oy5dyGXwIPe9FKno7Ulmq5M5bgzaHdUiz3otzNFeiGWlKhpbt3fa1OyBV5aaqM4eQ+aEDf0BoPl7SjdeshlT1MrB4a2ApfwaE3YT16Er8R7jQX9Vjo+DYhUksaFRnSrEw==" />
</form>

Merchant will receive the values as URL encoded key=value pair
enc_key=GVevAY3SkH0o17RA9gIX8zGb1q5EW1K%2FCQCg6pmfWM7ppyiIyIX1f%2FfGACAGtbdPtU4wrMHBi9MtfEvHS%2FBFC0SQFhQ9qVbi7pml8Dzi7Z03WADFWo3i%2F6EZi2WVgUTlcAx2etq65Q0CLMNQqIWl7bon6bTeIBWlLnluQR%2BIo5ve9uBWigtDoPPbjsm6tvbxPcBKZUAfLt6klEr3Njf3PXlZZRLlPFVyUvTFSRRrsWrmovfhiOSPHpZlKUugaBUSND8fvF7wCBupvIZpi6jHkGN5%2BK74lbcq3oJAn6nWHaSIZ%2BtX9x4DpP3Xi9P5oR%2FdDPbe0sQpqsisJ73mYMbSgA%3D%3D&corpid=CN000002¬ifyreq=UqIbevGgjNMHkWON9c2nd6gYys2QA84HeT2LFrLtvx1e157UONQ4ycePH8b%2BabxUmJrY5S64LNTX1PIrasH9hUrPzWjOC%2FixnnNA%2FXS33arFJbD84YivPojj3y21U6LU6J0a5l5Cc8qzvCjUR1ZLSI8wZeCIEkfuxQ41XwPaQORBPGnG8am4cUahNB3MyELPxdSoHsPffODn5nRlJ4m24oy5dyGXwIPe9FKno7Ulmq5M5bgzaHdUiz3otzNFeiGWlKhpbt3fa1OyBV5aaqM4eQ%2BaEDf0BoPl7SjdeshlT1MrB4a2ApfwaE3YT16Er8R7jQX9Vjo%2BDYhUksaFRnSrEw%3D%3D

						

Try it out

Input Fields
corpid
amt
country
currency
ref1
ref2
ref3
ref4
ref5
datetime
rurl
pspid
Merchant Keys
AES Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
Request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/bcollect
  

bMandate

Merchant can re-direct the buyer to bMandate URL of Straight2Bank Pay with the payload as part of https FORM. Straight2Bank Pay does the following:

  1. Validates the request, records it and re-directs the buyer to PSP page based on PSP ID sent in the payload.
  2. Buyer will be able to chose the bank or redirect to psp page to create mandate.
  3. PSP re-directs the buyer back to Straight2Bank Pay registered URL along with the payment status.
  4. Straight2Bank Pay records the status and re-directs the buyer back to Merchant's URL that was provided as part of bmandate. Straight2Bank Pay sends Notification message in HTTP FORM variable, notification message structure is described in section Notification Request

bmandate Request (Merchant Server to Straight2Bank Pay via user's browser)

Protocol

HTTPS POST (Browser re-direction)

Message Format

FORM

Communication Layer level security

TLSv1.2

Security Algorithm

Request and Response: JWE String (RS-256 Sign, AES-256 GCM encryption)

SCB RSA Public Key: https://test-s2bpay.sc.com/s2bpaysit/devguide#idocs_pubkey

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/bmandate

Prod: https://s2bpay.sc.com/s2bpay/bmandate

Event

Whenever Merchant needs to re-direct the user to PSP page to authorize.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 bmandate_req M X(2000)

This tag can either contain JWE string / AES-256 encrypted string as BAU.

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The JWE String table lists the details used to construct the value for 'bmandate_req' tag.

Payload Attributes

The payload to be constructed as below Request Parameters

Request Parameters

Seq Num Key Name M/O/C Type & Length Remarks
P1 corpid M X(8) Corp ID of Merchant
P2 country M X(2) 2 character country code
P3 currency M X(3) 3 character currency code. Only domestic currency is supported.
P4 ref1 O X(100) Reference Number 1.
This value can be shown in lightbox with the configured label.Please refer 'Unique Reference' rule.
P5 ref2 O X(100) Reference Number 2.
This value can be shown in lightbox with the configured label.Please refer 'Unique Reference' rule.
P6 ref3 O X(100) Reference Number 3.
This value can be shown in lightbox with the configured label.Please refer 'Unique Reference' rule.
P7 ref4 O X(100) Reference Number 4.
This value can be shown in lightbox with the configured label.Please refer 'Unique Reference' rule.
P8 ref5 O X(100) Reference Number 5.
This value can be shown in lightbox with the configured label.Please refer 'Unique Reference' rule.
P9 datetime M N(14) Format: DDMMYYYYHH(24)MMSS (GMT+08:00)
The encrypted string is valid only for 5 minutes from the created time.
P10 pspid C X(8) PSP for which payment is being initiated. Eg: BDSSLNET, BDSSLCRD, BDSSLNET.
PSP IDs to be obtained from Implementation Manager.
Mandatory for bcollect URL & collect API and not applicable for s2bpay.js.
P11 rurl C X(1000) Return URL needs to be populated if Merchant portal does not want Straight2Bank Pay to open another Browser Window to re-direct the buyer to PSP page but instead wants to use the current browser window to be used to re-direct the buyer to PSP page. On this user journey, Straight2Bank Pay uses this URL to re-direct the buyer back to merchant page, as part of this re-direction, Straight2Bank Pay includes the payload to provide the status. Payload parameters will be same as described in section Notification Request

Merchant may need to populate rurl value for their mobile app integration with Straight2Bank Pay since opening multiple pages on a webview instance is not recommended.
Mandatory for bcollect URL, Optional for s2bpay.js, qrCollect and not applicable for collect API.

bmandate Response (Straight2Bank Pay to Merchant Server via user's browser)

Straight2Bank Payreceives bCollect request, decrypts, validates the signature and stores the transaction if request is valid, then banklist will be displayed/re-directs the buyer to PSP page to for creating mandate.

Message Specification

Message and Payload specification are same as Mandate Notification [JWE Format] Request, will be sent as part of HTTPS FORM.

Exception Scenarios

Straight2Bank Pay gets any of the following error during the validation of bmandate request, then buyer will be shown with error.jsp of Straight2Bank Pay with the details of the error and will not be re-directed back to Merchant page since Straight2Bank Pay does not correct URL of Merchant.

Error Error Message shown in error.jsp
If corpid is invalid Invalid Corporate Id
If bmandate_req is empty or unable to decrypt Invalid Request
If sign does not match Invalid Request
If rurl is empty or invalid URL or URL is not registered in Profile Invalid Return URL

For remaining validation error, Straight2Bank Pay will re-direct the buyer to Merchant's URL (as mentioned in rurl tag) with the payload. Following error message is possible to send statusdesc field.

  • Invalid Amount
  • Currency code invalid
  • Country code invalid
  • Invalid Date time in Request
  • UniqueId invalid
  • PSPid invalid
  • Server Error Occurred. Please try again Later

Request and Response Samples

bmandate Request - Sample Message

Clear-text value for 'bmandate_req' tag:

{ "corpid": "CN000002", "country": "SG", "currency": "SGD", "datetime": "18012019125809", "ref1": "18012019125809", "rurl": "https://test-s2bpay.sc.com/s2bpaysit/testredirect" }

Sample FORM:

								<form id="s2bpay-bmandate-form" name = "s2bpay-bmandate-form" action="https://test-s2bpay.sc.com/s2bpaysit/bmandate" method="post">
<input name="corpid" type="hidden" value="CN000002"/>
<input name="bmandate_req" type="hidden"
value="eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.Vzme9s5j7hafsG90Dy8Ya9Ex91Gim07m0lIYS8c7gC1BNj29jSos-ctCpUoEdBOVkn9q0lDxNVBM-roTT-RNEVCbQ-CL2fiwjlSvEBQ1SZ19ocOq-y70H4H6X9jI4sx6ilU3JSI7oHMhAzyr2JT1gc0EzKOR4qpQNuGWxPpb8Th3LpVfQ-97tazXdfyOaPbikgDUcJs2nc_jjWFPSRricE_tbzx0ML0HFdMdP2O7ZDH-GUAZfZJ1NbQ3f3tbLujIq3RUp5gzXxyI-7LQC9hHpSMMD99uV3kMugxB70llhNIFlaf4F47HSOSEZdJlgFd8vSuUawj5hmeNk37e0V8-dw.D_40VlttIrQs6OnQ.ZLwI3h7VFWhKOkrd6Nud3EUMgaN_Exk9nkEAReLsZoaLlxZ2twPLaw-wuyO-uDXFPmFlF0VKh073Ksmve8GYfm6pd_DMCPAYnNdk1uHb2fJWsxG_ljmrw69Z7dH3NhtotYVWT8kzN0FUsAdtKKlUk-wSk-wRdl852sq4HIyebX7K3fLD3c-eHg-zWsh2xnPhYxlkoptd97gVI7hrpq3pYip3n2D5hzjhJER3E5SPPgTxfbtq1tIxXQGxBRiqxPde3E2Pb6_5KruT3Ppp_p4GY5dTgIcEqqzIWzYIZrTOYIhY90qYIYmKPRHKvQ0LLsyvbDVqPjno9PQtAuZcVFbeCIN4dYh4l7i8y1qcVZ1S53zq27yohE47pLi33CGT2fVMzRMSupAEMQzVlYlVV4DH4fi2FL971EIDaYrOZ80ClfRiI3burCAV00qqX1jySfz9xphBjXfn7kolijFvKgIV0GKe_sRnqqq5fyo3kpa4G6l4vDoPWqP6qkbtUsfNc6qdjnLWF9qMulLBnQ366ZUilV4UW61TneLrmIcp-43aGboS0vY883exuWNlwV_s_IP5aFL6uxpIHSldlEB_sls4IboBKsEO1EerYk1FyLAHgzFo6pFitVlu.oJ7PSOMoqBVd7O1ceKC_Yw"/>
</form>
							

bmandate Response - Sample Message

Clear-text value for 'mndt_notifyreq' tag

{ "ackref": "8900064789", "date": "13092016181800", "status": "SUCCESS", "txnid": "6000064687"}

Sample HTTP Form:

								<form id="s2bpay-mndt-notify-form" method="post"  action="<merchant rurl>" >
<input type="hidden" name="corpid" value="CN000002" />
<input type="hidden" name="mndt_notifyreq" value="eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.Vzme9s5j7hafsG90Dy8Ya9Ex91Gim07m0lIYS8c7gC1BNj29jSos-ctCpUoEdBOVkn9q0lDxNVBM-roTT-RNEVCbQ-CL2fiwjlSvEBQ1SZ19ocOq-y70H4H6X9jI4sx6ilU3JSI7oHMhAzyr2JT1gc0EzKOR4qpQNuGWxPpb8Th3LpVfQ-97tazXdfyOaPbikgDUcJs2nc_jjWFPSRricE_tbzx0ML0HFdMdP2O7ZDH-GUAZfZJ1NbQ3f3tbLujIq3RUp5gzXxyI-7LQC9hHpSMMD99uV3kMugxB70llhNIFlaf4F47HSOSEZdJlgFd8vSuUawj5hmeNk37e0V8-dw.D_40VlttIrQs6OnQ.ZLwI3h7VFWhKOkrd6Nud3EUMgaN_Exk9nkEAReLsZoaLlxZ2twPLaw-wuyO-uDXFPmFlF0VKh073Ksmve8GYfm6pd_DMCPAYnNdk1uHb2fJWsxG_ljmrw69Z7dH3NhtotYVWT8kzN0FUsAdtKKlUk-wSk-wRdl852sq4HIyebX7K3fLD3c-eHg-zWsh2xnPhYxlkoptd97gVI7hrpq3pYip3n2D5hzjhJER3E5SPPgTxfbtq1tIxXQGxBRiqxPde3E2Pb6_5KruT3Ppp_p4GY5dTgIcEqqzIWzYIZrTOYIhY90qYIYmKPRHKvQ0LLsyvbDVqPjno9PQtAuZcVFbeCIN4dYh4l7i8y1qcVZ1S53zq27yohE47pLi33CGT2fVMzRMSupAEMQzVlYlVV4DH4fi2FL971EIDaYrOZ80ClfRiI3burCAV00qqX1jySfz9xphBjXfn7kolijFvKgIV0GKe_sRnqqq5fyo3kpa4G6l4vDoPWqP6qkbtUsfNc6qdjnLWF9qMulLBnQ366ZUilV4UW61TneLrmIcp-43aGboS0vY883exuWNlwV_s_IP5aFL6uxpIHSldlEB_sls4IboBKsEO1EerYk1FyLAHgzFo6pFitVlu.oJ7PSOMoqBVd7O1ceKC_Yw;" />
</form>

						

Try it out

Input Fields
corpid
amt
country
currency
ref1
ref2
ref3
ref4
ref5
datetime
rurl
pspid
Merchant Keys
AES Key
Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Encrypted Request Payload
Request
Request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/bmandate
  


billCollect - Straight2BankPay QR / Payment Link

Straight2Bank Pay QR (aka Payment link) option can be utilized by Merchant for the following scenarios:

  1. Merchant does not have any web portal and want to collect via Straight2Bank Pay payment gateway.
  2. Merchant does have a portal but does not want to integrate with Straight2Bank Pay in real-time, due to some reason (no IT team to work on this immediately).

Merchant will be provided with a Payment Link URL as part of on-boarding process, Merchant can send this URL or convert into QR image and send it to the Payer using any of the following channels:

  1. Printing QR in physical invoice / Bill
  2. Sending URL or clickable QR code in any electronic medium (like email, SMS, portal, social media, etc)
Fraud Awareness
Business email compromise (BEC) is a type of email cybercrime scam in which an attacker targets a business to defraud the company. BEC scams can be perpetrated in several ways. One method involves an employee's email account being hacked and the fraudster impersonates the firm by requesting for payments from unsuspecting customers. Fraudsters can replicate invoices or include payment links similar to one you would normally send to your customers, and the payments are then sent to fraudulent bank accounts owned by the fraudster. Protect your firm and customers by learning how BEC scams can be disrupted here.

Payer to scan the QR code using built-in camera app of any smart phone or using any QR reader app or using Google Lens or Bixby Vision options or click on the URL. The payment link will be accessed via browser and Straight2Bank Pay shows the payment page and allows the payer to complete the payment.

Straight2Bank Pay offers 4 features via Payment Link solution:

  1. Static Payment Link
  2. Semi-dynamic Payment Link
  3. Dynamic Payment Link
  4. Static Payment Link with Bill Presentment

If the URL is invoked via QR reader or invoked from Payment link, then the request will reach to Straight2Bank Pay server and does the following:

  1. Decrypts the URL query-string and validates the Corp ID. If it is valid, then it shows the input page to prompt the user to key-in certain data. What data to be prompted to the payer is configurable at Corp ID level.
    • For 'Dynamic Payment Link', step 1 (input page) is not applicable, it goes to payment page directly which does not required any data input by payer.
  2. On Clicking on 'Submit' button in input page, Straight2Bank Pay shows the payment page with the enabled payment methods at Corp ID level.
    • For 'Static Payment Link with Bill Presentment', Straight2Bank Pay makes an API call to Merchant server to fetch the Bill details (refer Bill Fetch API section for more details). After getting the bill amount and other relevant data, Straight2Bank Pay shows the payment page.
  3. Depends on the payment method selected by the payer, Straight2Bank Pay will either redirect the payer to PSP page or process the transaction by connecting to PSP via API or shows the QR code.
  4. Post the payment authorization, PSP re-directs the payer back to Straight2Bank Pay registered URL along with the payment status.
  5. Straight2Bank Pay records the status and notifies the merchant via Notification Request if it is opted by Merchant.

Static Payment Link

As part of on-boarding, implementation team will create Payment Link URL & corresponding QR code and pass it to Merchant. Merchant can be send this URL or QR code to multiple payers, Payer is expected to key-in the amount and reference number and make the payment.

Alternatively, Merchant can bookmark this URL in browser and use it for face-to-face collection to generate instant payment QR or initiate Request-To-Pay (RTP) by entering the amount and reference number, the page also shows the status in real-time.

Payment Link URL contains query string (encstr) with encrypted data of Corp ID, country, currency and expiry date & time of URL.

For this option, no development work is expected at Merchant end. Merchant can opt for periodic Transaction Report to get the transactions that have been successful paid.

Sample Payment Link URL:

Test:

https://test-s2bpay.sc.com/s2bpaysit/billcollect?encstr=MBk+Eld6E75xgsUQNMbLR1ZnIDMA+s4XBFJ1WNy3twhH3nh+y/gnrFVMliYroy4Y

Prod:

https://s2bpay.sc.com/s2bpay/billcollect?encstr=5+aiI7Zc/B4N4/00DBe/xXj7Yk2KyT5FzgsvlwqvoCznks11+Sh3/e7eNZCW5LFV8nd2rtpXbAAKVeTaoPg7hQa==


Try it out

Input Fields
corpid
ctry
curr
datetime
Submit request
Static Payment Link

Semi-dynamic Payment Link / Dynamic Payment Link

Static Payment Link generated by Bank can be easily converted into semi-dynamic or dynamic payment link by appending an attribute 'cencstr' (client generated encrypted string').

For dynamic payment link 'cencstr' will minimum contain Amount and reference number, so it will by-pass the input page and goes to payment page with all pre-populated data.

For semi-dynamic payment link 'cencstr' will contain either Amount and expecting input page to prompt the payer to enter reference number or 'cencstr' will contain only reference number and expecting to prompt the payer to enter amount. As part of Merchant Profile, it will be configurable which field to be made as editable. For this option, input page will be shown to collect the data before presenting the payment page.

This option requires Merchant to have an application to construct 'cencstr' and append to Bank provided static Payment Link URL to convert into semi-dynamic or dynamic payment link.

URL

Production

https://s2bpay.sc.com/s2bpay/billcollect

Test

https://test-s2bpay.sc.com/s2bpaysit/billcollect

URL Specification

Seq Num Tag name M/O/C Remarks
X1 encstr M This attribute will be provided by Bank one time as part of on-boarding. This attribute contains the following data:
  1. Corp ID
  2. Country
  3. Currency
  4. Expiry date & time of URL
X2 cencstr M

Key-value payload needs to be constructed as described in section Request Parameters, then payload needs to be AES-256 CBC encrypted using shared secret key, encrypted string needs to be base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view the sample code to perform AES encryption.

Request parameters of 'cencstr'

Seq Num Key M/O/C Type & Length Remarks
P1 corpid M X(8) Corp ID of Merchant
P2 amt O N(16,3) 13 integer digits and a precision of 2 decimals
P3 ref1 O X(100)

Reference Number 1.

This value can be shown in lightbox with the configured label. Please refer 'Unique Reference' rule.

P4 ref2 O X(100)

Reference Number 2.

This value can be shown in lightbox with the configured label. Please refer 'Unique Reference' rule.

P5 ref3 O X(100)

Reference Number 3.

This value can be shown in lightbox with the configured label. Please refer 'Unique Reference' rule.

P6 ref4 O X(100)

Reference Number 4.

This value can be shown in lightbox with the configured label. Please refer 'Unique Reference' rule.

P7 ref5 O X(100)

Reference Number 5.

This value can be shown in lightbox with the configured label. Please refer 'Unique Reference' rule.

P8 datetime O N(14)

Format: DDMMYYYYHH(24)MMSS (GMT+08:00)

Expiry date and time of the Payment Link. If payment link is invoked after this expiry date and time, then Straight2Bank Pay will reject the request and display the error message.

P9 rurl O On this user journey, Straight2Bank Pay uses this URL to re-direct the payer back to merchant page, if provided, as part of this re-direction, Straight2Bank Pay includes the payload to provide the status. Payload parameters will be same as described in section Notification Request
P10 pspid O X(8)

PSP for which payment is being initiated. Eg: BDSSLNET, BDSSLCRD, BDSSLNET, SGPAYNOW, etc

If present, only that payment option will be displayed in lightbox.

PSP IDs to be obtained from Implementation Manager.

P11 sign O X(500)

Signature of entire key-value pair using Merchant's Private key.

Algorithm to be used : RS256

Refer to Generation of Digital Signature

Sample URL:

Merchant will be provided with an URL during on-boarding, which contains ecnstr attribute as part of query-string.

https://test-s2bpay.sc.com/s2bpaysit/billcollect?encstr=MBk+Eld6E75xgsUQNMbLR5U1saSyiUG1T0r0SCHbkuQdLahIuZ5I0RMrO3Xif20k

Merchant can add transaction details with attribute cencstr towards end of the URL as follows:

https://test-s2bpay.sc.com/s2bpaysit/billcollect?encstr=MBk+Eld6E75xgsUQNMbLR5U1saSyiUG1T0r0SCHbkuQdLahIuZ5I0RMrO3Xif20k&cencstr=Mhh1vazm+ol303RlwTVps+OqIgeEakKusfmlPF3j3REWkh8PM+URz5RO+/VLjIw+

cencstr - Sample Message

Clear-text value for 'cencstr' tag:

amt=1&corpid=CN000002&datetime=18012021125809&ref1=18012019125809&rurl=https://test-s2bpay.sc.com/s2bpaysit/testredirect&sign=gvudGHnQd6MgS4jmNutZ0nU4jcQrJrQO4PAsY7FReGMooQ5bJe/xDZhy2jtRdbLTmRfgZP9MnFjffOLq61rg81zuL2yeH+ISRPCxVoidwo0VBQizKWxmUNWaV7ntqiUuGZfCrszp4LPcYvUV4AKxDqgyQxmvapGzF/KyC7XCUeM2SyAzzzOTHLYF0Bw8MebnPfFpuHrZz481RXzdVJ5Ca03RR9kgO7d8RIcXeU5z2rzyPbaviZ9d42NwLcNtChn5keO69bgQDx5eoSENffU/60z5+oMyczOdweEpU0OX06ns2lUtzVzAibCgs+ON8JPBjYvL8wtD6A2uRyS2frrgyw==


Try it out

Input Fields
corpid
amt
ctry
curr
ref1
ref2
ref3
ref4
ref5
rurl
datetime
Merchant Keys
AES Key
Public Key
Corporate RSA Private Key
Submit request
Payment Link

Static Payment Link with Bill Presentment

For this option, Payment Link will be provided by Implementation team as part of on-boarding. The user journey will start with Input page which prompts the payer to enter his/her identity with the Merchant. Upon click on 'Submit' button, Straight2Bank Pay server makes Bill Fetch API that expected to host in Merchant Server, based on the response from Merchant server, pre-populated payment page will be shown to the payer to complete the payment.

If Merchant is already having an API which provides the Bill Amount and other reference data, then Straight2Bank Pay needs to be enhanced to consume that API to make required user journey for Bill Presentment collection. If Merchant is going to develop to host an API, then Merchant can build the API with the specification that has been defined by Straight2Bank Pay as described in next section.


Bill Fetch API

Bill Fetch API is hosted in Merchant's server to provide the bill details to Straight2Bank Pay. This API will be called whenever Payer enters the reference in Payment Link Input page in order to fetch the bill details.

billFetch - Request (Straight2Bank Pay Server to Merchant's server)

Protocol

HTTPS POST (REST API)

Message Format

JSON

Communication Layer level security

TLSv1.2

Message layer level Security

Request: HMAC-SHA256 hashing, AES-256 encryption, RSA2048 Encryption

Response: RS256 Signature , AES-256 encryption

URL

Merchant's URL provided to Bank during onboarding

Event

Whenever Payer enters the reference to fetch the Bill in Straight2Bank Pay Bill Presentment screen.

Message Specification
Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 billfetch_req M X(2000)

Key-value payload will be constructed as described in next table, then payload is encrypted (algorithm: AES-256 CBC) using a random key, then encrypted string needs to be encoded (with base64) and populated here.

X3 enc_key M X(2000)

Random key used to encrypt 'billfetch_req' tag is encrypted using Merchant's public key using RSA-2048 and populated here.

The following table lists the key name used to construct the value for billfetch_req tag, each key-value pair is separated using & (ampersand) character

Request Parameters:
Seq Num Key Name M/O/C Type & Length Remarks
P1 corpid M X(8) Corp ID of Merchant
P2 amt O N(16,3) 13 integer digits and a precision of 2 decimals
P3 ref1 O X(100) Reference Number 1
P4 ref2 O X(100) Reference Number 2
P5 ref3 O X(100) Reference Number 3
P6 ref4 O X(100) Reference Number 4
P7 ref5 O X(100) Reference Number 5
P7 ccy M X(3) 3 character currency code
P8 ctry M X(2) 2 character country code
P8 hash M X(200)

HMAC Hash value of entire key-value pair string. Straight2Bank Pay uses HMACSHA256 algorithm using shared Secret key.

Merchant needs to verify this Hash using Verification of Hash Value at Merchant Server, If computed Hash value does not match with the hash value in the message, then Merchant Server needs to reject the message.

billFetch - Response (Straight2Bank Pay Server to Merchant's server)

Merchant is expected to generate synchronous response for each billFetch request that is requested to Merchant's billFecch API endpoint URL.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 billfetch_resp M X(2000)

Key-value payload needs to be constructed as descripted in next table, then payload needs to be AES-256 CBC encrypted using shared secret key, encrypted string needs to be base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view the sample code to perform AES encryption.

The following table lists the key name used to construct the value for 'billresp_resp' tag. Each key-value pair needs to be separated using & (ampersand) character.

Seq Num Key Name M/O/C Type & Length Remarks
P1 status M X(10) Possible Value:
  • SUCCESS
  • FAIL
P2 statusdesc O X(100)

Description of the Failure.

E.g. Hashing Error

P1 corpid C X(8)

Must present when status = SUCCESS

Corp ID of Merchant

P2 amt C N(16,3)

Must present when status = SUCCESS

13 integer digits and a precision of 2 decimals

P3 ref1 O X(100) Reference Number 1
P4 ref2 O X(100) Reference Number 2
P5 ref3 O X(100) Reference Number 3
P6 ref4 O X(100) Reference Number 4
P7 ref5 O X(100) Reference Number 5
P8 sign M X(200)

Signature of entire key-value pair using Merchant's Private key.

Algorithm to be used : RS256

Refer to Generation of Digital Signature

Request and Response Samples

BillFetch Request - Sample Message
Clear-text value for 'billfetch_req' tag:

ccy=KES&corpid=CUIIN001&ctry=KE&ref1=12345 &hash=A7F4CB71B49E86B30BE4ECA2561F998223FA1FAD83531A07DFF982979CEFB862

JSON message:

								{
"corpid":"CN000002",
"billfetch_req":"bIBnxTBhMIs/LwGS6F+p5uyfjjU/PN+pnme/a2qBaDIOmcjFCxtQoEjw7GwtZIkZxVt0tFO21UAXiZ8h+pKbDNgdKWXJ+eurVZvgt92+UPvMYmDPWH7mQV3rSdhjmp3Jh4E7qG/lEt9acTMbG09/kr1Yd62lmVdKLyOf+HG/BIfC4bySuEeUkW8yER74NE5P",
"enc_key":"UiNmnMDrQneF3kkK33IPdHJ68FLppOAt3MO/WLdOz6oMA8I2UqS2zuKzMoFFE56AMLz5r4ZnOYcuFBI0E+crf6VRWZ/bvWG8oSZWWAu7/z2YY84B6cvsIPsTa7FkqtMyZXGjY8EuslBxECrRgLq7TxVpDGAr3116Z3uX3SuYBx5MbpEWOq3LOWexZfqIdxvvFixnJBZ+Y9Cu8paqdmn9IjXbHkln9lChadfe0eZ7xFHjw5m6cEQtlSxh73pXSFOXnKu8kvWJKaEBzvpJAUOXEYqDXRaRQ9HKuF7wstCWIOMoc2FsyLc7xv2V58NtMQi1l6hjgBN5c1NpUgFaCQm0Tg=="
}
						
BillFetch Response - Sample Message
Clear-text value for 'billfetch_resp' tag:

amt=100.12&corpid=CUIIN001&ref1=12345& ref2=John Smith& ref3=AQUI7890UB& ref4=xx&status=SUCCESS&sign= i0aL9O7LkTOEfDnkagVHRgBXy4yNBvibud7NFmGk2/CUPa856SJaDbvKjlHz7rdo+cfxRc8vKNwl0ms+OSb95K5YVqLfe26xfYM5cVhOMKarDiaLRbJSAUJvtw7+zCJ7ZiEuLcnZP2yOzhy5Zlvb5FtSIFT5WT6HOiqB3SWX4DUb4xuJQFyoRhA9iWwj8A0mbWDE5l7I/OCHPhBvVYcIhWI3br5xQ6kNzwkwDl5glvPby5zKEDXNZqCxTQ/451kXEITRT3JTmixb+Dhnd77IxvFiyW/zN6mkebSNU9GMEuxwOONrL+ykCBHSEyodYwaFPRYzs/MB1gLKmTnWjQLubA==

JSON message:

								{
"corpid":"CN000002",
"billfetch_resp":"cUl5LoAVncDUFDseeU1Pzwx6C28uPUoOPdEex97ZwwV6hZodAeapdoKWpIiRXvfj2P3knVYt0hybDa/a/eC6NdL7LV1qs5R/f4tzygDHSHrXm4LoWKoreDqfGFlfk3y43Re+SmaFIlnjKkVgtKTbQ0atiTL22YdRka9bS+Y5Su1346deVuT8ixL4TKTZ1Ej/9zX+AatJ7GofTA5Zo7jMjWMPLcb2npC1JKjVlFx7J5rQewnLCIu3LYH8HFSzQOGzZmSY5QllN1p0EvciHs50tH9qa5kT854bU8qMhSXMK2ZTehTV+gTxB9YKqXFtLSHl35FZK0emEPLb/Z4W/Y4lwL+F3RllJfuqR91f4jCdzTWKYOuDbkrEyfPPIEICBiWzK2UitbBm+cJCuRJZMBXG8qE+og+nhM6Z9zYG/Q8J+c3g72jG9h0aY/iXDvOHTe0+1SA5W2SXhFQcUreYvkf8xkAsbhAsN0KPiAOd5BshJcv/lM5TtT8r/IlXZc1SjbutuoUsggxF9FKAAQb16EVcwBb8wltN/CEIkrN1wLKaaMtig26LhZ0+BZP+CZxUSwcqvsCBgPsqKXjNh+8dSB2CLuZ3EgSZsOs+XQbLOCRelfvENTyHEl72vIXfoTcaMYGTgXQWn59ogTD1R8mTMkUcFe+am5e123EojMilxMr8iqc="
}
						

API Integration

In this integration type, Straight2Bank Pay is not involved in rendering UI on merchant page, but offers API services for Payment Method which is not required to re-direct the buyer to PSP page. Merchant to invoke API of Straight2Bank Pay as server-to-server call (collect) to perform on-line collection. For such Payment Method, buyer authorizes the payment in Mobile App, eg. UPI for India, PayNow for Singapore, etc. The following diagram depicts the minimum integration required for this type.

api

Collect

Merchant Server can call this API to initiate a collect request for applicable PSPs. Straight2Bank Pay does the following based on the PSP ID:

  1. If PSP meant for QR code generation, then QR string will be generated and respond back synchronously.
  2. If PSP meant to send collect request further to PSP, then the request will be sent to PSP and acknowledgement message will be sent synchronously as response.

Collect Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

Message layer level Security

Request: RS256 Signature , AES-256 encryption

Response: HMAC-SHA256 hashing, AES-256 encryption, RSA2048 Encryption

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/collect

Prod: https://s2bpay.sc.com/s2bpay/collect

Event

Whenever Merchant needs to collect

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 collect_req M X(2000)

Key-value payload needs to be constructed as described in section Request Parameters of s2bpay.js, then payload needs to be AES-256 CBC encrypted using shared secret key, encrypted string needs to be base64 encoded and populated here.

Refer AES256 encryption/decryption section to view the sample code to perform AES encryption.

Each key-value pair used to construct payload string for 'collect_req' tag need to be concatenated using & (ampersand) character.


Collect Response (Straight2Bank Pay to Merchant Server)

Straight2Bank Pay receives Collect Request, decrypts, validates the signature and stores the transaction if request is valid, then generates synchronously response and sends back to Merchant.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 ack M X(10) Possible Value
  • PASS
  • FAIL
X2 ackdesc O X(100)

This tag will be populated only if ack is FAIL.

Possible error description:

  • Invalid Request
  • Error in processing Request
  • Invalid Date time in Request
  • Sign Error
  • Invalid Corporate Id
  • Invalid Amount
  • Currency code invalid
  • Unique id invalid
  • Invalid psp id
  • No Operator configured for this Country Currency
X3 corpid C X(8) Corp ID of Merchant.
X4 collect_resp C X(2000)

Key-value payload will be constructed as descripted in section Notification Request, then payload is encrypted (algorithm: AES-256 CBC) using a random key, encrypted string is base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view sample code to perform AES decryption.

X5 enc_key C X(2000)

Random key used to encrypt'collect_resp' tag is encrypted using Merchant's public key (algorithm: RSA-2048) and populated here.

Refer to RSA 2048 encryption/decryption section to view sample code to perform RSA decryption.

Each key-value pair used to construct payload string for 'collect_resp' tag is concatenated using & (ampersand) character.


Request and Response Samples

Collect Request - Sample Message

Clear-text value for 'collect_req' tag:

amt=10&corpid=CUIMOM01&country=SG&currency=SGD&datetime=18092018122600&pspid=SGPAYNOW&ref1=234252343&ref2=6545256&sign=b+0fpnA/8qI2wqsPUaLTv+fxHv49rgk4xf7ieflB6J8H8MFzQI8VjAP1Efw2r8BRBZXK7ZwE+Pnrf286y5fP3vtTEgZJIZv8iGs0ySlodUruqe0xJNElFLtbXJjZt13CG3B3wPTucXBl+PO24WyaA1DkaFjZzsjiSC2V6VwoW1zMJ9ecSu+3Kqh8UBc2HyyH3M6CwL0NzxjQS+o077Yharayh6sqTd3ELt1q71dKSv7TNeRpzhUtW+8+BVYB4LMjE7hF1iKymsZKdQsEiDpY+LrJ2LXJ1PboiQu1wvKin0fFpRnRX8v25t5XKUZC8yvBPKIRtty8/golsl8tpodxbw==

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CUIMOM01</corpid>
<collect_req>wZxXJAPejDGUXEgmMyKoteLkgoPmSGbBz4UlHQongLpFyso2MCP6OidMkVpOdQdH97TTE7JAsqOsSLs2mu9CLe/d516meeNospOwrQUajbbgcwOXCkotRw64BfO3PQZ5EnAj3idxdvap7eZLLxRL0fn6yCTAy66D/kaj1tFzJPK1K7Kt3DBGlSy2AMoJggpV23c9FO05UylyCDBSHbbXlk6OKKj5VGt6QVHmezzuycdzXoBM/lqzEN4qAo0kvpBbdUT3i9dZYmDLKHC3sVgpjVJ4S3nIKqMopwfsbm+maPMh2k57aXJG3ZqpZB43OIbVJIijbPXKenHGETQJDsJROHsUwqlAc1f+Zs1yAD8NeV40SN585XqWgClCI4WOIRMvMSFrm8cRpbs7dGhCgOPkyLrHZyHxjQcI3XXZgMU3bBxJkKdk5vOkw76go1Osuy8fA95JlbTZ4YlpEPc9J7cFfsuzXj6v/fjy/9jajinhaX3mRYevYVnqssK8EoF1zcbXzK1T/MFjCyOqRHMeAASKFq+peTMqehZJom4VpFbO0YsplefQLnrxm9vGeGrXoEZkEHmsQ2qgXFmbLU3Fq/y0XOY4uldYnqReaTMCE5LFH14=</collect_req>
</xml>
							

Collect Response - Sample Message

Clear-text value for 'collect_resp' tag for PENDING status:

ack=PASS&amt=10.00&ccy=SGD&corpid=CN000002&ctry=SG&datetime=18092018122611&qrstr=MDAwMjAxMjYzNjAwMDlTRy5QQVlOT1cwMTAxMjAyMDkwMTIyMTkwMEIwMzAxMDUyMDQzMDM3NTMwMzcwMjU0MDUxMC4wMDU4MDJTRzU5MTJQYXlOb3cgVUFUMDI2MDA5U2luZ2Fwb3JlNjIxMTAxMDc2NTQ1MjU2NjMwNEU3Q0M=&ref1=234252343&ref2=6545256&status=PENDING&txnid=8000000942&txntype=NEW&hash=B9A3798F251AE07889420459D5758C44A4165C379BE3422023B53E04E67404D2

Clear-text value for 'collect_resp' tag for ERROR status:

ack=PASS&amt=1.00&ccy=INR&corpid=CN000002&corpref=0609201118103825&ctry=IN&datetime=06092018133755&ref1=0609201118103825&status=ERROR&statusdesc=Invalid VPA&txnid=8000110845&txntype=NEW&hash=BECDD88F0EE19C61AD7B6839F3BF0CDBCFB9E5B590900AD162DD016EFE005AAF

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<ack>PASS</ack>
<corpid>CN000002</corpid>
<collect_resp>HpBodmPUtt6bBhTK2KAkl01jO6X11Uj6kScr6jBEdNgtoCGsLUPvfT6bl+/L06an/iw0SwduwN0J2MaHYfrfK1n7WNexohDD5Sc9iw4ZEuZWR1krmUmQwFXNgwjmOCFeZzVVW9/+Y1S7Wx+xTxxR7rRSYpUq0/qNxdHEQwhmw0d8kOsEtOeFgK+IibY/9OQZ+BiMPi9DOOChplZFpWKE2ELrNZd4VRYI0GAKseFa0f9uphZ7JfRmGNF7elTWXScyGaiBHsGFWxmzcqvb5aSKPXvGnPAF3wzYT10huM+plPx2/I2yAshGvsXtR2W8VKVeufmPSEJynGLTAUUXmFu9n7FqtbGi4hXYF/39I9W3AzlvsbBQqhHM6Ed2hNBMNnq2</collect_resp>
<enc_key>W5M1G6BDJGlTEgFOcIrdsb3GN/WHjf4A8v5vewXnVwpFJQzfDnGiPVFwIqS3H3bQMrUXvERmWSgaT2vBdU+btvwPQtssFqiiT3c/IGBeLtgEJ9YXmBlf/kacF6MG5tN6ghpg4BKsFT7jB5Cdnrmi+RchtMZxqBO4v0nXxOkHiUif+ooWC8O0HLaEPIluTxCdo9AhJaFj60XW+2YKQnWcAwKSiEf1aWL3P+bjycgS/TUZQbnf/1m1XPl8P9GXm4Kovu+xiLlFLnhS4LZ8W9hisVv1mM6hwV5Kr0rlAuo0Fa8oUbUI26k/rA+8KmymuGFeJLgiFRb3G+CpS5jiqnMGtA==</enc_key>
</xml>
						
For FAIL acknowledgment
								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<ack>FAIL</ack>
<ackdesc>Sign Error</ackdesc>
</xml>
							

Try it out

Input Fields
corpid
amt
country
currency
ref1
ref2
ref3
ref4
ref5
pspid
datetime
Merchant Keys
AES Key
Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
XML request
JSON request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/collect
Response
Decrypted response

eMandate

Merchant Server can call this API to initiate a collect request for applicable PSPs. Straight2Bank Pay does the following based on the PSP ID:

  1. Mandate registration-S2B Pay Hosted API for Corporate Client to register mandate.
  2. This API will be Supported by the data level Security model as JWT (JWE/JWS) .

eMandate Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

Message layer level Security

Request and Response: JWE String (RS-256 Sign, AES-256 GCM encryption)

SCB RSA Public Key: https://test-s2bpay.sc.com/s2bpaysit/devguide#idocs_pubkey

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/eMandate

Prod: https://s2bpay.sc.com/s2bpay/emandate

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
E1 corpid M X(8) Corp ID of Merchant
E2 emandate_req M X(4000) This tag can either contain JWE string / AES-256 encrypted string as BAU.
JWE format string which contains this following parts separated by .(dot)
JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table - JWS String

The following table lists the key names used to construct the value for 'emandate_req' tag.

Payload Attributes

Seq Num Key Name M/O/C Type & Length Remarks
P1 corpid M X(8) Corp ID of Merchant
P2 amt C N(16,3) 13 integer digits and a precision of 2 decimals. To be populated in MAXAMOUNT of mandate Table. Mandatory for action C.
P2 country M X(2) 2 character country code
P3 currency M X(3) 3 character currency code. Only domestic currency is supported
P4 actn O X(1) possible action:

C - create default value (if not present, C to be considered)

A - amend

D - delete.

A and D to be considered only the corresponding MANDATE status is SUCCESS, for other status, sync response to be sent with FAILED with the error message 'requested action is not allowed'. For A, if Mandate record is in SUCCESS STATUS and D action is initiated earlier and it is in PENDING status, then A action to be rejected, error message 'Amendment is not allowed for the mandate that is being Deleted'. For D, if Mandate record is in SUCCESS STATUS and A action is initiated earlier and it is in PENDING status, then D action to be rejected, error message 'Deletion is not allowed for the mandate that is being amended'. For A, the value to be amended (amount, amount type and end date) to checked against existing MANDATE record, if all are same, then A to be rejected with the error message 'New value of amendment is same with the existing mandate data'.

P5 ref1 O X(100) Reference Number 1 - To pass client reference. It should be unique default at corp/PSP Level INUPIDDI BILLREFNO [REF1]. In case, this parameter is not configured, then map same value of ID (s2bpay assigned unique value) to BILLREF column of mandate table. For action A and D, this field should have the value of parent's BILLREFNO
P6 ref2 O X(100) Reference Number 2 - To pass payerId (ID assigned by client for each payer) default at PSP Level INUPIDDI CORP_PAYERID [REF2]
P7 ref3 O X(100) Reference Number 3 - To pass PayerVPA INUPIDDI PAYER_VPA [REF3]. In case, this parameter is not configured or derived value is null, s2bpay to call UPI SWITCH API to generate 'AutoPay QR'
P8 ref4 O X(100) Reference Number 4
P9 ref5 O X(100) Reference Number 5
P10 ref6 O X(100) Reference Number 6
P11 ref7 O X(100) Reference Number 7
P12 ref8 O X(100) Reference Number 8
P13 ref9 O X(100) Reference Number 9
P14 ref10 O X(100) Reference Number 10
P15 datetime M N(14) Format: DDMMYYYYHH(24)MMSS (GMT+08:00)
P16 pspid M X(8) PSP for which mandate is being initiated. For UPI mandate, default PSPID is INUPIDDI
P18 rurl O X(100) Mandatory for lmandate & bmandate (phase2). Optional for emandate API

eMandate Response (Straight2Bank Pay to Merchant Server)

Straight2Bank Pay receives eMandate Request, decrypts, validates the signature and stores the transaction if request is valid, then generates synchronously response and sends back to Merchant.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
R1 ack M X(10) Possible Value : PASS / FAIL. Applicable only for sync response of eMandate and mandate query.
R2 ackdesc O X(100) This tag will be populated only if ack is FAIL. Applicable only for sync response of eMandate and mandate query.
R3 corpid C X(8) Corp ID of Merchant. Present only when ack=PASS for sync response of eMandate and mandate query. Notification request message CorpId will be populated.
R4 emandate_resp C X(2000)

This tag can either contain JWE string / AES-256 encrypted string as BAU.

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in JWS String Table

Payload Attributes


Seq Num Key Name M/O/C Type & Length Remarks
P1 status M X(10) possible values:
eMandate sync Response: FAILED, PENDING
mandate query response & Notification Request Message: PEND NG, SUCCESS (only for this DDI can be initiated by client), FAIL, CANCELLED, AUTHORIZED
P2 statusdesc O X(100) Remarks on status if available.
P3 txntype M X(20) Possible value: MANDATE, AMEND_MANDATE, CANCEL_MANDATE
P4 corpid M X(8) Corp ID of Merchant
P5 mndtid M N(14) Straight2Bank Pay generated unique Mandate ID
P6 payerid M X(50) Merchant assigned payer id as part of ref field.
P7 billref M X(50) Corporate reference for mandate
P8 txnref M X(50) TXNREF from mandate table
P9 ref1 O X(100) Reference Number 1. payerId in any one of Ref
P10 ref2 O X(100) Reference Number 2. PayerVPA in any one of Ref
P11 ref3 O X(100) Reference Number 3.
P12 ref4 O X(100) Reference Number 4.
P13 ref5 O X(100) Reference Number 5.
P14 ref6 O X(100) Reference Number 6.
P15 ref7 O X(100) Reference Number 7.
P16 ref8 O X(100) Reference Number 8.
P17 ref9 O X(100) Reference Number 9.
P18 ref10 O X(100) Reference Number 10.
P19 date M N(14) Current date time in HKT in DDMMYYYYHHMISS format (GMT+8)
P20 pspid M X(8) PSP for which mandate is being initiated
P21 ctry M X(2) 2 character country code
P22 ccy M X(3) 3 character currency code. Only domestic currency is supported
P23 strtdt O X(8) FROMDATE from mandate table
P24 enddt O X(8) TODATE from mandate table
P25 payeraccnum M X(35) Payer Account Number from Mandate Table
P26 payerbankcode M X(11) Payer Bankcode from mandate table
P27 payername M X(100) Payer Name from mandate table
P28 sgmnt O X(20) SEGMENT value from mandate table
P29 payeraccnumtkn O X(250) PAYER_ACC_TK from mandate table
P30 payeridenttype O X(50) PAYER_IDENT_TYPE from mandate table
P31 payerident O X(250) PAYER_IDNET from mandate table
P32 payeridenttkn O X(250) PAYER_IDNET_TK from mandate table
P33 issurctry O X(2) INSTR_ISSUER_CTRY from mandate table
P34 issurbin O X(100) INSTR_BIN from mandate table
P35 isdefault O X(1) ISDEFAULT from mandate table
P36 psptkn O X(4000) PSP_TK from mandate table
P37 maxamt O N(18,3) MAXAMOUNT from mandate table
P38 schedulefreq O X(50) SCHEDULE_FREQ from mandate table
P39 corpident M X(99) CORP_IDENT from mandate table
P40 amttype O X(50) AMT_TYPE from mandate table
P41 schedulerelation O X(50) SCHEDULE_RELATION from mandate table
P42 scheduleday O X(50) SCHEDULE_DAY from mandate table
P43 schemetxnref O X(100) SCHME_TXNREF from mandate table
P44 qrstr O X(4000) QR string will be sent, in case of mandate request is for Autopay QR
P45 corpacc O X(35) Corporate Account number.

Request and Response Samples

eMandate Request - Sample Message

Clear-text value for 'emandate_req' tag:

{ "corpid": "CUIMOM01", "amt": "10", "country": "SG", "currency": "SGD", "actn": "C", "ref1": "234252343", "ref2": "6545256", "ref3": "payer_vpa", "ref4": "232", "ref5": "", "ref6": "", "ref7": "", "ref8": "", "ref9": "", "ref10": "", "datetime": "18092018122600", "pspid": "SGPAYNOW", "rurl": "https://example.com/return" }

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CUIMOM01</corpid>
<emandate_req>eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.RyAD2NS_disLVDhk-Ja-2JoMu6SdOMi_E8sIowXRdGP35kOakvTsE8aDcoW3beUfB9UavtXCsyv2vD61J1dDXNP02Qtwoa-JkhXdghLf0TpUgxewayizhJxRrDNcmgTDVw9WL761RDb2RqPuvnkC_iYF4znD9SUZp-DgzL9Ye1CqW9rM9IzhwDS56B4b20e8so9pck0hpMuKF5hE0-lDdsID7UhTTBCeJUE-Uw4feBRAhUGyeUsbWv8b0NX2HxWBu9cVnhirNT4j2yp-tFOfhni8z4C0Z1iHS7Eyo_n8D9xp3JqknaSqRYO3JPtTCRxNVPDQ4jcimm4eRmCzbfdN_g.n_q7WLrjX4pbDUyL.ZifqpUuCKk7wK43Ts453dT0Wcg2H39CYybPTbSUR3IC1zwqc2BZ4Kkf28Tg_zosptBsWvnxIzavix5TmYTk4BXl7tqHXmquTQ7j9f2EQLA1fdR9OJGUgOF0BUs1NKUsR0TGO_4x80f4jpsABdEZZVZHfSUdY2WnZE1zn_3Rtb1xbVVumDRuD3tp_zq8udOWJGv5XZBxyHImK9L3DazwQQcpZjm8bEII9HPuB9s9QRV82OruCKxT7SYF7Msq4DvMpkJdQG4JA_Hqkwx7TclPqBsINTgJT3ONgC5Viubx_4jjZCDjYIZqu0sO9XW3kkTS2Ef16Uw1EUBOIzvy0NRsfvUmRmnh6cMiVC5gxEkJAHAojdas6ajEq0QtoL5KIFh_0Coznc7ykPLpHAC1lCGxeRd7mccdu1yIUQ6nO3Nc-GrXYJMsGhWbHGzXvIpfAi0DbYBM8X0bdPfmKwExoSGa_f_j6KFMUOeOcA33N70qpsUlLPtHRl0BigH0XHQ2SDUoZOVMRNEuonldeIEM9JsBZLLS4kF-l-0VOxaApBVHjZP_c8OAl0_hwbqL1BNRFJZOru80C6cJ26GnZqJO3Rp_4sir_SqeYX2OD1APQgsNmO0Vtowz8LBLO.d4Lr8wKRJEMkgYgIqTWo3Q</emandate_req>
</xml>
							

eMandate Response - Sample Message

Clear-text value for response status:

{ "ack": "PASS", "ackdesc": "Description if FAIL", "corpid": "CN000002", "emandate_resp": { "status": "PENDING", "statusdesc": "Remarks on status", "txntype": "MANDATE", "corpid": "CN000002", "mndtid": "12345678901234", "payerid": "payer_id_value", "billref": "corporate_reference", "txnref": "txn_reference", "ref1": "reference_1", "ref2": "reference_2", "ref3": "reference_3", "ref4": "reference_4", "ref5": "reference_5", "ref6": "reference_6", "ref7": "reference_7", "ref8": "reference_8", "ref9": "reference_9", "ref10": "reference_10", "date": "18092018122600", "pspid": "SGPAYNOW", "ctry": "SG", "ccy": "SGD", "strtdt": "start_date", "enddt": "end_date", "payeraccnum": "payer_account_number", "payerbankcode": "payer_bank_code", "payername": "payer_name", "sgmnt": "segment_value", "payeraccnumtkn": "payer_account_token", "payeridenttype": "payer_ident_type", "payerident": "payer_ident", "payeridenttkn": "payer_ident_token", "issurctry": "issuer_country", "issurbin": "issuer_bin", "isdefault": "Y", "psptkn": "psp_token", "maxamt": "1000.00", "schedulefreq": "3", "corpident": "corporate_identifier", "amttype": "amount_type", "schedulerelation": "schedule_relation", "scheduleday": "schedule_day", "schemetxnref": "2409243423", "qrstr": "qr_string", "corpacc": "1234567890" } }

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<ack>PASS</ack>
<corpid>CN000002</corpid>
<emandate_resp>eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.RyAD2NS_disLVDhk-Ja-2JoMu6SdOMi_E8sIowXRdGP35kOakvTsE8aDcoW3beUfB9UavtXCsyv2vD61J1dDXNP02Qtwoa-JkhXdghLf0TpUgxewayizhJxRrDNcmgTDVw9WL761RDb2RqPuvnkC_iYF4znD9SUZp-DgzL9Ye1CqW9rM9IzhwDS56B4b20e8so9pck0hpMuKF5hE0-lDdsID7UhTTBCeJUE-Uw4feBRAhUGyeUsbWv8b0NX2HxWBu9cVnhirNT4j2yp-tFOfhni8z4C0Z1iHS7Eyo_n8D9xp3JqknaSqRYO3JPtTCRxNVPDQ4jcimm4eRmCzbfdN_g.n_q7WLrjX4pbDUyL.ZifqpUuCKk7wK43Ts453dT0Wcg2H39CYybPTbSUR3IC1zwqc2BZ4Kkf28Tg_zosptBsWvnxIzavix5TmYTk4BXl7tqHXmquTQ7j9f2EQLA1fdR9OJGUgOF0BUs1NKUsR0TGO_4x80f4jpsABdEZZVZHfSUdY2WnZE1zn_3Rtb1xbVVumDRuD3tp_zq8udOWJGv5XZBxyHImK9L3DazwQQcpZjm8bEII9HPuB9s9QRV82OruCKxT7SYF7Msq4DvMpkJdQG4JA_Hqkwx7TclPqBsINTgJT3ONgC5Viubx_4jjZCDjYIZqu0sO9XW3kkTS2Ef16Uw1EUBOIzvy0NRsfvUmRmnh6cMiVC5gxEkJAHAojdas6ajEq0QtoL5KIFh_0Coznc7ykPLpHAC1lCGxeRd7mccdu1yIUQ6nO3Nc-GrXYJMsGhWbHGzXvIpfAi0DbYBM8X0bdPfmKwExoSGa_f_j6KFMUOeOcA33N70qpsUlLPtHRl0BigH0XHQ2SDUoZOVMRNEuonldeIEM9JsBZLLS4kF-l-0VOxaApBVHjZP_c8OAl0_hwbqL1BNRFJZOru80C6cJ26GnZqJO3Rp_4sir_SqeYX2OD1APQgsNmO0Vtowz8LBLO.d4Lr8wKRJEMkgYgIqTWo3Q</emandate_resp>
</xml>
						
For FAIL acknowledgment
								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<ack>FAIL</ack>
<ackdesc>Sign Error</ackdesc>
</xml>
							

Try it out

Input Fields
corpid
amt
country
currency
actn
ref1
ref2
ref3
ref4
ref5
ref6
ref7
ref8
ref9
ref10
pspid
datetime
Merchant Keys
AES Key
Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
XML request
JSON request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/emandate
Response
Decrypted response

Notification

Merchant is expected to host a REST API (also called as Webhook / Reverse API) to receive real-time notification from Straight2Bank Pay.

As per buyer's user journey, if buyer has successfully authorized a payment, then PSP notifies to Straight2Bank Pay, Straight2Bank Pay saves the status and notifies to Merchant Server in real-time. This notification will be sent only for successful transaction for NEW transactions. For REFUND transactions, Notification will be sent both for Success and Fail scenarios.

Merchant Server is expected to accept the message, saves the status and sends the response synchronously back to Straight2Bank Pay server. In case, Straight2Bank Pay receives timeout error or no response while delivering the notification message, it will automatically retry for 3 days for every 2 hours until the message is successfully delivered and response message is received.

The notification and its response message specifications have been designed by Straight2Bank Pay:


Notification Request (Straight2Bank Pay to Merchant Server)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON as configured in profile

Communication Layer level security

Minimum TLSv1.2 

Message layer level Security

Request: HMAC-SHA256 hashing, AES-256 encryption, RSA2048 Encryption

Response: RS256 Signature , AES-256 encryption

Notification URL

Merchant URL as configured in Profile.

SCB IP Address Following subnet range to be white listed at Merchant server (Same for Test and Production):

166.81.66.31, 166.81.66.32, 166.81.66.33, 166.81.66.34, 166.81.66.35, 166.81.66.36, 166.81.66.37, 166.81.66.38, 166.81.66.39, 166.81.66.40

166.81.85.31, 166.81.85.32, 166.81.85.33, 166.81.85.34, 166.81.85.35, 166.81.85.36, 166.81.85.37, 166.81.85.38, 166.81.85.39, 166.81.85.40

166.81.13.0/25, 166.81.14.0/25, 166.81.23.0/25, 166.81.24.0/25

166.81.78.0/25, 166.81.77.0/25, 166.81.79.0/25, 166.81.80.0/25

Event

Whenever Buyer authorize a payment successfully and or any REFUND transaction reached to final status.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 notifyreq M X(2000)

Key-value payload will be constructed as described in next table, then payload is encrypted (algorithm: AES-256 CBC) using a random key, then encrypted string is base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view sample code to perform AES decryption.

X3 enc_key M X(2000)

Random key used to encrypt 'notifyreq' tag is encrypted using Merchant's public key (algorithm: RSA-2048) and populated here.

Refer to RSA 2048 encryption/decryption section to view sample code to perform RSA decryption.

The following table lists the key name used to construct the value for 'notifyreq' tag, each key-value pair is separated using & (ampersand) character

Request Parameters:

Seq Num Key Name M/O/C Type & Length Remarks
P1 ack M X(10)

"PASS"

Applicable only for

  • Query API Response
  • Collect API Response
  • Refund API Response
  • Postauth API Response
  • Response payload as re-direction back to rurl (value for rurl can be provided in s2bpay.js, bCollect, billCollect)
P2 status M X(10) For possible value, please refer to status values.
P3 statusdesc O X(100) Remarks on status if available.
P4 txntype M X(20) Possible value:
  • NEW
  • REFUND
P5 corpid M X(8) Corp ID of Merchant
P6 amt M N(16,3) 13 integer digits and a precision of 2 decimals
P7 ccy M X(3) 3 character currency code
P8 ctry M X(2) 2 character country code
P9 ref1 O X(100) Reference Number 1
P10 ref2 O X(100) Reference Number 2
P11 ref3 O X(100) Reference Number 3
P12 ref4 O X(100) Reference Number 4
P13 ref5 O X(100) Reference Number 5
P14 corpref C X(100) The unique ref value of NEW Transaction
P15 refundcorpref O X(100) The unique ref value of REFUND Transaction
P16 txnid M X(16) Straight2Bank Pay generated unique transaction ID for this NEW transaction.
P17 refundtxnid O X(16) Straight2Bank Pay generated unique transaction ID for this REFUND transaction.
P18 optxnid O X(75) PSP assignedTransaction ID for NEW Transaction
P19 refundoptxnid O X(75) PSP assigned Transaction ID for REFUND Transaction
P20 qrstr C X(500)

Applicable only in 'collect' API response.

If pspid in 'collect' API request message is meant for QR code generation, then QR string will be generated, base64 encoded and respond back synchronously. Merchant needs to base64 decode, convert the qrstr into QR image and present it to the buyer either in electronic medium or physical bill or invoice.

P21 pspid M X(8)

Not Applicable for 'collect' API response.

PSP ID (indicates payment method). Eg: BDSSLNET, BDSSLCRD, BDSSLNET, SGPAYNOW, HKFPSHKD.

PSP IDs to be obtained from Implementation Manager.

P22 payername O X(70)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Payer Name. It can be included on this notification message.

It is not applicable for all payment methods.

P23 payeraccnum O X(34)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Payer Account Number. It can be included on this notification message if regulator rule allows.

It is not applicable for all payment methods.

P24 payerbankcode O X(50)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Payer Bank Code. It can be included on this notification message.

It is not applicable for all payment methods.

P25 payerident O X(50)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Payer's identity (like mobile number). It can be included on this notification message if regulator rule allows.

It is not applicable for all payment methods.

P26 corpident O X(50)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Merchant's identity (like Biller ID, VPA). It can be included on this notification message.

It is not applicable for all payment methods.

P27 authcode O X(70)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Authorization Code. It can be included on this notification message.

It is not applicable for all payment methods.

P28 date M X(14)

Datetime stamp when the transaction is made.

Format: DDMMYYYYHH24MiSS (GMT+8)

P29 hash M X(200)

HMAC Hash value of entire key-value pair string. Straight2Bank Pay uses HMACSHA256 algorithm by passing Secret key.

Merchant needs to verify this Hash using Verification of Hash Value at Merchant Server, it should not be performed in Browser for security reason. If computed Hash value does not match with the hash value in the message, then Merchant Server needs to reject the message.


Notification Response (Merchant Server to Straight2Bank Pay)

Merchant is expected to generate synchronous response for each notify message that is pushed to Merchant's Webhook URL.

Message Specification
Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 notify_resp M X(2000)

Key-value payload needs to be constructed as described in next table, then payload needs to be AES-256 CBC encrypted using shared secret key, encrypted string needs to be base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view the sample code to perform AES encryption.

The following table lists the key name used to construct the value for 'notify_resp' tag. Each key-value pair needs to be separated using & (ampersand) character.

Seq Num Key Name M/O/C Type & Length Remarks
P1 status M X(10) Possible Value:
  • SUCCESS
  • ERROR
P2 statusdesc O X(100)

Description of the Error.

E.g. Hashing Error

P3 ackref M X(16) Acknowledgment Reference which can be used to investigate of any missing notification.
P4 txnid M X(16) Transaction ID that has been sent in the notifyreq message.
P5 date O X(14)

Datetime stamp of Merchant server.

Format: DDMMYYYYHH24MiSS (GMT+8)

P6 sign M X(200)

Signature of entire key-value pair string using Merchant's Private key. Algorithm to be used : RS256

Refer to Generation of Digital Signature


Request and Response Samples

Notification Request - Sample Message

Clear-text value for 'notifyreq' tag:

amt=1.00&ccy=INR&corpid=CUIIN001&corpref=8000083745&ctry=IN&date=09012018214705&optxnid=1&ref1=ref1&ref2=ref2&ref3=ref3&ref4=ref4&ref5=ref5&status=SUCCESS&txnid=8000083745&txntype=NEW&hash=A7F4CB71B49E86B30BE4ECA2561F998223FA1FAD83531A07DFF982979CEFB862

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CUIIN001</corpid>
<notifyreq>MkxJywCyD+nUMsgb7AqAjMWmL6VclHHSYP4Xjnl2IJejEiQLAFbwMxcj/91rTK05qzIye8y4e3jfbLlY0wtjVe4IbDo7zSaP1A2zrogCV5VV0auRw2mB89EDtdAwbGHRNC3JMnbFLL3/8F6lN1YALs6eHE4W8W/rkunCnl/OUZhcTE
mwzUPniDdXkJaiRN/zIVR9R2C///ZmxSfN7cltENUiqJdI6qSDaV/UnsIZLKwIRL/o1ORnS3/oO/7GqciXwY63r+wpgeIwoGseaJGhwpXNgQ2AP7A6i70PkmVT3D1hXp+I5ppxMKgpL3B/BPwP5e3rQp/MXlP8Urvj4qf/IQ==</notifyreq>
<enc_key>I5z/K2x1DNxJJW3oJEw++JzaSwYl+ZGYhvMmgeXZ7cL1cSUEd+CIT9mpc/dRPQSeGDp4pgnJYtx7/J+pbin7Wt9V1Ix9pFrpaHOj3upFi4jHzuLxh1vnxzREWrYyx7m1jfgqJfJpk1H0QfaZyqh8KYJ1lI5tHcQQsf8QrdhsCpBxUoDo4
hYQu1vpHuoKypw6teMI1bZFxubWFDe+QCJifZxWcBEProTYKpk6XgOnXR62X3jAUuIIl4MUE9SiziFqQMThhxL0XRqYsrvovHJwFCJEHRA6+ew4pa1fmY1rchp/VCDlkXHCyTc2rGLfeXC2wsORvKJ4MtNInPoXty8T6Q==</enc_key>
</xml>
							

Notification Response - Sample Message

Clear-text value for 'notify_resp' tag:

ackref=8900064789&date=13092016181800&status=SUCCESS&txnid=6000064687&sign=E9C4E04664A469EA2196820B12D1D0EF4E209BE8A456D7B806A0EED2264C1C81

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CN000001</corpid>
<notify_resp> 2nK57VdsNzeXj229xl7mIKjBEM0xjfutFGkjry7v2IEKUseJ9URgLkbz1z504w3pvv00VDlrvObH+r1G5VUeY8XNvzWF1i1e8WIVKauYeFo2wF3cMRBPZ4ObGqF/KmUykb9hM7Sd5wnz9d/B6
CEzvJh305thMfKH+AYz70IX+BdONzeI3XAOcm0YWr2MMQdj</notify_resp>
</xml>
							

Try it out

Input Fields
corpid

Please choose either scbtxnid or corpref

optxnid
payername
payeraccnum
payerbankcode
payerident
corpident
authcode
Submit request


Mandate Notification [Key Value Pair]

Mandate Notification [Key Value Pair] Request (Straight2Bank Pay to Merchant Server)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON as configured in profile

Communication Layer level security

Minimum TLSv1.2 

Message layer level Security

Request: HMAC-SHA256 hashing, AES-256 encryption, RSA2048 Encryption

Response: RS256 Signature , AES-256 encryption

Notification URL

Merchant URL as configured in Profile.

SCB IP Address Following subnet range to be white listed at Merchant server (Same for Test and Production):

166.81.66.31, 166.81.66.32, 166.81.66.33, 166.81.66.34, 166.81.66.35, 166.81.66.36, 166.81.66.37, 166.81.66.38, 166.81.66.39, 166.81.66.40

166.81.85.31, 166.81.85.32, 166.81.85.33, 166.81.85.34, 166.81.85.35, 166.81.85.36, 166.81.85.37, 166.81.85.38, 166.81.85.39, 166.81.85.40

166.81.13.0/25, 166.81.14.0/25, 166.81.23.0/25, 166.81.24.0/25

166.81.78.0/25, 166.81.77.0/25, 166.81.79.0/25, 166.81.80.0/25

Event

Whenever Buyer authorizes an Mandate using Card (Master Card / Visa) or Bank Account (like eGiro for SG)

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 mndt_notifyreq M X(2000)

Key-value payload will be constructed as described in next table, then payload is encrypted (algorithm: AES-256 CBC) using a random key, then encrypted string is base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view sample code to perform AES decryption.

X3 enc_key M X(2000)

Random key used to encrypt 'mndt_notifyreq' tag is encrypted using Merchant's public key (algorithm: RSA-2048) and populated here.

Refer to RSA 2048 encryption/decryption section to view sample code to perform RSA decryption.

The following table lists the key name used to construct the value for 'mndt_notifyreq' tag, each key-value pair is separated using & (ampersand) character

Request Parameters:

Seq Num Key Name M/O/C Type & Length Remarks
M1 ack M X(10)

"PASS"

Applicable only for

  • Response payload as re-direction back to rurl (value for rurl can be provided as part of lmandate in cencstr or configured in corpId profile)
M2 status M X(10)

For possible value

  • AUTHORIZED - it is temporary status, the user has authorized, but it is not confirmed by Payer Bank
  • CANCELLED
  • FAIL
  • PENDING
  • SUCCESS: only for this status, transaction can be initiated
M3 statusdesc O X(100) Remarks on status if available.
M4 mndtid M N(14) Straight2Bank Pay generated unique Mandate ID
M5 corpid M X(8) Corp ID of Merchant
M6 payerid M X(50) Merchant assigned payer id as part of ref field.
M7 txntype M X(20)

Possible value:

  • MANDATE
M8 txnref O X(50) Reference number that is sent to PSP to identify Mandate.
M9 ref1 O X(250) Reference Number 1
M10 ref2 O X(250) Reference Number 2
M11 ref3 O X(250) Reference Number 3
M12 ref4 O X(250) Reference Number 4
M13 ref5 O X(250) Reference Number 5
M14 ref6 O X(250) Reference Number 6
M15 ref7 O X(250) Reference Number 7
M16 ref8 O X(250) Reference Number 8
M17 ref9 O X(250) Reference Number 9
M18 ref10 O X(250) Reference Number 10
M19 ctry M X(2) 2 character country code
M20 ccy M X(3) 3 character currency code
M21 pspid M X(8) PSP ID (indicates payment method). Eg: SGWPCRD1. PSP IDs to be obtained from Implementation Manager
M22 isdefault O X(1) Possible value Y or N to indicates whether this mandate_notify is default for the payerid
M23 billref O X(50) Bill (Mandate) Reference sent to PSP
M24 psptkn O X(4000) Psp assigned token for this mandate
M25 maxamt O N(18,3) Maximum amount assigned by Payer
M26 strtdt O X(8)

Mandate start date

Format: DDMMYYYY (GMT+8)

M27 enddt O X(8)

Mandate expiry (End) data

Format: DDMMYYYY (GMT+8)

M28 sgmnt O X(50)

Mandate segment, possible value:

  • RETAIL
  • CORPORATE
M29 payeraccnum O X(50) Payer Account in clear text, it will be populated if no regulatory allows to share the account number
M30 Payeraccnumtkn O X(250) Masked payer Account Number
M31 payerbankcode O X(50) Payer Bank Code or Card scheme name
M32 payername O X(75) Payer Name
M33 payeridenttype O X(50) Payer Identifier Type
M34 payerident O X(250) Payer Identifier Value
M35 payeridenttkn O X(250) Payer Identifier Value token
M36 issurctry O X(2) Country Code Card Issuer
M37 Issurbin O X(100) Issuer Identity
M38 date M X(14)

Datetime stamp when the transaction is made.

Format: DDMMYYYYHH24MiSS (GMT+8)

M39 hash M X(200)

HMAC Hash value of entire key-value pair string. Straight2Bank Pay uses HMACSHA256 algorithm by passing Secret key.

Merchant needs to verify this Hash using Verification of Hash Value at Merchant Server, it should not be performed in Browser for security reason. If computed Hash value does not match with the hash value in the message, then Merchant Server needs to reject the message.


Mandate Notification [Key Value Pair] Response (Merchant Server to Straight2Bank Pay)

Merchant is expected to generate synchronous response for each notify message that is pushed to Merchant's Webhook URL.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 mndt_notify_resp M X(2000)

Key-value payload needs to be constructed as described in next table, then payload needs to be AES-256 CBC encrypted using shared secret key, encrypted string needs to be base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view the sample code to perform AES encryption.

The following table lists the key name used to construct the value for 'mndt_notify_resp' tag. Each key-value pair needs to be separated using & (ampersand) character.

Seq Num Key Name M/O/C Type & Length Remarks
P1 status M X(10) Possible Value:
  • SUCCESS
  • ERROR
P2 statusdesc O X(100)

Description of the Error.

E.g. Hashing Error

P3 ackref M X(16) Acknowledgment Reference which can be used to investigate of any missing notification.
P4 mndtid M X(16) Mandate ID that has been sent in the mndt_notifyreq message.
P5 date O X(14)

Datetime stamp of Merchant server.

Format: DDMMYYYYHH24MiSS (GMT+8)

P6 sign M X(200)

Signature of entire key-value pair string using Merchant's Private key. Algorithm to be used : RS256

Refer to Generation of Digital Signature


Mandate Notification [Key Value Pair] Request and Response Samples

Mandate Notification [Key Value Pair] Request - Sample Message

Clear-text value for 'mndt_notifyreq' tag:

amt=1.00&ccy=INR&corpid=CUIIN001&corpref=8000083745&ctry=IN&date=09012018214705&optxnid=1&ref1=ref1&ref2=ref2&ref3=ref3&ref4=ref4&ref5=ref5&status=SUCCESS&txnid=8000083745&txntype=NEW&hash=A7F4CB71B49E86B30BE4ECA2561F998223FA1FAD83531A07DFF982979CEFB862

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CUIIN001</corpid>
<mndt_notifyreq>MkxJywCyD+nUMsgb7AqAjMWmL6VclHHSYP4Xjnl2IJejEiQLAFbwMxcj/91rTK05qzIye8y4e3jfbLlY0wtjVe4IbDo7zSaP1A2zrogCV5VV0auRw2mB89EDtdAwbGHRNC3JMnbFLL3/8F6lN1YALs6eHE4W8W/rkunCnl/OUZhcTE
mwzUPniDdXkJaiRN/zIVR9R2C///ZmxSfN7cltENUiqJdI6qSDaV/UnsIZLKwIRL/o1ORnS3/oO/7GqciXwY63r+wpgeIwoGseaJGhwpXNgQ2AP7A6i70PkmVT3D1hXp+I5ppxMKgpL3B/BPwP5e3rQp/MXlP8Urvj4qf/IQ==</mndt_notifyreq>
<enc_key>I5z/K2x1DNxJJW3oJEw++JzaSwYl+ZGYhvMmgeXZ7cL1cSUEd+CIT9mpc/dRPQSeGDp4pgnJYtx7/J+pbin7Wt9V1Ix9pFrpaHOj3upFi4jHzuLxh1vnxzREWrYyx7m1jfgqJfJpk1H0QfaZyqh8KYJ1lI5tHcQQsf8QrdhsCpBxUoDo4
hYQu1vpHuoKypw6teMI1bZFxubWFDe+QCJifZxWcBEProTYKpk6XgOnXR62X3jAUuIIl4MUE9SiziFqQMThhxL0XRqYsrvovHJwFCJEHRA6+ew4pa1fmY1rchp/VCDlkXHCyTc2rGLfeXC2wsORvKJ4MtNInPoXty8T6Q==</enc_key>
</xml>
							

Mandate Notification [Key Value Pair] Response - Sample Message

Clear-text value for 'mndt_notify_resp' tag:

ackref=8900064789&date=13092016181800&status=SUCCESS&txnid=6000064687&sign=E9C4E04664A469EA2196820B12D1D0EF4E209BE8A456D7B806A0EED2264C1C81

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CN000001</corpid>
<mndt_notify_resp> 2nK57VdsNzeXj229xl7mIKjBEM0xjfutFGkjry7v2IEKUseJ9URgLkbz1z504w3pvv00VDlrvObH+r1G5VUeY8XNvzWF1i1e8WIVKauYeFo2wF3cMRBPZ4ObGqF/KmUykb9hM7Sd5wnz9d/B6
CEzvJh305thMfKH+AYz70IX+BdONzeI3XAOcm0YWr2MMQdj</mndt_notify_resp>
</xml>
							

Try it out

Input Fields
corpid
mndttid
txnref
payerid
txntype
ref1
ref2
ref3
ref4
ref5
pspid
ctry
ccy
isDefault
date
Submit request

Mandate Notification [JWE Format]

Mandate Notification [JWE Format] Request (Straight2Bank Pay to Merchant Server)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON as configured in profile

Communication Layer level security

Minimum TLSv1.2 

Message layer level Security

Request and Response: JWE String (RS-256 Sign, AES-256 GCM encryption)

SCB RSA Public Key: https://test-s2bpay.sc.com/s2bpaysit/devguide#idocs_pubkey

Notification URL

Merchant URL as configured in Profile.

SCB IP Address Following subnet range to be white listed at Merchant server (Same for Test and Production):

166.81.66.31, 166.81.66.32, 166.81.66.33, 166.81.66.34, 166.81.66.35, 166.81.66.36, 166.81.66.37, 166.81.66.38, 166.81.66.39, 166.81.66.40

166.81.85.31, 166.81.85.32, 166.81.85.33, 166.81.85.34, 166.81.85.35, 166.81.85.36, 166.81.85.37, 166.81.85.38, 166.81.85.39, 166.81.85.40

166.81.13.0/25, 166.81.14.0/25, 166.81.23.0/25, 166.81.24.0/25

166.81.78.0/25, 166.81.77.0/25, 166.81.79.0/25, 166.81.80.0/25

Event

Whenever Buyer authorizes an Mandate using Card (Master Card / Visa) or Bank Account (like eGiro for SG)

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 mndt_notifyreq M X(2000)

This tag contains JWE String

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in JWS String Table

Request Parameters:

Seq Num Key Name M/O/C Type & Length Remarks
M1 ack M X(10)

"PASS"

Applicable only for

  • Response payload as re-direction back to rurl (value for rurl can be provided as part of lmandate in cencstr or configured in corpId profile)
M2 status M X(10)

For possible value

  • AUTHORIZED - it is temporary status, the user has authorized, but it is not confirmed by Payer Bank
  • CANCELLED
  • FAIL
  • PENDING
  • SUCCESS: only for this status, transaction can be initiated
M3 statusdesc O X(100) Remarks on status if available.
M4 mndtid M N(14) Straight2Bank Pay generated unique Mandate ID
M5 corpid M X(8) Corp ID of Merchant
M6 payerid M X(50) Merchant assigned payer id as part of ref field.
M7 txntype M X(20)

Possible value:

  • MANDATE
M8 txnref O X(50) Reference number that is sent to PSP to identify Mandate.
M9 ref1 O X(250) Reference Number 1
M10 ref2 O X(250) Reference Number 2
M11 ref3 O X(250) Reference Number 3
M12 ref4 O X(250) Reference Number 4
M13 ref5 O X(250) Reference Number 5
M14 ref6 O X(250) Reference Number 6
M15 ref7 O X(250) Reference Number 7
M16 ref8 O X(250) Reference Number 8
M17 ref9 O X(250) Reference Number 9
M18 ref10 O X(250) Reference Number 10
M19 ctry M X(2) 2 character country code
M20 ccy M X(3) 3 character currency code
M21 pspid M X(8) PSP ID (indicates payment method). Eg: SGWPCRD1. PSP IDs to be obtained from Implementation Manager
M22 isdefault O X(1) Possible value Y or N to indicates whether this mandate_notify is default for the payerid
M23 billref O X(50) Bill (Mandate) Reference sent to PSP
M24 psptkn O X(4000) Psp assigned token for this mandate
M25 maxamt O N(18,3) Maximum amount assigned by Payer
M26 strtdt O X(8)

Mandate start date

Format: DDMMYYYY (GMT+8)

M27 enddt O X(8)

Mandate expiry (End) data

Format: DDMMYYYY (GMT+8)

M28 sgmnt O X(50)

Mandate segment, possible value:

  • RETAIL
  • CORPORATE
M29 payeraccnum O X(50) Payer Account in clear text, it will be populated if no regulatory allows to share the account number
M30 Payeraccnumtkn O X(250) Masked payer Account Number
M31 payerbankcode O X(50) Payer Bank Code or Card scheme name
M32 payername O X(75) Payer Name
M33 payeridenttype O X(50) Payer Identifier Type
M34 payerident O X(250) Payer Identifier Value
M35 payeridenttkn O X(250) Payer Identifier Value token
M36 issurctry O X(2) Country Code Card Issuer
M37 Issurbin O X(100) Issuer Identity
M38 date M X(14)

Datetime stamp when the transaction is made.

Format: DDMMYYYYHH24MiSS (GMT+8)


Mandate Notification [JWE Format] Response (Merchant Server to Straight2Bank Pay)

Merchant is expected to generate synchronous response for each notify message that is pushed to Merchant's Webhook URL.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 mndt_notify_resp M X(2000)

This tag contains JWE String

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in JWS String Table

Payload Attributes

Seq Num Key Name M/O/C Type & Length Remarks
P1 status M X(10) Possible Value:
  • SUCCESS
  • ERROR
P2 statusdesc O X(100)

Description of the Error.

E.g. Hashing Error

P3 ackref M X(16) Acknowledgment Reference which can be used to investigate of any missing notification.
P4 mndtid M X(16) Mandate ID that has been sent in the mndt_notifyreq message.
P5 date O X(14)

Datetime stamp of Merchant server.

Format: DDMMYYYYHH24MiSS (GMT+8)


Mandate Notification [JWE Format] Request and Response Samples

Mandate Notification [JWE Format] Request - Sample Message

Clear-text value for 'mndt_notifyreq' tag:

{ "amt": "1.00", "ccy": "INR", "corpid": "CUIIN001", "corpref": "8000083745", "ctry": "IN", "date": "09012018214705", "optxnid": "1", "ref1": "ref1", "ref2": "ref2", "ref3": "ref3", "ref4": "ref4", "ref5": "ref5", "status": "SUCCESS", "txnid": "8000083745", "txntype": "NEW" }

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CUIIN001</corpid>
<mndt_notifyreq>eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.RyAD2NS_disLVDhk-Ja-2JoMu6SdOMi_E8sIowXRdGP35kOakvTsE8aDcoW3beUfB9UavtXCsyv2vD61J1dDXNP02Qtwoa-JkhXdghLf0TpUgxewayizhJxRrDNcmgTDVw9WL761RDb2RqPuvnkC_iYF4znD9SUZp-DgzL9Ye1CqW9rM9IzhwDS56B4b20e8so9pck0hpMuKF5hE0-lDdsID7UhTTBCeJUE-Uw4feBRAhUGyeUsbWv8b0NX2HxWBu9cVnhirNT4j2yp-tFOfhni8z4C0Z1iHS7Eyo_n8D9xp3JqknaSqRYO3JPtTCRxNVPDQ4jcimm4eRmCzbfdN_g.n_q7WLrjX4pbDUyL.ZifqpUuCKk7wK43Ts453dT0Wcg2H39CYybPTbSUR3IC1zwqc2BZ4Kkf28Tg_zosptBsWvnxIzavix5TmYTk4BXl7tqHXmquTQ7j9f2EQLA1fdR9OJGUgOF0BUs1NKUsR0TGO_4x80f4jpsABdEZZVZHfSUdY2WnZE1zn_3Rtb1xbVVumDRuD3tp_zq8udOWJGv5XZBxyHImK9L3DazwQQcpZjm8bEII9HPuB9s9QRV82OruCKxT7SYF7Msq4DvMpkJdQG4JA_Hqkwx7TclPqBsINTgJT3ONgC5Viubx_4jjZCDjYIZqu0sO9XW3kkTS2Ef16Uw1EUBOIzvy0NRsfvUmRmnh6cMiVC5gxEkJAHAojdas6ajEq0QtoL5KIFh_0Coznc7ykPLpHAC1lCGxeRd7mccdu1yIUQ6nO3Nc-GrXYJMsGhWbHGzXvIpfAi0DbYBM8X0bdPfmKwExoSGa_f_j6KFMUOeOcA33N70qpsUlLPtHRl0BigH0XHQ2SDUoZOVMRNEuonldeIEM9JsBZLLS4kF-l-0VOxaApBVHjZP_c8OAl0_hwbqL1BNRFJZOru80C6cJ26GnZqJO3Rp_4sir_SqeYX2OD1APQgsNmO0Vtowz8LBLO.d4Lr8wKRJEMkgYgIqTWo3;</mndt_notifyreq>
</xml>
							

Mandate Notification [JWE Format] Response - Sample Message

Clear-text value for 'mndt_notify_resp' tag:

{ "ackref": "8900064789", "date": "13092016181800", "status": "SUCCESS", "txnid": "6000064687"}

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CN000001</corpid>
<mndt_notify_resp>eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.RyAD2NS_disLVDhk-Ja-2JoMu6SdOMi_E8sIowXRdGP35kOakvTsE8aDcoW3beUfB9UavtXCsyv2vD61J1dDXNP02Qtwoa-JkhXdghLf0TpUgxewayizhJxRrDNcmgTDVw9WL761RDb2RqPuvnkC_iYF4znD9SUZp-DgzL9Ye1CqW9rM9IzhwDS56B4b20e8so9pck0hpMuKF5hE0-lDdsID7UhTTBCeJUE-Uw4feBRAhUGyeUsbWv8b0NX2HxWBu9cVnhirNT4j2yp-tFOfhni8z4C0Z1iHS7Eyo_n8D9xp3JqknaSqRYO3JPtTCRxNVPDQ4jcimm4eRmCzbfdN_g.n_q7WLrjX4pbDUyL.ZifqpUuCKk7wK43Ts453dT0Wcg2H39CYybPTbSUR3IC1zwqc2BZ4Kkf28Tg_zosptBsWvnxIzavix5TmYTk4BXl7tqHXmquTQ7j9f2EQLA1fdR9OJGUgOF0BUs1NKUsR0TGO_4x80f4jpsABdEZZVZHfSUdY2WnZE1zn_3Rtb1xbVVumDRuD3tp_zq8udOWJGv5XZBxyHImK9L3DazwQQcpZjm8bEII9HPuB9s9QRV82OruCKxT7SYF7Msq4DvMpkJdQG4JA_Hqkwx7TclPqBsINTgJT3ONgC5Viubx_4jjZCDjYIZqu0sO9XW3kkTS2Ef16Uw1EUBOIzvy0NRsfvUmRmnh6cMiVC5gxEkJAHAojdas6ajEq0QtoL5KIFh_0Coznc7ykPLpHAC1lCGxeRd7mccdu1yIUQ6nO3Nc-GrXYJMsGhWbHGzXvIpfAi0DbYBM8X0bdPfmKwExoSGa_f_j6KFMUOeOcA33N70qpsUlLPtHRl0BigH0XHQ2SDUoZOVMRNEuonldeIEM9JsBZLLS4kF-l-0VOxaApBVHjZP_c8OAl0_hwbqL1BNRFJZOru80C6cJ26GnZqJO3Rp_4sir_SqeYX2OD1APQgsNmO0Vtowz8LBLO.d4Lr8wKRJEMkgYgIqTWo3;</mndt_notify_resp>
</xml>
							

Try it out

Input Fields
corpid
mndttid
txnref
payerid
txntype
ref1
ref2
ref3
ref4
ref5
pspid
ctry
ccy
isDefault
date
Submit request



Query

Straight2Bank Pay may fail to deliver the notification message if Merchant server is not reachable or Merchant URL's SSL certificate is not matching, etc. As an alternative way to get the status, Straight2Bank Pay hosts Query API. If Merchant has not received the expected notification message from Straight2Bank Pay in time or Merchant does not want to host an API to receive notification, then Merchant can make use of Query API to get the status of a transaction.

This API can be used to get the status of Refund transaction as well.


Query Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

Message layer level Security

Request: RS256 Signature , AES-256 encryption

Response: HMAC-SHA256 hashing, AES-256 encryption, RSA2048 Encryption

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/query

Prod: https://s2bpay.sc.com/s2bpay/query

Event

Whenever Merchant needs status of a transactions for both NEW and REFUND.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 query_req M X(2000)

Key-value payload needs to be constructed as described in the next table, then payload needs to be AES-256 CBC encrypted using shared secret key, encrypted string needs to be base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view the sample code to perform AES encryption.

The following table lists the key names used to construct the value for 'query_req' tag. Each key-value pair needs to be concatenated using & (ampersand) character.

Seq Num Key Name M/O/C Type & Length Remarks
P1 corpid M X(8) Corp ID of Merchant.
P2 corpref M X(100) Unique reference of transaction for which status is being queried.
P3 datetime M X(14)

Datetime stamp of client server.

Format: DDMMYYYYHH(24)MISS

P4 sign M X(200)

Signature of entire key-value pair string using Merchant's Private key.

Algorithm to be used : RS256

Refer to Generation of Digital Signature


Query Response (Straight2Bank Pay to Merchant Server)

Straight2Bank Pay receives the Query Request, decrypts, validates the signature and locates the requested transaction using Corp ID and corpref. If corresponding transaction is found, then response will be generated synchronously and sent back to Merchant.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 ack M X(10) Possible Value
  • PASS
  • FAIL
X2 ackdesc O X(100)

This tag will be populated only if ack is FAIL.

Possible error description:

  • Hashing Error
  • Invalid Request
  • Invalid Date time in Request
  • Invalid Corporate Id
X3 corpid M X(8) Corp ID of Merchant.
X4 query_resp M X(2000)

Key-value payload will be constructed as described in section Notification Request, then payload is encrypted (algorithm: AES-256 CBC) using a random key, encrypted string is base64 encoded and here.

Refer to AES256 encryption/decryption section to view sample code to perform AES decryption.

X5 enc_key M X(2000)

Random key used to encrpt 'query_resp' tag is encrypted using Merchant's public key (algorithm: RSA-2048) and populated here.

Refer to RSA 2048 encryption/decryption section to view sample code to perform RSA decryption.

Each key-value pair used to construct payload string for 'query_resp' tag is concatenated using & (ampersand) character. If status is ERROR in query response, then following parameters are not applicable: txntype, amt, ccy, ctry, ref1, ref2, ref3, ref4, ref5, refundcorpref, txnid, refundtxnid, optxnid, refundoptxnid.


Request and Response Samples

Query Request - Sample Message

Clear-text value for 'query_req' tag:

corpid=CN000001&corpref=1234567890&datetime=13092016181800&sign=4A3BA9484039D100FE75D4AECB1FE6496876546004BFA118E1D06EBE83E03725

Sample - XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CN000001</corpid>
<query_req>+PUC1/q3BSYPC38PPSIXJPZaQ/lblAlOAf59QpBTH4ba6h4OyxsKaKO2NGHXsSoq1TU0EAfrvw5mQf51MvhABojj1/b/FVcgGX3Zj8/7ZW0Oi2Vic/Em8ZhojTbP+UfUAxqHDzSmB/fI20XHpXFJb9DUGbl7dBfEvuPFMR9Xr24=</query_req>
</xml>
							

Query Response - Sample Message

Clear-text value for 'query_resp' tag for SUCCESSFUL status:

ack=PASS&amt=10000.00&ccy=VND&corpid=CUIMOMO1&corpref=7000082839&ctry=VN&date=09012018230344&optxnid=131760705&ref1=test1&ref2=test2&ref3=test3&ref4=test4&status=SUCCESSFUL&statusdesc=RECONCILED&txnid=7000082839&txntype=NEW&hash=A5A7515CCB973E8182A8AF9E1D726AE1FA980D0E8773F6A384E7DA477020A0E0

Clear-text value for 'query_resp' tag for UNSUCCESSFUL status:

ack=PASS&amt=10000.00&ccy=VND&corpid=CUIMOMO1&corpref=8000083727&ctry=VN&date=09012018223647&optxnid=1515479610685&ref1=ref1&ref2=ref2&ref3=ref3&ref4=ref4&ref5=ref5&status=UNSUCCESSFUL&statusdesc=Order was canceled by user&txnid=8000083727&txntype=NEW&hash=E8CAB36EAED77377E8F815FFE043377B09242BCF658BB449079E1987CED27CE8

Clear-text value for 'query_resp' tag for PENDING status:

ack=PASS&amt=10000.00&ccy=VND&corpid=CUIMOMO1&corpref=8000002012&ctry=VN&date=14022018153025&optxnid=0&ref1=ref1&ref2=ref2&ref3=ref3&ref4=ref4&ref5=ref5&status=PENDING&txnid=8000002012&txntype=NEW&hash=BDA180AC88A5E72683B21B0CA4466684CC4A1FBD844B0CCA1E3543A00D8F5451

Clear-text value for 'query_resp' tag for ERROR status:

ack=PASS&corpid=CUIMOMO1&corpref=9999999991&date=09012018173223&status=ERROR&statusdesc=Transaction Not Found&hash=AEDC5F1B10F26346EA27A6954004D64FB9480FE388D11E70A33D94ADFC82D97C

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<ack>PASS</ack>
<corpid>CUIMOMO1</corpid>
<query_resp>vYusFLuU5LtOwTU1GOVz58xFvbxnCC3Gw/vk67zzGQe3MW4iE5fsDSmVcCp3CIktHdMTku7Pbdjw1yn3NHAFnbFZSvhKgcbm3DRvYYE2dMUXs1yA4AgU9w252sGWzLNGXBh2qNqG1QoLXKxxFIgg1R/1q4K+txMF+9+FPAL4GGHcu0WvQ5YY6VBMhpFuj5b3dWifFM9G89K/wVox86BUfJ625n4BI5ZTHveMC4TJia/UHLOM4EHvdG7MYwXmsnbjO9FLpUNBFq7b4C4nxN34SoRq0hT2e0xIBNBmFuD63diNvS2tOY5rT0TEFdFn4fFS3nJNyezUjOfqBLmqGsED8yITudi9GN7VXT/5+hKPtSU05FbOm4/NIjH5/Kf5fIhDjn/SqP5ERT1XcI7zSxzcNQ==  AfBeiFGkBluQFPTyk43EQc4xMrIW2HoJT+fx0V+sLSYFjAkvwPp8+ptI+Nl+xXtgKOqcsD1/NiQBEx+GRfJlkv2GM1nZga7rodmJG4XeELhccBhDSYaTkhNZv2dKvlOiSU0wb1K1GJQMPRX0eDbebnir9ZO3Vi2yVbqiPjZPm52hUpV3PpwHaVFgE3qmHJ0+wNEJrDhzZ8hO/c/2lhvLubgJuBKINEQqPne+XPmjrAjc2kHZUeXwN7RhlqgIo5Mipag/p1+Ed+Fk4Q2XZE5J3lzfwEnzLLiQwOyMgzK/rU68zjPO+oFruKo8FcHG/AoisaqDW5qIFEicVNLp7nm25w==</enc_key>
</xml>













							
				
				
						

Try it out

Input Fields
corpid
corpref
datetime
Merchant Keys
AES Key
Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
XML request
JSON request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/query
Response
Decrypted response

Mandate Query

Straight2Bank Pay may fail to deliver the mandate notification message if Merchant server is not reachable or Merchant URL's SSL certificate is not matching, etc. As an alternative way to get the status, Straight2Bank Pay hosts Mandate Query API. If Merchant has not received the expected notification message from Straight2Bank Pay in time or Merchant does not want to host an API to receive notification, then Merchant can make use of Mandate Query API to get the status of a mandate.


Mandate Query Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

JSON

Communication Layer level security

TLSv1.2

Message layer level Security

Request and Response: JWE String (RS-256 Sign, AES-256 GCM encryption)

SCB RSA Public Key: https://test-s2bpay.sc.com/s2bpaysit/devguide#idocs_pubkey

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/mandatequery

Prod: https://s2bpay.sc.com/s2bpay/mandatequery

Event

Whenever Merchant needs status of a mandate.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 mandatequery_req M X(2000)

This tag can either contain JWE string / AES-256 encrypted string as BAU.

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in JWS String Table

The following tables lists the details used to construct the value for 'mandatequery_req' tag.

Payload Attributes

Seq Num Key Name M/O/C Type & Length Remarks
P1 corpid M X(8) Corp ID of Merchant
P2 payerid M X(100) payer_id
P3 billref M X(100) client reference of mandate
P4 pspid M X(8) PSP for which mandate query is being initiated
IN Mandate: INUPIDDI
SG Mandate: SGRTDDI1
(In case of SG PSPID, mandate status will be fetched from mandate table)
P5 actn C X(1) Possible Value:
C - Default value.
A - Amend
D - Delete
P6 datetime M X(14) Datetime stamp of client server.
Format: DDMMYYYYHH(24)MISS

Mandate Query Response (Straight2Bank Pay to Merchant Server)

Straight2Bank Pay receives the Mandate Query Request, decrypts, validates the signature and locates the requested transaction using Corp ID and mandate ref. If corresponding transaction is found, then response will be generated synchronously and sent back to Merchant.

Message Specification

Seq Num Key M/O/C Type(Length) Remarks
R1 ack M X(10) Possible Value: PASS / FAIL. Applicable only for sync response of eMandate and mandate query.
R2 ackdesc O X(100) This tag will be populated only if ack is FAIL. Applicable only for sync response of eMandate and mandate query.
R3 corpid C X(8) Corp ID of Merchant. Present only when ack=PASS for sync response of eMandate and mandate query. Notification request message CorpId will be populated.
R4 mandatequery_resp C X(2000)

This tag can either contain JWE string / AES-256 encrypted string as BAU.

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in JWS String Table

Payload Attributes

Message and Payload specification are same as Mandate Notification [JWE Format] Request .


Request and Response Samples

Mandate Query Request - Sample Message

Clear-text value for 'mandatequery_req' tag:

{ "corpid": "CN000001", "payerid": "110520211929288", "billref": "110520211929288", "pspid": "SGRTDDI1", "actn": "C", "datetime": "13092016181800" }

Sample - XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CN000001</corpid>
<mandatequery_req>eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.RyAD2NS_disLVDhk-Ja-2JoMu6SdOMi_E8sIowXRdGP35kOakvTsE8aDcoW3beUfB9UavtXCsyv2vD61J1dDXNP02Qtwoa-JkhXdghLf0TpUgxewayizhJxRrDNcmgTDVw9WL761RDb2RqPuvnkC_iYF4znD9SUZp-DgzL9Ye1CqW9rM9IzhwDS56B4b20e8so9pck0hpMuKF5hE0-lDdsID7UhTTBCeJUE-Uw4feBRAhUGyeUsbWv8b0NX2HxWBu9cVnhirNT4j2yp-tFOfhni8z4C0Z1iHS7Eyo_n8D9xp3JqknaSqRYO3JPtTCRxNVPDQ4jcimm4eRmCzbfdN_g.n_q7WLrjX4pbDUyL.ZifqpUuCKk7wK43Ts453dT0Wcg2H39CYybPTbSUR3IC1zwqc2BZ4Kkf28Tg_zosptBsWvnxIzavix5TmYTk4BXl7tqHXmquTQ7j9f2EQLA1fdR9OJGUgOF0BUs1NKUsR0TGO_4x80f4jpsABdEZZVZHfSUdY2WnZE1zn_3Rtb1xbVVumDRuD3tp_zq8udOWJGv5XZBxyHImK9L3DazwQQcpZjm8bEII9HPuB9s9QRV82OruCKxT7SYF7Msq4DvMpkJdQG4JA_Hqkwx7TclPqBsINTgJT3ONgC5Viubx_4jjZCDjYIZqu0sO9XW3kkTS2Ef16Uw1EUBOIzvy0NRsfvUmRmnh6cMiVC5gxEkJAHAojdas6ajEq0QtoL5KIFh_0Coznc7ykPLpHAC1lCGxeRd7mccdu1yIUQ6nO3Nc-GrXYJMsGhWbHGzXvIpfAi0DbYBM8X0bdPfmKwExoSGa_f_j6KFMUOeOcA33N70qpsUlLPtHRl0BigH0XHQ2SDUoZOVMRNEuonldeIEM9JsBZLLS4kF-l-0VOxaApBVHjZP_c8OAl0_hwbqL1BNRFJZOru80C6cJ26GnZqJO3Rp_4sir_SqeYX2OD1APQgsNmO0Vtowz8LBLO.d4Lr8wKRJEMkgYgIqTWo3Q;</mandatequery_req>
</xml>
							

Mandate Query Response - Sample Message

Clear-text value for 'mandatequery_resp' tag for SUCCESSFUL status:

{ "status": "SUCCESS", "statusdesc": "TransactionSuccessful", "txntype": "MANDATE", "corpid": "CUIMOMO1", "mndtid": "12345678901234", "payerid": "110520211929288", "billref": "110520211929288", "txnref": "2400097684", "ref1": "ref1", "ref2": "ref2", "ref3": "ref3", "ref4": "ref4", "ref5": "ref5", "ref6": "ref6", "ref7": "ref7", "ref8": "ref8", "ref9": "ref9", "ref10": "ref10", "date": "09012018230344", "pspid": "PSP123", "ctry": "VN", "ccy": "VND", "strtdt": "01012022", "enddt": "31122022", "payeraccnum": "1234567890", "payerbankcode": "BK123456789", "payername": "John Doe", "sgmnt": "segment1", "payeraccnumtkn": "accToken123", "payeridenttype": "IDType1", "payerident": "ident123", "payeridenttkn": "identToken123", "issurctry": "VN", "issurbin": "BIN123", "isdefault": "Y", "psptkn": "pspToken123", "maxamt": "10000.00", "schedulefreq": "monthly", "corpident": "corpIdent123", "amttype": "fixed", "schedulerelation": "relation1", "scheduleday": "15", "schemetxnref": "schemeTxnRef123", "qrstr": "qrString123", "corpacc": "corpAcc123" }

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<ack>PASS</ack>
<corpid>CUIMOMO1</corpid>
<mandatequery_resp>eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.RyAD2NS_disLVDhk-Ja-2JoMu6SdOMi_E8sIowXRdGP35kOakvTsE8aDcoW3beUfB9UavtXCsyv2vD61J1dDXNP02Qtwoa-JkhXdghLf0TpUgxewayizhJxRrDNcmgTDVw9WL761RDb2RqPuvnkC_iYF4znD9SUZp-DgzL9Ye1CqW9rM9IzhwDS56B4b20e8so9pck0hpMuKF5hE0-lDdsID7UhTTBCeJUE-Uw4feBRAhUGyeUsbWv8b0NX2HxWBu9cVnhirNT4j2yp-tFOfhni8z4C0Z1iHS7Eyo_n8D9xp3JqknaSqRYO3JPtTCRxNVPDQ4jcimm4eRmCzbfdN_g.n_q7WLrjX4pbDUyL.ZifqpUuCKk7wK43Ts453dT0Wcg2H39CYybPTbSUR3IC1zwqc2BZ4Kkf28Tg_zosptBsWvnxIzavix5TmYTk4BXl7tqHXmquTQ7j9f2EQLA1fdR9OJGUgOF0BUs1NKUsR0TGO_4x80f4jpsABdEZZVZHfSUdY2WnZE1zn_3Rtb1xbVVumDRuD3tp_zq8udOWJGv5XZBxyHImK9L3DazwQQcpZjm8bEII9HPuB9s9QRV82OruCKxT7SYF7Msq4DvMpkJdQG4JA_Hqkwx7TclPqBsINTgJT3ONgC5Viubx_4jjZCDjYIZqu0sO9XW3kkTS2Ef16Uw1EUBOIzvy0NRsfvUmRmnh6cMiVC5gxEkJAHAojdas6ajEq0QtoL5KIFh_0Coznc7ykPLpHAC1lCGxeRd7mccdu1yIUQ6nO3Nc-GrXYJMsGhWbHGzXvIpfAi0DbYBM8X0bdPfmKwExoSGa_f_j6KFMUOeOcA33N70qpsUlLPtHRl0BigH0XHQ2SDUoZOVMRNEuonldeIEM9JsBZLLS4kF-l-0VOxaApBVHjZP_c8OAl0_hwbqL1BNRFJZOru80C6cJ26GnZqJO3Rp_4sir_SqeYX2OD1APQgsNmO0Vtowz8LBLO.d4Lr8wKRJEMkgYgIqTWo3Q</mandatequery_resp>
</xml>
							
						

Try it out

Input Fields
corpid
payerid
billref
datetime
pspid
actn
Merchant Keys
AES Key
Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
XML request
JSON request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/mandatequery
Response
Decrypted response

Additional APIs

Straight2Bank Pay offers following APIs that can be utilized irrespective of which integration method is used to initiate the collection request.

JS


Refund

Merchant Server can initiate refund request using this API for PSPs that support refund. Straight2Bank Pay server does the following validation:

  • Refund request can be raised only against a transaction that was successfully authorized by a buyer via Straight2Bank Pay.
  • Refund requested amount should not be greater than the corresponding authorized transaction amount.
  • Multiple refund requests can be initiated, but total amount of all refunds, should not exceed the authorized transaction amount.

Successfully validated refund request will be accepted and queued for processing. For each refund request, Straight2Bank Pay will initiate fund transfer from Merchant's account to internal account, this transfer will be initiated using Merchant's S2B Group ID as like Merchant has initiated Book Transfer (BT) payment to pay internal account. Once funds have been successfully debited from Merchant's account, Straight2Bank Pay will call API of PSP and request for refund to the Buyer. Buyer will be identified based on the reference number of authorized transaction that was initiated by buyer to pay to Merchant.

Straight2Bank Pay accepts the refund request, validates and sends acknowledgment back synchronously. If Merchant Profile is configured to receive real-time notification, then Straight2Bank Pay notifies final status of refund to Merchant's server via API end-point URL that been configured in the profile. Message specification of refund notification is same as described in section Notification Request

In case the notification message does not reach in time or merchant does not want to host API to receive notification, then Merchant can make use of Query API to receive the status of refund. Please refer Query API details in section Query

In case, PSP does not support Refund due to some reason or Buyer has paid using Instant payment method (like QR or RTP), then Straight2Bank Pay offers refund service which initiates outgoing payment via Clearing House to the Beneficiary. If Beneficiary of refund is available in Straight2Bank Pay (as it is received as part collection transaction), then Merchant does not need to provide the Beneficiary data as part of Refund instruction as Straight2Bank Pay uses the buyer name, buyer account number and buyer Bank code as Beneficiary details for the outgoing payment for the initiated refund instruction. In case, S2BPay does not receive the buyer data in collection transaction, then Merchant is expected to send Beneficiary data (creditaccnum, creditbankcode & creditorname) to S2BPay (as part refund instruction) which will be used as Beneficiary in outgoing domestic payment.


Refund Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

Message layer level Security

Request: RS256 Signature , AES-256 encryption

Response: HMAC-SHA256 hashing, AES-256 encryption, RSA2048 Encryption

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/refund

Prod: https://s2bpay.sc.com/s2bpay/refund

Event

Whenever Merchant needs to initiate refund

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 refund_req M X(2000)

Key-value payload needs to be constructed as descripted in next table, then payload needs to be AES-256 CBC encrypted using shared secret key, encrypted string needs to be base64 encoded and populated here.

Refer AES256 encryption/decryption section to view the sample code to perform AES encryption.

The following table lists the key names used to construct the value for 'refund_req' tag. Each key-value pair needs to be concatenated using & (ampersand) character.

Seq Num Key Name M/O/C Type & Length Remarks
P1 corpid M X(8) Corp ID of Merchant.
P2 refundcorpref M X(16) Unique reference of this refund request
P3 amt M N(16,3) Amount to be refunded
P4

txnid/ corpref/ optxnid

C

Reference number to locate earlier collected transaction for which refund is being initiated, either one of the following key values can be used:

txnid - Transaction ID that is assigned by Straight2Bank Pay, Merchant can get this value from notification message.

corpref - Transaction Reference that was assigned by Merchant.

optxnid - Transaction Reference that was assigned by Operator (PSP). Merchant can get this value from notification message.

P5 debitaccnum O X(34)

Merchant's account that needs to be debited to process the refund request.

If no value is provided for this tag, then it will be defaulted to the account that has been configured in profile.

P6 refundvaldt O X(8)

Format: DDMMYYYY

If value date populated is future date, then it will be considered. Otherwise, Straight2Bank Pay will compute the value date based on when collected transaction is credited into Merchant account.

P7 pspid O X(8) PSP id of the transaction
P8 type C X(10)

If any PSP supports both Refund and VOID (same day cancellation), then it is mandatory to be explicitly to be mentioned. Possible value:

  • VOID
  • REFUND
P9 creditaccnum C X(34) Beneficiary Account Number or Beneficiary Proxy to which the fund to be sent. It is mandatory for the PSP for which Straight2Bank Pay does not receive Buyer Account Number from PSP or Clearing House.
P10 creditbankcode C X(11) Beneficiary Bank Code. If Bank Code is mandatory for outgoing payment, then it is not avaialble in Straight2Bank Pay, then it is mandatory.
P11 creditorname C X(70) Beneficiary Name. It is mandatory for the PSP for which Straight2Bank Pay does not receive Buyer Name from PSP or Clearing House.
P12 paytype C X(10) It will indicate either Payment Type or sub-payment-type, coded value. The value will be provided during the implementation if it is applicable.
P13 datetime M X(14)

Datetime stamp of client server

Format: DDMMYYYYHH(24)MMSS (GMT+08:00)

P14 sign M X(200)

Signature of entire key-value pair using Merchant's Private key.

Algorithm to be used : RS256

Refer to Generation of Digital Signature


Refund Response (Straight2Bank Pay to Merchant Server)

Straight2Bank Pay receives Refund Request, decrypts, validates the signature and stores transaction if request is valid, then generates synchronously response and sends back to Merchant.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 ack M X(10) Possible value:
  • PASS
  • FAIL
X2 ackdesc C X(100)

This tag will be populated only if ack is FAIL.

PossibleValues:

  • Invalid Request
  • Error in processing Request
  • Invalid Date time in Request
  • Sign Error
  • Invalid Amount
  • Refund not allowed
X3 corpid C X(8) Corp ID of Merchant.
X4 refund_resp C X(2000)

Key-value payload will constructed as described in section Notification Request, then payload is encrypted (algorithm: AES-256 CBC) using a random key, encrypted string is base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view sample code to perform AES decryption.

X5 enc_key C X(2000)

Random key used to encrypt 'refund_resp' tag is encrypted using Merchant's public key (algorithm: RSA-2048) and populated here.

Refer to RSA 2048 encryption/decryption section to view sample code to perform RSA decryption.

Each key-value pair used to construct payload string for 'refund_resp' tag is concatenated using & (ampersand) character. For ERROR status, following are possible statusdesc values:

  • Transaction not found
  • Refund Amount is greater than Paid Amount
  • refundref already exists
  • No or Multiple values found in refundtxn

Request and Response Samples

Refund Request - Sample Message

clear-text value for 'refund_req' tag:

amt=1&corpid=CN000002&datetime=01092018230815&pspid=SGFDMS01&refundcorpref=0109201811194015&txnid=8000092202&sign=I2gCL1lw7f6pq8g+9uxzwZb1yJgVKjZXRkgLuuqKfse7JLv2kDHhJ723nnemLaqnzERtfADkW1ObRYFXipNeEgvPoL4slGZSITFnw7vmzOYnO6CAb+S9pr44NxrNVWNlTz5ho6rgtsxkCpp35jrhLTlb/pb7yT3pKE9/ZOZV/47hqt+hob1qPs+llkhOG6JxiAADTPXMQ0fYe58G8qDGwTGJnTodJEmd4qe+Ccbyzzbxji9G/hY3hfM7e/Uh8lqor+wdZbkYtpf6RZ25/LoBFIelqqp749R9FoC6P+aOl6RtAsJBW/sdujFQ34EYzK5LBoNov5n8kTt8RHPwtZXDaA==

Sample - XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CN000002</corpid>
<refund_req>RmLPKUiYs8yQW7/CUYBABO0SyKNPrkemhVxG2FtgAh0oir3/Htw9t+WPupgdmicbIBebog/SGvTNeYqvzSLDmGvVCiJNj604FOX65N4f5mTn6OJ+72VOUm+rlzvgC30DspGM49XdZWM6NNuFQ0Q5otvTkF05CxrZLqofR1KVgAK6zwb/JUsS0v/+YPOt27wWYk/YTmXWEtFincEKTTIKLYvuJ2SJ+rVwEUtdTQJj2SK9bDDVPJpdra/IEZITMoISxex0FfdrrduCzYXsrP8EX0/uzERk8+h3d9RJZOULHul+Ft3FBO3lyjVQacYAA/jrxnwU5ThLI8HZtqTyE/7LV2Cv4QHq2LrQ+7TD8m7rIFWmxEArVeoMgA6IIBPlgaYl0l8YhuhGhRfxpAst5gMDVZQkO/Gltvgbye4NWs84zCVZVb9LdW8lX6G/ny+J782YD252fCi6wnNobt/aF1RyOd/rImCf+VhNFiHRZ6gl7bI/7t+otUumra5a2x9Q6knL3zTwzFOZp3KwbLpcWxNETbe/wvksBrrgV9Lh32/PbKUWpZsDnP6tk65fdtrhmTf90xI1jRWiIyjtARYxtTKkSZhbsWhIALMHG29Lv9oQI0A=</refund_req>
</xml>
						

Refund Response - Sample Message

Clear-text value for 'refund_resp' tag for ACCEPTED status:

ack=pass&amt=1.00&ccy=MYR&corpid=CN000002&corpref=8000092202&datetime=01092018230946&optxnid=84516311335&ref1=05062018194017&refundcorpref=0109201811194015&refundtxnid=8000110568&status=ACCEPTED&txnid=8000092202&txntype=REFUND&hash=8DDEA0AE766185B5F31421F5ACBD1FC46E42643F36E6803C3AC1CEA498FF0309

Clear-text value for 'refund_resp' tag for ERROR status:

ack=PASS&corpid=CN000002&datetime=04092018144511&status=ERROR&statusdesc=Refund Amount is greater than Paid Amount&hash=59637D619A1AF291F2CEAE725E70AAF8A05A292108C4BF3B328977460D50F3F6

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<ack>PASS</ack>
<corpid>CN000002</corpid>
<refund_resp>HpBodmPUtt6bBhTK2KAkl01jO6X11Uj6kScr6jBEdNgtoCGsLUPvfT6bl+/L06an/iw0SwduwN0J2MaHYfrfK1n7WNexohDD5Sc9iw4ZEuZWR1krmUmQwFXNgwjmOCFeZzVVW9/+Y1S7Wx+xTxxR7rRSYpUq0/qNxdHEQwhmw0d8kOsEtOeFgK+IibY/9OQZ+BiMPi9DOOChplZFpWKE2ELrNZd4VRYI0GAKseFa0f9uphZ7JfRmGNF7elTWXScyGaiBHsGFWxmzcqvb5aSKPXvGnPAF3wzYT10huM+plPx2/I2yAshGvsXtR2W8VKVeufmPSEJynGLTAUUXmFu9n7FqtbGi4hXYF/39I9W3AzlvsbBQqhHM6Ed2hNBMNnq2</refund_resp>
<enc_key>W5M1G6BDJGlTEgFOcIrdsb3GN/WHjf4A8v5vewXnVwpFJQzfDnGiPVFwIqS3H3bQMrUXvERmWSgaT2vBdU+btvwPQtssFqiiT3c/IGBeLtgEJ9YXmBlf/kacF6MG5tN6ghpg4BKsFT7jB5Cdnrmi+RchtMZxqBO4v0nXxOkHiUif+ooWC8O0HLaEPIluTxCdo9AhJaFj60XW+2YKQnWcAwKSiEf1aWL3P+bjycgS/TUZQbnf/1m1XPl8P9GXm4Kovu+xiLlFLnhS4LZ8W9hisVv1mM6hwV5Kr0rlAuo0Fa8oUbUI26k/rA+8KmymuGFeJLgiFRb3G+CpS5jiqnMGtA==</enc_key>
</xml>
						
For FAIL acknowledgment
								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<ack>FAIL</ack>
<ackdesc>Sign Error</ackdesc>
</xml>
							

Try it out

Input Fields
corpid
refundcorpref
amt
txnid
corpref
optxnid
datetime
Merchant Keys
AES Key
Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
XML request
JSON request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/refund
Response
Decrypted response

PostAuth

This API is mandatory for UAE PGS payment method to confirm that the delivery is completed and request for the settlement.

For credit card payment method in certain countries, Merchant Profile can be configured to get pre-authorization from the buyer as part of user journey. After pre-authorization, Merchant is expected to call this API to send Post Authorization request with the final amount to be billed to the buyer, this amount should equal or less than the pre-authorized amount by the buyer.


PostAuth Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

Security Algorithm

Request: RS256 Signature , AES-256 encryption

Response: HMAC-SHA256 hashing, AES-256 encryption, RSA2048 Encryption

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/postauth

Prod: https://s2bpay.sc.com/s2bpay/postauth

Event

Whenever Merchant wants to charge the final amount to Buyer's Card.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant
X2 postauth_req M X(2000)

Key-value payload needs to be constructed as described in next table, then payload needs to be AES-256 CBC encrypted using shared secret key, encrypted string needs to be base64 encoded and populated here.

Refer AES256 encryption/decryption section to view the sample code to perform AES encryption.

The following table lists the key names used to construct the value for 'postauth_req' tag. Each key-value pair needs to be concatenated using & (ampersand) character.

Seq Num Key Name M/O/C Type & Length Remarks
P1 corpid M X(8) Corp ID of Merchant.
P2 postauthref O X(16) reference of this postauth request
P3 amt M N(16,3) Final Amount to be charged to the card.
P4 txnid / corpref / optxnid C X(75)

Reference number to locate earlier pre-authorized transaction for which postauth is being initiated, either one of the following key value can be used:

txnid - Transaction ID that is assigned by Straight2Bank Pay, Merchant can get this value from notification message.

corpref - Transaction Reference that was assigned by Merchant.

optxnid - Transaction Reference that was assigned by Operator (PSP). Merchant can get this value from notification message.

P5 pspid M X(8) PSP id of the transaction
P6 datetime M X(14)

Datetime stamp of client server in HKT

Format: DDMMYYYYHH(24)MMSS (GMT+08:00)

P7 sign M X(200)

Signature of entire key-value pair string using Merchant's Private key.

Algorithm to be used : RS256

Refer to Generation of Digital Signature


PostAuth Response (Straight2Bank Pay to Merchant Server)

Straight2Bank Pay receives PostAuth Request, decrypts, validates the signature and stores transaction if request is valid, then generates synchronously response and sends back to Merchant.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 ack M X(10)

Possible Value

  • PASS
  • FAIL
X2 ackdesc C X(100)

This tag will be populated only if ack is FAIL.

Possible error description:

  • Invalid Request
  • Error in processing Request
  • Invalid Date time in Request
  • Sign Error
  • Invalid Corporate Id
  • Invalid Amount
  • Currency code invalid
  • Unique id invalid
  • Invalid psp id
X3 corpid C X(8) Corp ID of Merchant.
X4 postauth_resp C X(2000)

Key-value payload will constructed as described in section Notification Request, then payload is encrypted (algorithm: AES-256 CBC) using a random key, encrypted string is base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view sample code to perform AES decryption.

X5 enc_key C X(2000)

Random key used to encrypt 'postauth_resp' tag is encrypted using Merchant’s public key (algorithm: RSA-2048) and populated here.

Refer to RSA 2048 encryption/decryption section to view sample code to perform RSA decryption.

Each key-value pair used to construct payload string for 'postauth_resp' tag is concatenated using & (ampersand) character. For ERROR status, following are possible statusdesc values:

  • Transaction not found
  • Postauth Amount is greater than User Authorized Amount

Request and Response Samples

PostAuth Request - Sample Message

Clear-text value for 'postauth_req' tag:

amt=1&corpid=CN000002&date=18092018195916&postauthref=18092018094616&pspid=SGFDMS01&txnid=9999999999&sign=JnngPZwX4B+Hv54FN4mF2M06O+37uZvRU1t4+rMenYViYwJJn8DO6vIqBNsEllJiU9n7fBONqkGMN6PRVa3svMtJxOFWRRmzxSHJ8QYPCwx1Woi6l7DqOyUboOj/xalCwHvp7TXhxTzywtTWFSUTV+AqM0RSe7f0UVlDMPhC9vLVOq2Ytk9sBDrEqTjNRJ+QKYBjNbNJlm3G8D7/l2ouXo8YpjmXrE8FASQeNHHQHNhZJIq9wzSKLetH0Qsm8VJne37XTlK9JZywhXVmEVJ6l8CNb60vunc5PiYjo7zPvVD7skSdF5fqx3CblxIgGLOm0AZ3BxXMlVx5yq3BbldyEg==

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CN000002</corpid>
<postauth_req>RmLPKUiYs8yQW7/CUYBABFECc7u3nnrpdbXo1Ieqgjfwj7mnBRKhLw38DOZOIHEmZ1uKH28bDT5lXyFRJ1mFbXIakDO14D5uTbr2Fhbw7MdYtq0G0Jq9EC2cwKuKEM/QCCuW5j85jd9IlRkFN2gmiRHNvLMuvfZPQuRTU7cJ2t2/Tvb6s+wkExwxXhOB8JPXvQD87NgE30CIfEyqQnRxis5IyIHLtuC9RBxkRzpk+gCuWDobANFT3maZwf/r4RhPyCHl3e5METUkqAp+Fm7gXhDPOLVoA+9f1rfpYYLcNwySwab986QzPcZnV4OPT5ygENV3kdxxR5hLYnA/nQAhsKHpWJm6F5/gBLoRS/MWCD9Y/a8Wpkj/isYazmXDkxvxZPC3kQekfRyfOQo7SCxdcpp/D+4kkb40OF5/GNuI9GbYfHk/br8o0KFnqhPeAyxWELRi1MHSYdC1xORYCUg9dXvnmx0dbTZy3Iw82rozO8r92TEAmDAKe+qEm6zB/5/J9e8MPuaPWs0czZ/nY4Hl4BJRrE3jKPP4WoLyPJe++b3f2xHzdvjTzGaDM6NT7DNtCL3sRqsk3lLLlyLqnSA3fTAuK/+7/JZ604DgEJllhNI=</postauth_req>
</xml>
						

PostAuth Response - Sample Message

Clear-text value for 'postauth_resp' tag for SUCCESS status:

ack=PASS&amt=1&ccy=SGD&corpid=CN000002&corpref=8000000923&ctry=SG&date=26072018194519&optxnid=84518647137&ref1=45778&status=SUCCESS&txnid=8000000923&txntype=NEW&hash=A792872638828316BD214C4BE30521B6EEFB6C6330F3AE5E85D84FCFD085A230

Clear-text value for 'postauth_resp' tag for ERROR status:

ack=PASS&corpid=CN000002&date=19092018122858&status=ERROR&statusdesc=Transaction Not Found&hash=051A6A8D5AA834098121A93FB42BC5247E9996A6B93730091A9419B032C1339E

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CN000002</corpid>
<postauth_resp>EIT+JOdgtmuwPCEf7aNhIS4RfAC+rgoHRUzFfaOqrXiU/0elJIhlW1CHrStDY/dRHsAk43JQ0Nz0nkt/Q9u/N/7Ro9o3z4PFaJsCvghLp9e/5FFTvyKiJ6PKHhAVnvjTJmZyrSEn9LYACA8k/O9H0AkVg9t/rGgg4RTVRTbBQABask5Ds2ZZcJRud2mseRx68qD4mJypPrvnCSAUQCQpHKjaIFkxMYHmoTK4SXJ+Vu1+ZT/FsBNPbhF7MHVnM8HLlRqqVjuvlFvGRfPa/tP4NfHfTufTfLi+qFgmqluD0d1kxR40sEp/uYYa/f9dG71l</postauth_resp>
<enc_key>dNZJ9ExVM00EIInY9cdwSWNf1vzb0YiTCyUhkzM1nftYB6iWBWD4wj/riBzmjYKLsGq+LWoinTl8PcjXrxj+0Ut6+FL+So5ddiRJBqCGEuyWtfq7Xkz6mtqOZ+IlI5vwx85IHg5R8x8wmsLRu+BYuKFIXkTbaThfePElwkfypUzYIY2Y5udaCku7BNYmfucROEfxGcfcQR4y0/Qwih/IUAbXmMQDrbjH4aege7BvTCz7osnH/VlJHpIbARKxu/MLw80jAGjb23Gvftw54fUI88QVOLGjyBcuygygZwt0DoIp8uYmzZRK4TX5iQYotafp09fPyAR/g7wcCumtVQBYNA==</enc_key>
</xml>
						
For FAIL acknowledgment
								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<ack>FAIL</ack>
<ackdesc>Sign Error</ackdesc>
</xml>
							

Try it out

Input Fields
corpid
postauthref
amt
txnid
corpref
optxnid
datetime
pspid
Merchant Keys
AES Key
Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
XML request
JSON request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/postauth
Response
Decrypted response

TxnReport

This API provides a list of transactions for any day. It is recommended to make use of this API only if number of transaction is less than or equal to 1000. For more than 1000 transactions, Merchant can get the report from Straight2Bank Pay via SFTP server or via eMail, Merchant can download the report from Bank's SFTP server and Straight2Bank Pay can push the files to Merchant's SFTP server.


TxnReport Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

Security Algorithm

Request: RS256 Signature , AES-256 encryption

Response: HMAC-SHA256 hashing, AES-256 encryption, RSA2048 Encryption

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/txnreport

Prod: https://s2bpay.sc.com/s2bpay/txnreport

Event

Once in a day.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant.
X2 txnrpt_req M X(2000)

Key-value payload needs to be constructed as descripted in next table, then payload needs to be AES-256 CBC encrypted using shared secret key, encrypted string needs to be base64 encoded and populated here.

Refer AES256 encryption/decryption section to view the sample code to perform AES encryption.

The following table lists the key names used to construct the value for 'txnrpt_req' tag. Each key-value pair needs to be concatenated using & (ampersand) character.

Seq Num Key Name M/O/C Type & Length Remarks
P1 corpid M X(8) Corp ID of Merchant.
P2 apiref M X(16) reference of this txnreport request
P3 fltrreqdate M X(8)

Date for which report is requested

Format: DDMMYYYY

P4 fltrstatus O X(25)

Status of the transaction to be filtered

For NEW Transaction

  • SUCCESSFUL
  • UNSUCCESSFUL
  • PENDING
  • CREDITED

For REFUND Transaction:

  • SUCCESSFUL
  • FAILED
  • PENDING
P7 fltrtxntype O X(10)

Type of the transaction.

Valid Values:

  • NEW
  • REFUND
P8 fltrpspid O X(8)

PSP for which report is needed. PSP ID to be obtained from Implementation Manager.

P9 datetime M X(14)

Datetime stamp of client server

Format: DDMMYYYYHH(24)MMSS (GMT+08:00)

P10 sign M X(200)

Signature of entire key-value pair string using Merchant's Private key. Algorithm to be used : RS256

Refer to Generation of Digital Signature


TxnReport Response (Straight2Bank Pay to Merchant Server)

Straight2Bank Pay receives TxnReport Request, decrypts, validates the signature, then generates synchronously response and sends back to Merchant.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 ack M X(10)

Possible Value

  • PASS
  • FAIL
X2 ackdesc O X(100)

This tag will be populated only if ack is FAIL.

Possible error description:

  • Invalid Request
  • Error in processing Request
  • Invalid Date time in Request
  • Sign Error
  • Invalid Corporate Id
X3 corpid M X(8) Corp ID of Merchant.
X4 apiref M X(16) Echoed from Request message
X5 datetime M X(14)

Date & time

Format: DDMMYYYYHH(24)MMSS (GMT+08:00)

X4 txnrpt_resp M X(30K)

Key-value payload will be constructed as described in the next table then payload is encrypted (algorithm: AES-256 CBC) using a random key, encrypted string is base64 encoded and populated here.

Refer to AES256 encryption/decryption section to view sample code to perform AES decryption.

X5 enc_key M X(2000)

Random key used to encrypt 'txnrpt_resp' tag is encrypted using Merchant's public key (algorithm: RSA-2048) and populated here.

Refer to RSA 2048 encryption/decryption section to view sample code to perform RSA decryption.

The following table lists the tag names used to construct the value for 'txnrpt_resp' tag, the format of the payload will be same as the format of the request message, it will be either XML or JSON.

Seq Num Key Name M/O/C Type & Length Remarks
P1 status M X(10) Status of the Transaction
P2 statusdesc O X(100) This tag will be returned only if a status description is present
P3 txntype M X(20)

Possible value:

  • NEW
  • REFUND
P4 corpid M X(8) Corp ID of Merchant
P5 amt M N(16,3) 13 integer digits and a precision of 2 decimals
P6 ccy M X(3) 3 character currency code
P7 ctry M X(2) 2 character country code
P8 ref1 O X(100) Reference Number 1
P9 ref2 O X(100) Reference Number 2
P10 ref3 O X(100) Reference Number 3
P11 ref4 O X(100) Reference Number 4
P12 ref5 O X(100) Reference Number 5
P13 corpref O X(16) The unique ref value of NEW Transaction
P14 refundcorpref O X(16) The unique ref value of REFUND Transaction
P15 txnid M X(16) Straight2Bank Pay generated unique transaction ID for this NEW transaction.
P16 refundtxnid O X(16) Straight2Bank Pay generated unique transaction ID for this REFUND transaction.
P17 optxnid O X(75) PSP assinged Transaction ID for NEW Transaction
P18 refundoptxnid O X(75) PSP assinged Transaction ID for REFUND Transaction
P19 pspid M X(8)

Not Applicable for 'collect' API response.

PSP ID (indicates payment method). Eg: BDSSLNET, BDSSLCRD, BDSSLNET, SGPAYNOW, HKFPSHKD.

PSP IDs to be obtained from Implementation Manager.

P20 payername O X(256)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Payer Name. It can be inlcuded on this notifcation message.

It is not applicable for all payment methods.

P21 payeraccnum O X(34)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Payer Account Numbe. It can be inlcuded on this notifcation message if regulator rule allows.

It is not applicable for all payment methods.

P22 payerbankcode O X(50)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Payer Bank Code. It can be inlcuded on this notifcation message.

It is not applicable for all payment methods.

P23 payerident O X(50)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Payer's identity (like mobile number). It can be inlcuded on this notifcation message if regulator rule allows.

It is not applicable for all payment methods.

P24 corpident O X(50)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Merchant's identity (like Biller ID, VPA). It can be included on this notification message.

It is not applicable for all payment methods.

P25 authcode O X(70)

Not Applicable for 'collect' API response.

For certain payment methods, S2BPay receives the Authorization Code. It can be inlcuded on this notifcation message.

It is not applicable for all payment methods.

P26 gstamt O N(16,3)

Applicable only for Txn Report response

GST amount applicable for that transaction. Applicable only for certain payment methods

P27 taxamt O N(16,3)

Applicable only for Txn Report response

GST amount applicable for that transaction. Applicable only for certain payment methods

P28 chrgamt O N(16,3)

Applicable only for Txn Report response

Charge amount applicable for that transaction. Applicable only for certain payment methods

P29 netamt O N(16,3)

Applicable only for Txn Report response

Net amount that is settled for that transaction. Applicable only for certain payment methods

P30 totalchrgamt O N(16,3)

Applicable only for Txn Report response

Total charge amount applicable for that transaction. Applicable only for certain payment methods

P31 settlementdate O X(8)

Applicable only for Txn Report response

Date on which this transaction will be settled. Format: DDMMYYYY

P32 datetime M X(14)

Datetime stamp when the transaction is made

Format: DDMMYYYYHH(24)MMSS (GMT+08:00)


Request and Response Samples

TxnReport Request - Sample Message

Clear-text value for 'txnrpt_req' tag:

apiref=9999999991&corpid=CN000002&datetime=18012019141850&fltrreqdate=18012019&fltrpspid=INBILDSK &fltrstatus=SUCCESSFUL&fltrtxntype=NEW&sign=VnIx2rBHfDSPh7vj5iJTwughxVono3MHHyWGbWbpFacdKQSvIS4Vg6oF/fuvos6hVaPAcfjvW39kUR6D1AenMFRWMz8KxlOLwps3uRicZMS9JvcMFRowI99hgHJidq3tQo5FKGbsB1wtAE645mQgziTIWS63UrN32pRzAEfX2QXwGWerk2Hub37zyKOmQa2mMzdMIZdoANbCo5+fD+F/4ArGJPyM9hIFFRmogbF6gUaOQSqmTmXtiYMmV3DxemCMd7KogK3PBDDJ9Ttz9StCWRkFks04Z83v4t92vVug2Eqpx6YXK361Vss0RGLIh+djHj5LkTxjQEEGJgA2oqa86g==

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<corpid>CN000002</corpid>
<txnrpt_req>WNU3YqSl7LFF6/gvel+TmE8c0nQXSAxuA1QrItwVBK+WPF8YjPocQFXg8tZF7PuwsxRt/VrIBsmt2xxcQGiMQebKL1UbO3FP6QsHSHoFetBVi8xwf/1B1mXt4tUoCcPE7hH4frPvRB7xEPXU7kPIhkZWmm103Ko3HoL3uue7mbjuZCnjyrvg40Rj39t4pAWRO+CxhQYdVnW+vtaQ1BNfNV5ZoX7fFQMaGwEUANHn5Xp4hjPQ/8D9meKUVD8iZlOWWhPYJn8/z7NUi9UgJhVwvgu3NBRIA7Hn3GySzrcKmNKYvTReihW82TmWWdK2Nv++G4+hR8N9/YWVVUhYioestUrjnbp36pikFK0nmxJUwTB2uqTiHReCDm3g4GdiGupdEUvqEDjo6BvvMAlaZwNZzypMBEQGp5GUWY0vATOoqy0nAW38eFkd0b/j7ZyjfYJxwBxcuSfGqVnlbtESX1kyZH+T68iHA8f1WFO01mxJ23Gv5EtLDfWiIardSFWcZ5GQr80TFF4WEMvtu/UoGq82JTZNiSLt8bY58H7V2rqW1+Hzfw6DKO3MkOt0T4yepXrMwtO7pe5/FzQbOUCcANiaq87laFRDgfCnfLizHIy8sQI=</txnrpt_req>
</xml>
						

TxnReport Response - Sample Message

Clear-text value for 'txnrpt_resp':
								<txn>
<status>CREDITED</status>
<statusdesc>Credited</statusdesc>
<txntype>NEW</txntype>
<amt>47458.95</amt>
<ccy>INR</ccy>
<ctry>IN</ctry>
<ref1>Bala1234</ref1>
<corpref>Bala1234</corpref>
<txnid>9000114698</txnid>
<optxnid>13123599</optxnid>
<psp_id>INBILDSK</psp_id>
<gstamt>3.24</gstamt>
<chrgamt>18</chrgamt>
<netamt>47437.71</netamt>
<totalchrgamt>21.24</totalchrgamt>
<settlementdate>17022023</settlementdate>
<datetime>18012019141323</datetime>
</txn>
						

XML message:

								<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
<ack>PASS</ack>
<corpid>CN000002</corpid>
<apiref>9999999991</apiref>
<datetime>18012019141904</datetime>
<txnrpt_resp>islpieDY3b2az09FG7i1gkuVMokr3mAck7tdT9sVKiaaoowztOV4nFEN8pDlJgOjtjwMcSqK2H0HxZpqKhQTJQKxw0wa/ix9x0QAYR2d1Hypmbb0PAJbZcoexCnA2hmAcX8hWF0By8hQSAWYUuscS3snOW26yKFrQFTNdXy4MEuiuVRgXCTz732GJbElVL1B8I2UOHjtaLKYwECg3uR005nJ1cQwqw227qoz+fo2/wulU6oisI7QzstqVknyR1V54fipdVnx5rT7tsmMBDsxJqpscLpHvKQFPqzAcpHqpVxIBRkzv0RWF4pa8aY9j5fdjLRCZ87j9FbfL/GlJ/igVBFJIAWq8/S1n1jIHEDUoADEWwNN3FyUHXsI4haWJspKeb4N/a05T5GXiDtrGQvK68v/Pf0XepA+KppsZVnWv8A3nQTATWZBaWHAPF/L16gJ6+lrf6L+uAWSh7kS+AAnoDC5vYUgSrnGZ0AY/WWQRv1USTjTv8vS+pm7vw+BJawzhU0uLYTBmb1RUPtUVpmjnE1eWLushwAM0PGwhZ/CLPjQT981IHQpXMeivRnm7nPkn71gpboSoBnRRK7rrjKWntRSpQeFFb3ThswRavitDWcGLHHtD9FoxZBnQgoxvipVI4kpSKtDoZ0PrJtRu12ahAL7ZzR9SDvKNBDbU9gut3CKeMHaGmiVP/fpSWzMy9n9+u2FYcmhZBcriM3VRpgw4bEvAwk+9qr5cFsQDdmrFNwHQxz2NPgBh7ZcjjIPAjQUK1uL9M/k1DRCPGmssGAT0bJCFcK++oe6z7AWGCECW6qGwLiT7M1VwfZcawXjq+gPlmCvUCOPL0cGAs0mxlVRB3yr4QC6vY/vPEby5VEWkg/6oSHcE0sC9CAlaTf/ZX+7C11M0t2qMUC4iu1D41swAxfSfYMnMYhc6cDb2CTqyP65prAuKEWlDlQ9Mt98bRD13JqLtdkVY0LG2PBBWDiWg0DrSN0IlAvMAb8VBLEyMATM30TRozEEKBC5p8OdjNSxs31Gr5KrNgpkQ5urNkVrunvzGvAvIcj2CIe1R0T9qV3iWSeV9AIiciB4mYW02Ry5DpXW/M7MccbLef8NQekukY9suc9PDz+/GtNKd1atPnkN51SNSACK7jtDNCk1sxFsuPidzpWO2JYJx2kHmZr8YzSH4qOQj2cRgxOTQ0cKdzljCdllrWI77j95xncGiw6pTnQDSfh+iYWWpcR7wSFIx5J7lT3UPk74HylNFWNJgY/4xH24h+LipEDUvv/8IG/XXZuCKH+4EMpCAYp7aQvQR6XFRgoSAtSoVhu2fCp4LCBFoBtoiL6dfsku4BveG/Q38FsM/JAx6JXb2LhwxI5bJZdhZm9W66Jm8+y+Rb48MVJdsY77UL0LAx3jQyhj5V9EFKadsfLXlMnTZHtATDAwObxsOjnnpwmXHaNmtWjtADOLVTKSn71hDqYu297kf6y9t4I5g98zQwuP4YS6ZlRag0QNkcINdn4lIS1YWOqmWp/uomHC7MLUz2/VVhjHTx+EZNE7pdVtGF7K1GUcdSKCQ+juMvX5sdOYXXEbRIf3FABvIpI1Ak5RZJXIE3c2QLBafNKXVMp67yVke2RVCgY6R+XI0lzkOeWuCn33SMWtOoKlv/N3dszZ42JuwQJk/MpVs8fKlAXUoWB2dfNHUpol30jYBf1GS7/wIEQIwvRLIzYPgo9ksnsui6GX0/Qnl7JtmRSuQFa1uSVS8yxzjodqCU+rxoukc1L7IsJ7pA2b/FQ94O3wTEgKr/AP5aWxu0tkAzIWMPRNsYkYHmGn48x2y5apRNyRvOXPGUtG5GYPjEk+4QopWEU+GypBlJXVpplpbEGubjdB0wdoebyLIry+rZPxpFvcprJIu4zeieOJ8LK9OnBcLxZDT6Ua10JqLX5SSScjk+6p2+Y24bMKhJTunQB9tiUV4YyYPZLfMYDFuU+6W8Mw7VjHVDj9ovsilTqkWZW6uQ+6vWGfxm9hA2+EvVfi5FhI6e/BQ8Grsz/AKO8OJ6rXp/YkSUy5S2amCPJzIA6Su0l0S5/45kxBR+mVQhvwa0Zwm6W8aKH1/Q4WjDyZ26JV3Y3Qx5DS3YqVVgF9T5NYNffiV42ieUyC3zjqGzovkoOhkNWeKAVevtSWI/uwWcPttawgWN2bYceZtp21PRPvYyNXI+WPfqIoxBnU605Hk1Ya2UGKQO/1TOZmhMwOhYZFS4WAr0Tft6VYxjBbVsho0nCRizQI+J7KYiGpytPEwFVaGwRrP6wCjCHGwezfCbUowK4vJ7U4UsIJni4ZfHzkBPfkAJLMonTSLwNOGciEEBlOI96oS8/VxZh04ElQjSMiq3dVgRYCQvAeL8uC7IJiOZiVrEJpmvBc9VhNc3CdLF5b3j05QzlJI3GGKhHPBfIoC6Oj/Jxr/fNaI3QjuyO223yieC08Suw2Bqc3z4Ud8msU/Ah2zgxlV1kAZEY+o49NfxAazXbSnPTRKv/c7PLE5MtKaljswlV8z8plpVkUkMwoERldoTv7atxZxrTlPlMbi48e0kVFIbwxN4W7mvjKINgWve3E5mchXRjixwguYqIaGCX1hWFzVfFAGlPKij/yDCz3OAKUgYo61diI</txnrpt_resp>
<enc_key>F/kYBr1xfhyKIm5seGtabcp20iex2QfCdKEJ+OFn0woPIPk8boLKfqBC53Kojh8NYETgKEOc612OozzJS5KFxVxFJJn/HlWTMloRxfCB825bpYK/cujEw1zBVAxPlQR83U0LDq+0RZljwGMz6++vBHgN6dFl0Jfw0giBhTus3V9+BI6zbeR6gkJZDAI35ztJ8bxaFwNYiLAK2ID8npBQtmFzATbBvFlchule1NN499FV7mf5eKefgB/E3Qchv4SkSGAeXBSOo07KTUEKPkOSpc70gXqBg+cQ/3KxBhCVP/sSDpwVWmQHA1JRTKnrEZteXp0PPpnmxeVXcWeDMqgijQ==</enc_key>
</xml>
						

Try it out

Input Fields
corpid
apiref
fltrreqdate
datetime
fltrstatus
fltrtxntype
Merchant Keys
AES Key
Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
XML request
JSON request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/txnreport
Response
Decrypted response

Banklist API

If Merchant uses Re-direct Integration, wants to avoid Straigh2Bank Pay UI (User interface) and payment method expects to show the Bank List for the buyer to choose, then Merchant can call this API to get the list of Bank supported for the such payment Method (like FPX for Malaysia, NetBanking for Indonesia, etc) and present in Merchant's UI.


Banklist Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

Security Algorithm

Request and Response: JWE String (RS-256 Sign, AES-256 GCM encryption)

SCB RSA Public Key: https://test-s2bpay.sc.com/s2bpaysit/devguide#idocs_pubkey

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/getbanklist

Prod: https://s2bpay.sc.com/s2bpay/getbanklist

Event

Whenever Merchant needs to get the Bank lists from S2BPAY

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant.
X2 banklist_req M X(2000)

This tag can either contain JWE string / AES-256 encrypted string as BAU.

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table - JWS String

The following tables lists the details used to construct the value for 'banklist_req' tag.

JWE String

JWE Component Value
JWE Header

Base64URL encode (UTF8(JSON value))

{"enc":"A256GCM","alg":"RSA-OAEP-256"}

JWE encrypted Key Generate a random key(32 chars). Encrypt the random key with SCB Public key using RSA-2048 algorithm
Initialization Vector Generate a 12 byte IV string used for GCM encryption
Ciphertext

Form the JWS String with Header.Payload.Signature format explain in next table.

Encrypt the JWS string with random key generated using AES-256 GCM algorithm and populate in Ciphertext.

Authentication Tag Authentication tags returned in GCM algorithm

JWS String

JWS Component Value
JWS Header

Base64URL encode (UTF8(JSON value))

{"alg":"RS256","typ":"JWT"}

JWS Payload

Payload is base-64 encoded JSON string.

JWS Signature

Sign generated for Header.Payload using RS256 algorithm with Sender's Private key

The value will be validated at receiver's end

Payload Attributes

Key Name M/O/C Type & Length Remarks
corpid M X(8) Corp ID of Merchant
pspid M X(8)

PSP for which Bank list is requested

EG: FPX Retail PSP ID: MYFPXB2C

datetime M N(14)

Format: DDMMYYYYHH(24)MMSS (GMT+08:00)

The encrypted string is valid only for 5 minutes from the created time.


Banklist Response (Straight2Bank Pay to Merchant Server)

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 ack M X(10)

Possible Value

  • PASS
  • FAIL
X2 ackdesc O X(100)

This tag will be populated only if ack is FAIL.

X3 corpid C X(8)

Corp ID of Merchant.

Present only when ack=PASS

X4 banklist_resp C X(2000)

Present only when ack = PASS

JWE format string which contains this following parts separated by .(dot).

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table:

The following table lists the tag names used to construct the value for 'banklist_resp' tag.

JWE String

JWE Component Value
JWE Header

Base64URL encode (UTF8(JSON value))

{"enc":"A256GCM","alg":"RSA-OAEP-256"}

JWE encrypted Key Random key is encrypted with Merchant's public key. Decrypt it using Merchant's private key
Initialization Vector 12 byte IV string used for GCM decryption
Ciphertext

JWS String with Header.Payload.Signature format explain in next table.

Decrypt it with the Random key

Authentication Tag Authentication tags returned in GCM algorithm

JWS String

JWS Component Value
JWS Header

Base64URL encode (UTF8(JSON value))

{"alg":"RS256","typ":"JWT"}

JWS Payload

Payload is Base-64 encoded JSON string with attributes in next table

JWS Signature

Sign generated for Header.Payload using RS256 algorithm with Sender's Private key

The value will be validated at receiver's end

Payload Attributes

Key Name M/O/C Type & Length Remarks
corpid M X(8) Corp ID of Merchant
pspid M X(8) PSP for which Bank list is requested
datetime M N(14) Current date time in HKT
banklist M JSON Array JSON Array with the following fields
Key Name M/O/C Type & Length Value
bankcode M X(100) Bank code given by PSP
bankname M X(100) Bank name given by PSP
status O X(20)

Possible values

active,inactive

segment O X(20)

Applicable only for specific PSP

Possible values

retail, corporate

Not applicable for FPX

productcode O X(50)

Applicable only for specific PSP

Not applicable for FPX

url O X(200)

Bank URL to redirect the user

Not applicable for FPX

browserversion O X(200)

Browser version supported for this bank

Not applicable for FPX

androidappid O X(200)

Android app ID for the Bank's app

Not applicable for FPX

iosappid O X(200)

IOS app ID for Bank's app

Not applicable for FPX


Request and Response Samples

Banklist Request - Sample Message

Clear-text value for JWS payload of 'banklist_req' tag:

Message:

								{"corpid":"CN000002","pspid":"MYFPXB2C","datetime":"14052022093000"}
						

Banklist Response - Sample Message

Clear-text value for JWS payload of 'banklist_resp' tag:
								{"corpid":"CN000002",
 "pspid":"MYFPXB2C",
 "datetime":"14052022093000",
 "banklist":[{"bankcode":"ABB0233","bankname":"Affin Bank", "status":"active"},
	    {"bankcode":"AMBB0209","bankname":"AmBank", "status":"inactive"}]
}
						

Create Party

This API is applicable for Master Merchant. Master Merchant can utilize this API to submit the details of sub-Merchant. For Singapore, this API also serves to create UEN Proxy for each sub-merchant with the display name of both Master Merchant and sub-Merchant name together. For Malaysia, Straight2Bank Pay uses the sub-merchant details for regulatory reporting.


Create Party Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

API Name

Create Party

Source

Corporate client

Destination

S2BPAY

Message layer level Security

Request and Response: JWE String (RS-256 Sign, AES-256 GCM encryption)

SCB RSA Public Key: https://test-s2bpay.sc.com/s2bpaysit/devguide#idocs_pubkey

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/createparty

Prod: https://s2bpay.sc.com/s2bpay/createparty

Event

Whenever Corporate wants to create SubCorpId

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant.
X2 createparty_req M X(2000)

This tag contains JWE String

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table - JWS String

The following tables lists the details used to construct the value for 'createparty_req' tag.

JWE String

JWE Component Value
JWE Header

Base64URL encode (UTF8(JSON value))

{"enc":"A256GCM","alg":"RSA-OAEP-256"}

JWE encrypted Key Generate a random key(32 chars). Encrypt the random key with SCB Public key using RSA-2048 algorithm
Initialization Vector Generate a 12 byte IV string used for GCM encryption
Ciphertext

Form the JWS String with Header.Payload.Signature format explain in next table.

Encrypt the JWS string with random key generated using AES-256 GCM algorithm and populate in Ciphertext.

Authentication Tag Authentication tags returned in GCM algorithm

JWS String

JWS Component Value
JWS Header

Base64URL encode (UTF8(JSON value))

{"alg":"RS256","typ":"JWT"}

JWS Payload Payload is base-64 encoded JSON string with attributes in next table
JWS Signature

Sign generated for Header.Payload using RS256 algorithm with Sender's Private key

The value will be validated at receiver's end

Payload Attributes

Key Name M/O/C Type & Length Remarks
corpid M X(8) Corp ID of Merchant
subcorpid M X(50)

subcorpid value given by merchant

the value to be URL encoded if having &=

subcorpname M X(70)

name of sub corporate

the value to be URL encoded if having &=

subcorpnamell O X(70) name of sub corporate in local language
shortname O X(70)

Alias name for sub corporate

the value to be URL encoded if having &=

subcorpidproxy C X(50)

Mandatory for Singapore.

specify the suffix value to be used with for PROXY

country M X(2) country code
mcc O X(4) Merchant category code
pspid M X(8) PSPid for which subcorpid to be created
bizregnum O X(100)

Business Registration Number

the value to be URL encoded if having &=

remark O X(200)

Description field

the value to be URL encoded if having &=

datetime M N(14)

Format: DDMMYYYYHH(24)MMSS (GMT+08:00)

The encrypted string is valid only for 5 minutes from the created time.


Create Party Response (Straight2Bank Pay to Merchant Server)

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 ack M X(10)

Possible Value

  • PASS
  • FAIL
X2 ackdesc O X(100)

This tag will be populated only if ack is FAIL.

X3 corpid C X(8)

Corp ID of Merchant.

Present only when ack=PASS

X4 createparty_resp C X(2000)

Present only when ack = PASS

JWE format string which contains this following parts separated by .(dot).

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table:

The following tables lists the details used to construct the value for 'createparty_resp' tag.

JWE String

JWE Component Value
JWE Header

Base64URL encode (UTF8(JSON value))

{"enc":"A256GCM","alg":"RSA-OAEP-256"}

JWE encrypted Key Random key is encrypted with Merchant's public key. Decrypt it using Merchant's private key
Initialization Vector Generate a 12 byte IV string used for GCM encryption
Ciphertext

JWS String with Header.Payload.Signature format explain in next table.

Decrypt it with the Random key

Authentication Tag Authentication tags returned in GCM algorithm

JWS String

JWS Component Value
JWS Header

Base64URL encode (UTF8(JSON value))

{"alg":"RS256","typ":"JWT"}

JWS Payload Payload is base-64 encoded JSON string with attributes in next table
JWS Signature

Sign generated for Header.Payload using RS256 algorithm with S2BPAY's Private key

The value will be validated at receiver's end using S2BPAY's public key

Payload Attributes

Key Name M/O/C Type & Length Remarks
corpid M X(8) Corp ID of Merchant
subcorpid M X(50)

subcorpid value given by merchant

the value to be URL encoded if having &=

subcorpname M X(70)

name of sub corporate

the value to be URL encoded if having &=

subcorpidproxy C X(50) Value given by merchant
country M X(2) country code
pspid M X(8) PSPid for which subcorpid to be created
partyseqnum O N(14) Straight2Bank Pay generated unique ID for this Proxy entry
deleteflag M X(1)

Indicates whether this subcorpid is deleted/not

Possible values: Y/N

Default value : N

status M X(20)

Possible values:

ACCEPTED

FAIL

SUCCESS (only for PSPs where proxy creation is not required like MY)

statusdesc O X(100) Remarks on status if available.
datetime M N(14)

Current date time in HKT

in DDMMYYYYHHMISS format


Request and Response Samples

Create Party Request - Sample Message

Clear-text value for JWS payload of 'createparty_req' tag:
								{"corpid":"CN000002","subcorpid":"SG687687","subcorpname":"ABC Private Limited","shortname":"ABC","subcorpidproxy":"AAA","country":"SG","mcc":"1234","pspid":"SGPAYNOW","bizregnum":"67597697X","remark":"Sample Payload","datetime":"12102022120000"}
						

Create Party Response - Sample Message

Clear-text value for JWS payload of 'createparty_resp' tag:
								{"corpid":"CN000002","subcorpid":"SG687687","subcorpname":"ABC Private Limited","subcorpidproxy":"AAA","country":"SG","pspid":"SGPAYNOW","deleteflag":"N","status":"ACCEPTED","datetime":"12102022120000"}
						

Try it out

Input Fields
corpid
subcorpid
subcorpname
shortname
subcorpidproxy
country
pspid
mcc
bizregnum
remark
datetime
Merchant Keys
Straight2Bank Pay Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
XML request
JSON request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/createparty
Response
Decrypted response

Delete Party


Delete Party Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

API Name

Delete Party

Source

Corporate client

Destination

S2BPAY

Message layer level Security

Request and Response: JWE String (RS-256 Sign, AES-256 GCM encryption)

SCB RSA Public Key: https://test-s2bpay.sc.com/s2bpaysit/devguide#idocs_pubkey

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/deleteparty

Prod: https://s2bpay.sc.com/s2bpay/deleteparty

Event

Whenever Corporate wants to delete SubCorpId

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant.
X2 deleteparty_req M X(2000)

This tag contains JWE String

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table - JWS String

The following tables lists the details used to construct the value for 'deleteparty_req' tag.

JWE String

JWE Component Value
JWE Header

Base64URL encode (UTF8(JSON value))

{"enc":"A256GCM","alg":"RSA-OAEP-256"}

JWE encrypted Key Generate a random key(32 chars). Encrypt the random key with SCB Public key using RSA-2048 algorithm
Initialization Vector Generate a 12 byte IV string used for GCM encryption
Ciphertext

Form the JWS String with Header.Payload.Signature format explain in next table.

Encrypt the JWS string with random key generated using AES-256 GCM algorithm and populate in Ciphertext.

Authentication Tag Authentication tags returned in GCM algorithm

JWS String

JWS Component Value
JWS Header

Base64URL encode (UTF8(JSON value))

{"alg":"RS256","typ":"JWT"}

JWS Payload Payload is base-64 encoded JSON string with attributes in next table
JWS Signature

Sign generated for Header.Payload using RS256 algorithm with Sender's Private key

The value will be validated at receiver's end

Payload Attributes

Key Name M/O/C Type & Length Remarks
corpid M X(8) Corp ID of Merchant
subcorpid M X(50)

subcorpid value given by merchant

the value to be URL encoded if having &=

datetime M N(14)

Format: DDMMYYYYHH(24)MMSS (GMT+08:00)

The encrypted string is valid only for 5 minutes from the created time.


Delete Party Response (Straight2Bank Pay to Merchant Server)

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 ack M X(10)

Possible Value

  • PASS
  • FAIL
X2 ackdesc O X(100)

This tag will be populated only if ack is FAIL.

X3 corpid C X(8)

Corp ID of Merchant.

Present only when ack=PASS

X4 deleteparty_resp C X(2000)

Present only when ack = PASS

JWE format string which contains this following parts separated by .(dot).

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table:

The following tables lists the details used to construct the value for 'deleteparty_resp' tag.

JWE String

JWE Component Value
JWE Header

Base64URL encode (UTF8(JSON value))

{"enc":"A256GCM","alg":"RSA-OAEP-256"}

JWE encrypted Key Random key is encrypted with Merchant's public key. Decrypt it using Merchant's private key
Initialization Vector Generate a 12 byte IV string used for GCM encryption
Ciphertext

JWS String with Header.Payload.Signature format explain in next table.

Decrypt it with the Random key

Authentication Tag Authentication tags returned in GCM algorithm

JWS String

JWS Component Value
JWS Header

Base64URL encode (UTF8(JSON value))

{"alg":"RS256","typ":"JWT"}

JWS Payload Payload is base-64 encoded JSON string with attributes in next table
JWS Signature

Sign generated for Header.Payload using RS256 algorithm with S2BPAY's Private key

The value will be validated at receiver's end using S2BPAY's public key

Payload Attributes

Key Name M/O/C Type & Length Remarks
corpid M X(8) Corp ID of Merchant
subcorpid M X(50)

subcorpid value given by merchant

the value to be URL encoded if having &=

subcorpname M X(70)

name of sub corporate

the value to be URL encoded if having &=

subcorpidproxy C X(50) Value given by merchant
country M X(2) country code
pspid M X(8) PSPid for which subcorpid to be created
accnum O X(34) Merchant Account number for which Proxy is created
partyseqnum O N(14) Straight2Bank Pay generated unique ID for this Proxy entry
proxy O X(200) Proxy created as per merchant configuration
regid O X(50) Registration ID while creating Proxy
diplayname O X(140)

Display name used when creating proxy based on merchant configuration

the value to be URL encoded if having &=

deleteflag M X(1)

Indicates whether this subcorpid is deleted/not

Possible values: Y/N

Default value : N

status M X(20)

Current status of proxy from Straight2Bank Pay records

Possible values: SUCCESS, FAIL, PENDING

statusdesc O X(100) Remarks on status if available.
datetime M N(14)

Current date time in HKT

in DDMMYYYYHHMISS format


Request and Response Samples

Delete Party Request - Sample Message

Clear-text value for JWS payload of 'deleteparty_req' tag:
								{"corpid":"CN000002","subcorpid":"SG687687","datetime":"12102022120000"}
						

Delete Party Response - Sample Message

Clear-text value for JWS payload of 'deleteparty_resp' tag:
								{"corpid":"CN000002","subcorpid":"SG687687","subcorpname":"ABC Private Limited","subcorpidproxy":"AAA","country":"SG","pspid":"SGPAYNOW","proxy":"SG000002SG6787687","regid":"779324636295","accnum":"0100584918","diplayname":"ABC Private Limited Singapore","deleteflag":"N","status":"ACCEPTED","datetime":"12102022120000"}
						

Try it out

Input Fields
corpid
subcorpid
datetime
Merchant Keys
Straight2Bank Pay Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
XML request
JSON request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/deleteparty
Response
Decrypted response

Query Party


Query Party Request (Merchant Server to Straight2Bank Pay)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

API Name

Query Party

Source

Corporate client

Destination

S2BPAY

Message layer level Security

Request and Response: JWE String (RS-256 Sign, AES-256 GCM encryption)

SCB RSA Public Key: https://test-s2bpay.sc.com/s2bpaysit/devguide#idocs_pubkey

URL

Test: https://test-s2bpay.sc.com/s2bpaysit/queryparty

Prod: https://s2bpay.sc.com/s2bpay/queryparty

Event

Whenever Corporate wants to query SubCorpId

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid M X(8) Corp ID of Merchant.
X2 queryparty_req M X(2000)

This tag contains JWE String

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table - JWS String

The following tables lists the details used to construct the value for 'queryparty_req' tag.

JWE String

JWE Component Value
JWE Header

Base64URL encode (UTF8(JSON value))

{"enc":"A256GCM","alg":"RSA-OAEP-256"}

JWE encrypted Key Generate a random key(32 chars). Encrypt the random key with SCB Public key using RSA-2048 algorithm
Initialization Vector Generate a 12 byte IV string used for GCM encryption
Ciphertext

Form the JWS String with Header.Payload.Signature format explain in next table.

Encrypt the JWS string with random key generated using AES-256 GCM algorithm and populate in Ciphertext.

Authentication Tag Authentication tags returned in GCM algorithm

JWS String

JWS Component Value
JWS Header

Base64URL encode (UTF8(JSON value))

{"alg":"RS256","typ":"JWT"}

JWS Payload Payload is base-64 encoded JSON string with attributes in next table
JWS Signature

Sign generated for Header.Payload using RS256 algorithm with Sender's Private key

The value will be validated at receiver's end

Payload Attributes

Key Name M/O/C Type & Length Remarks
corpid M X(8) Corp ID of Merchant
subcorpid M X(50)

subcorpid value given by merchant

the value to be URL encoded if having &=

datetime M N(14)

Format: DDMMYYYYHH(24)MMSS (GMT+08:00)

The encrypted string is valid only for 5 minutes from the created time.


Query Party Response (Straight2Bank Pay to Merchant Server)

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 ack M X(10)

Possible Value

  • PASS
  • FAIL
X2 ackdesc O X(100)

This tag will be populated only if ack is FAIL.

X3 corpid C X(8)

Corp ID of Merchant.

Present only when ack=PASS

X4 queryparty_resp C X(2000)

Present only when ack = PASS

JWE format string which contains this following parts separated by .(dot).

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table:

The following tables lists the details used to construct the value for 'queryparty_resp' tag.

JWE String

JWE Component Value
JWE Header

Base64URL encode (UTF8(JSON value))

{"enc":"A256GCM","alg":"RSA-OAEP-256"}

JWE encrypted Key Random key is encrypted with Merchant's public key. Decrypt it using Merchant's private key
Initialization Vector Generate a 12 byte IV string used for GCM encryption
Ciphertext

JWS String with Header.Payload.Signature format explain in next table.

Decrypt it with the Random key

Authentication Tag Authentication tags returned in GCM algorithm

JWS String

JWS Component Value
JWS Header

Base64URL encode (UTF8(JSON value))

{"alg":"RS256","typ":"JWT"}

JWS Payload Payload is base-64 encoded JSON string with attributes in next table
JWS Signature

Sign generated for Header.Payload using RS256 algorithm with S2BPAY's Private key

The value will be validated at receiver's end using S2BPAY's public key

Payload Attributes

Key Name M/O/C Type & Length Remarks
corpid M X(8) Corp ID of Merchant
subcorpid M X(50)

subcorpid value given by merchant

the value to be URL encoded if having &=

subcorpname M X(70)

name of sub corporate

the value to be URL encoded if having &=

subcorpidproxy C X(50) Value given by merchant
country M X(2) country code
pspid M X(8) PSPid for which subcorpid to be created
accnum O X(34) Merchant Account number for which Proxy is created
partyseqnum O O(14) Straight2Bank Pay generated unique ID for this Proxy entry
proxy O X(200) Proxy created as per merchant configuration
regid O X(50) Registration ID while creating Proxy
diplayname O X(140)

Display name used when creating proxy based on merchant configuration

the value to be URL encoded if having &=

deleteflag M X(1)

Indicates whether this subcorpid is deleted/not

Possible values: Y/N

Default value : N

status M X(20)

Current status of proxy from Straight2Bank Pay records

Possible values: SUCCESS, FAIL, PENDING

statusdesc O X(100) Remarks on status if available.
datetime M O(14)

Current date time in HKT

in DDMMYYYYHHMISS format


Request and Response Samples

Query Party Request - Sample Message

Clear-text value for JWS payload of 'queryparty_req' tag:
								{"corpid":"CN000002","subcorpid":"SG687687","datetime":"12102022120000"}
						

Query Party Response - Sample Message

Clear-text value for JWS payload of 'queryparty_resp' tag:
								{"corpid":"CN000002","subcorpid":"SG687687","subcorpname":"ABC Private Limited","subcorpidproxy":"AAA","country":"SG","pspid":"SGPAYNOW","proxy":"SG000002SG6787687","regid":"779324636295","accnum":"0100584918","diplayname":"ABC Private Limited Singapore","deleteflag":"N","status":"SUCCESS","datetime":"12102022120000"}
						

Try it out

Input Fields
corpid
subcorpid
datetime
Merchant Keys
Straight2Bank Pay Public Key
Corporate RSA Private Key
Payload
Plain Request Payload
Request
XML request
JSON request
Submit request
URL https://test-s2bpay.sc.com/s2bpaysit/queryparty
Response
Decrypted response

Party Notification

Merchant is expected to host a REST API (also called as Webhook / Reverse API) to receive real-time notification from Straight2Bank Pay.

In the above mentioned party flows, Straight2Bank Pay notifies the corporate client in real-time about the status of the request. For CreateParty, the client is notified in both SUCCESS and FAIL cases while for DeleteParty, the client is notified on successful deletion. Merchant Server is expected to accept the message, saves the status and sends the response synchronously back to Straight2Bank Pay server.

The notification and its response message specifications have been designed by Straight2Bank Pay


Party Notification Request (Straight2Bank Pay to Merchant Server)

Protocol

HTTPS POST (REST API)

Message Format

XML or JSON

Communication Layer level security

TLSv1.2

API Name

Party Notification

Source

S2BPAY

Destination

Corporate client

Message layer level Security

Request and Response: JWE String (RS-256 Sign, AES-256 GCM encryption)

SCB RSA Public Key: https://test-s2bpay.sc.com/s2bpaysit/devguide#idocs_pubkey

URL

Client Notify URL as configured

SCB IP Address Following subnet range to be white listed at Merchant server (Same for Test and Production):

166.81.66.31, 166.81.66.32, 166.81.66.33, 166.81.66.34, 166.81.66.35, 166.81.66.36, 166.81.66.37, 166.81.66.38, 166.81.66.39, 166.81.66.40

166.81.85.31, 166.81.85.32, 166.81.85.33, 166.81.85.34, 166.81.85.35, 166.81.85.36, 166.81.85.37, 166.81.85.38, 166.81.85.39, 166.81.85.40

166.81.13.0/25, 166.81.14.0/25, 166.81.23.0/25, 166.81.24.0/25

166.81.78.0/25, 166.81.77.0/25, 166.81.79.0/25, 166.81.80.0/25

Event

For positive and negative scenarios in CreateParty and for successful cases in DeleteParty.

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid C X(8) Corp ID of Merchant.
X2 party_notifyreq C X(2000)

This tag contains JWE String

JWE format string which contains this following parts separated by .(dot)

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table - JWS String

The following tables lists the details used to construct the value for 'party_notifyreq' tag.

JWE String

JWE Component Value
JWE Header

Base64URL encode (UTF8(JSON value))

{"enc":"A256GCM","alg":"RSA-OAEP-256"}

JWE encrypted Key Generate a random key(32 chars). Encrypt the random key with SCB Public key using RSA-2048 algorithm
Initialization Vector Generate a 12 byte IV string used for GCM encryption
Ciphertext

Form the JWS String with Header.Payload.Signature format explain in next table.

Encrypt the JWS string with random key generated using AES-256 GCM algorithm and populate in Ciphertext.

Authentication Tag Authentication tags returned in GCM algorithm

JWS String

JWS Component Value
JWS Header

Base64URL encode (UTF8(JSON value))

{"alg":"RS256","typ":"JWT"}

JWS Payload Payload is base-64 encoded JSON string with attributes in next table
JWS Signature

Sign generated for Header.Payload using RS256 algorithm with Sender's Private key

The value will be validated at receiver's end

Payload Attributes

Key Name M/O/C Type & Length Remarks
corpid M X(8) Corp ID of Merchant
subcorpid M X(50)

subcorpid value given by merchant

the value to be URL encoded if having &=

subcorpname M X(70)

name of sub corporate

the value to be URL encoded if having &=

subcorpidproxy C X(50) Value given by merchant
country M X(2) country code
pspid M X(8) PSPid for which subcorpid to be created
accnum O X(34) Merchant Account number for which Proxy is created
partyseqnum O N(14) Straight2Bank Pay generated unique ID for this Proxy entry
proxy O X(200) Proxy created as per merchant configuration
regid O X(50) Registration ID while creating Proxy
diplayname O X(140)

Display name used when creating proxy based on merchant configuration

the value to be URL encoded if having &=

deleteflag M X(1)

Indicates whether this subcorpid is deleted/not

Possible values: Y/N

Default value : N

status M X(20)

Current status of proxy from Straight2Bank Pay records

Possible values: SUCCESS, FAIL, PENDING

statusdesc O X(100) Remarks on status if available.
datetime M N(14)

Current date time in HKT

in DDMMYYYYHHMISS format


Party Notify Response (Merchant Server to Straight2Bank Pay)

Message Specification

Seq Num Key Name M/O/C Type & Length Remarks
X1 corpid C X(8)

Corp ID of Merchant.

Present only when ack=PASS

X2 party_notifyresp C X(2000)

Present only when ack = PASS

JWE format string which contains this following parts separated by .(dot).

JWE Header.JWE encrypted Key.Initialization Vector.Ciphertext.Authentication Tag

The details are explained in below table:

The following tables lists the details used to construct the value for 'party_notifyresp' tag.

JWE String

JWE Component Value
JWE Header

Base64URL encode (UTF8(JSON value))

{"enc":"A256GCM","alg":"RSA-OAEP-256"}

JWE encrypted Key Random key is encrypted with Merchant's public key. Decrypt it using Merchant's private key
Initialization Vector Generate a 12 byte IV string used for GCM encryption
Ciphertext

JWS String with Header.Payload.Signature format explain in next table.

Decrypt it with the Random key

Authentication Tag Authentication tags returned in GCM algorithm

JWS String

JWS Component Value
JWS Header

Base64URL encode (UTF8(JSON value))

{"alg":"RS256","typ":"JWT"}

JWS Payload Payload is base-64 encoded JSON string with attributes in next table
JWS Signature

Sign generated for Header.Payload using RS256 algorithm with S2BPAY's Private key

The value will be validated at receiver's end using S2BPAY's public key

Payload Attributes

Seq Num Key Name M/O/C Type & Length Remarks
P1 status M X(10) Possible Value:
  • SUCCESS
  • ERROR
P2 statusdesc O X(100)

Description of the Error.

E.g. Hashing Error

P3 ackref M X(16) Acknowledgment Reference which can be used to investigate of any missing notification.
P4 partyseqnum M X(16) Transaction ID that has been sent in the notifyreq message.
P5 date O X(14)

Datetime stamp of Merchant server.

Format: DDMMYYYYHH24MiSS (GMT+8)


Request and Response Samples

Party Notify Request - Sample Message

Clear-text value for JWS payload of 'party_notifyreq' tag:
								{"corpid":"CN000002","subcorpid":"TEST002SG687687","subcorpname":"ABC Private Limited","subcorpidproxy":"AAA","country":"SG","pspid":"SGPAYNOW","accnum":"0200000451","partyseqnum":"1011","proxy":"03100810BAAA","regid":"543301554798","diplayname":"ABC Company Ltd-ABC Private Limited","deleteflag":"N","status":"SUCCESS","datetime":"07022023152722"}
						

Party Notify Response - Sample Message

Clear-text value for JWS payload of 'party_notifyresp' tag:
								{"status":"SUCCESS","ackref":"8990065897", "partyseqnum":"1011", "date":"07022023152742"}
						

Try it out

Input Fields
corpid
subcorpid
status
Submit request


Mandate Link Response

Response specification are same as Mandate Notification Request.

Request and Response Samples

Sample Request

Merchant will be provided with an URL during on-boarding, which contains encstr attribute as part of query-string.

https://test-s2bpay.sc.com/s2bpaysit/lmandate?encstr=MBk+Eld6E75xgsUQNMbLR1ZnIDMA+s4XBFJ1WNy3twigc3qJXUZuW0lLQZ3QohIWQ0MAAoMhcj6Pg8eQJ+YF3g==&cencstr=MBk+Eld6E75xgsUQNMbLRzL89TrVP++ChURabfgRwtk=

Merchant can add transaction details with attribute cencstr towards end of the URL as follows:

https://test-s2bpay.sc.com/s2bpaysit/lmandate?encstr=MBk+Eld6E75xgsUQNMbLR5U1saSyiUG1T0r0SCHbkuQdLahIuZ5I0RMrO3Xif20k&cencstr=Mhh1vazm+ol303RlwTVps+OqIgeEakKusfmlPF3j3REWkh8PM+URz5RO+/VLjIw+

Sample Response

Response Sample same as Mandate Notification Request Sample.


Try it out

Input Fields
corpid
ctry
curr
ref1
ref2
ref3
ref4
ref5
ref6
ref7
ref8
ref9
ref10
datetime
rurl
pspid
Merchant Keys
AES Key
Public Key
Corporate RSA Private Key
Submit request
Digital Signature
eMandate Link

Report and File Handling

This section provides Format specification of Reports that Straight2Bank Pay generates based on Merchant's Profile. Straight2Bank generates 2 types of reports.

  1. Transaction Report
  2. Settlement Report (not applicable for collection via Instant Payment)
This section also covers the format specification of file format that can be uploaded for the following:
  1. To initiate refund instruction
  2. To generate dynamic/semi-dynamic payment link
  3. To generate Payment Link Generator with hard-coded value for reference field
Fraud Awareness
Protect your organisation from fraud by staying vigilant. Before downloading or opening any files, always ensure that it is from a trusted source and channel. Likewise, information should only be uploaded via secure channels, and inputs should be limited to the required data attributes. Learn more about fraud and how to protect your organisation here. (Click on the "Report Fraud" button on this page to report any suspicious activities).

Syntax of the Report

  • Straight2Bank Pay report is in CSV file format.
  • The report contains one header row with field title and followed by data.
  • Each record ends with new line character. Unix-style new line character is being used.
  • Start/End character for each field is " (double-quoted).
  • Field separator is , (Comma).
  • No escape character supported.
  • Date field is formatted in YYYY-MM-DD and Time field is formatted in HH:mm:ss (hours are represented in 24 hours format)
  • M - Mandatory, O - Optional. C - Conditional (Mandatory based on other fields / conditions)
  • Column 'Type & Length' indicates:
    1. X(n) - Alphanumeric, 'n' indicates maximum number of characters allowed.
    2. 9(m).9(n) - Numeric alone, 'm' indicates maximum number of total digits including decimals and 'n' indicates maximum number of decimals allowed.

Delivery Channel of Report

The report can be delivered either via eMail or any H2H channel (SFTP, SAP PI, SWIFTNET FileAct).


Transaction Report

The report can be configured in such a way to report only positive status transactions (default setting) or ALL statuses transactions. Refer D17 for the details of the statuses. The report will contain the transaction of a Corp ID, irrespective integration method used to integrate with Straight2Bank Pay.

Seq Num Field Name M/O/C Type & Length Column Title Remarks
D1 Corp ID M X(8) Corp ID Corp ID of Merchant
D2 Country Code M X(2) Country Code 2-character country code.
D3 PSP ID M X(8) Payment Method Payment Service Provider ID. S2BPay assigns 8 characters code for each Payment Method. Eg: SG: SGPAYNOW, SGENETS1, SGFDMS01
D4 Transaction Type M X(30) Txn Type Possible value:
  1. NEW
  2. REFUND
  3. VOID
D5 Reference 1 O X(100) Ref 1 Reference 1 as provided by Merchant.
D6 Reference 2 O X(100) Ref 2 Reference 2 as provided by Merchant.
D7 Reference 3 O X(100) Ref 3 Reference 3 as provided by Merchant.
D8 Reference 4 O X(100) Ref 4 Reference 4 as provided by Merchant.
D9 Reference 5 O X(100) Ref 5 Reference 5 as provided by Merchant.
D10 Unique Reference M X(100) Unique Ref Unique value either from Merchant (any one field from ref1..ref5 as configured in corp_id profile) or S2BPay assigned unique value. Or Refund reference as provided by Merchant.
D11 Currency Code M X(3) CCYCODE 3-character currency code.
D12 Amount M X(22) Amount Amount of the transaction.
D13 S2BPay Assigned Transaction ID M X(22) SCB Txn ID Straight2Bank Pay generated unique transaction ID for this transaction.
D14 Partner assigned transaction ID O X(70) Partner Txn ID Our partner (PSP) generated unique transaction ID for this transaction if available.
D15 Status Date M X(11) Created Date Date on which the transaction status is updated with final status. Date is in GMT+08:00 time zone.
D16 Status Time M X(11) Created Time Created Time on which the transaction status is updated with final status. Date is in GMT+08:00 time zone.
D17 Status M X(22) Status For possible value for default Report configuration which sends Positive status only. For NEW Transaction:
  1. SUCCESSFUL
  2. CREDITED
  3. PRE_AUTHORIZED
For REFUND / VOID Transaction:
  1. SUCCESSFUL
For possible value for Report configuration which sends ALL statuses. For NEW Transaction:
  1. SUCCESSFUL
  2. UNSUCCESSFUL
  3. PENDING
  4. CREDITED
  5. PRE_AUTHORIZED
  6. VOIDED
For REFUND / VOID Transaction:
  1. SUCCESSFUL
  2. PENDING
  3. FAILED
D18 Status Remarks O X(200) Status Remarks Remarks on status if available.
D19 Refund Parent Transaction ID C X(150) Refund Parent Txn ID Transaction ID of original transaction for which refund was initiated. It will be populated only for REFUND txn type. A static code is prefixed with the data, static code value is like UNIQUEREF- or SCB_TXN_ID-.
D20 Payer Account O X(35) Payer Account Payer Account if available.
D21 Payer Bank Code O X(50) Payer Bank Code Payer Bank Code if available.
D22 Payer Name O X(50) Payer Name Payer Name if available.
D23 Client Identity O X(50) Corporate Identity Client proxy if available.
D24 Pre-auth Amount O X(22) Preauth Amount Pre-authorized amount if this feature is utilized.
D25 GST Amount O X(22) GST Amount Not applicable.
D26 Tax Amount O X(22) Tax Amount Not applicable.
D27 Charge Amount O X(22) Charge Amount Not applicable.
D28 Net Amount O X(22) Net Amount Not applicable.
D29 Total Charge Amount O X(22) Total Charge Amount Not applicable.

Transaction Report as Prior-Day

This report can be configured as Prior day. Report generation timing needs to be captured at Corporate Profile level. If Report is configured to generate at 02:30 am (GMT+08:00), then the report will be generated with transaction from 02:30am of Prior day to 02:30am of today.


Transaction Report as Prior-Day + Intra-Day

Report can be configured to generate multiple time of the day. If report timing is configured as 00:00,09:00,18:00,
  1. 1st report will be generated at 00:05 of current date with the transactions that are created/authorized from 00:00 of prior day to 00:00 of today.
  2. 2nd report will be generated at 09:05 of current date with the transactions that are created/authorized from 00:00 of current date to 09:00 of current date.
  3. 3rd report will be generated at 18:05 of current date with the transactions the tare created/authorized from 00:00 of current date to 18:00 of current date.

Sample Transaction Report

"Corp ID","Country Code","Payment Method","Txn Type","Ref 1","Ref 2","Ref 3","Ref 4","Ref 5","Unique Ref","CCYCODE","Amount","SCB Txn ID","Partner Txn ID","Created Date","Created Time","Status","Status Remarks","Refund Parent Txn ID","Payer Account","Payer BankCode","Payer Name","Corporate Identity","Preauth Amount","GST Amount","Tax Amount","Charge Amount","Net Amount","Total Charge Amount"
"S2BPAY02","HK","HKFPSHKD","NEW","12345678901","","","","CXXXG HO XXX","20000651078","HKD","1","20000651078","","2020-04-14","00:02:35","CREDITED","","","","","","","","","","","",""

Settlement Report

This report will be generated when Straight2Bank sends payment instructions to back office application to credit into Merchant's account. This report will contain all the transactions that are qualified for settlement for current date. Please note that this report does not include Instant Payment (like, UPI, PayNow, FPS, Bank Transfer via VA etc) transaction as settlement has taken place in real-time

Seq Num Field Name M/O/C Type & Length Column Title Remarks
D1 Corp ID M X(8) Corp ID Corp ID of Merchant
D2 Country Code M X(2) Country Code 2-character country code.
D3 PSP ID M X(8) Payment Method Payment Service Provider ID. S2BPay assigns 8 characters code for each Payment Method. Eg: SG: SGPAYNOW, SGENETS1, SGFDMS01
D4 Transaction Type M X(30) Txn Type Possible value:
  1. NEW - Individual txn for which settlement is being initiated
  2. CHARGEBACKS - CREDIT
  3. MISC - CREDIT
  4. MISC FEE - CREDIT
  5. GST ON FEE - CREDIT
  6. SETTLEMENT - it will contain the consolidated view of today's settlement.
D5 Reference 1 O X(100) Ref 1 Reference 1 as provided by Merchant.
D6 Reference 2 O X(100) Ref 2 Reference 2 as provided by Merchant.
D7 Reference 3 O X(100) Ref 3 Reference 3 as provided by Merchant.
D8 Reference 4 O X(100) Ref 4 Reference 4 as provided by Merchant.
D9 Reference 5 O X(100) Ref 5 Reference 5 as provided by Merchant.
D10 Unique Reference M X(100) Unique Ref Unique value either from Merchant (any one field from ref1..ref5 as configured in Merchant's profile) or S2BPay assigned unique value. Or Refund reference as provided by Merchant.
D11 Settlement Reference O X(22) Settlement Ref Settlement Reference if available.
D12 Currency Code M X(3) CCYCODE 3-character currency code.
D13 Pre-auth Amount M X(22) Preauth Amount 13 integer digits and a precision of 2 decimals
D14 Settlement Date M Date Settlement Date Settlement Date.
D15 Amount M X(22) Amount 13 integer digits and a precision of 2 decimals
D16 Charge Amount O X(22) Charge Amount Charge Amount if available.
D17 Net Amount O X(22) Net Amount Net Amount if available
D18 S2BPay Assigned Transaction ID M X(22) SCB Txn ID Straight2Bank Pay generated unique transaction ID for this transaction.
D19 Partner assigned transaction ID O X(70) Partner Txn ID Our partner (PSP) generated unique transaction ID for this transaction.
D20 Status Date M X(11) Created Date Date on which the transaction status is updated with final status. Date is in GMT+08:00 time zone.
D21 Status Time M X(11) Created Time Time on which the transaction status is updated with final status. Date is in GMT+08:00 time zone.
D22 Refund Parent Transaction ID C X(150) Refund Parent Txn ID Not applicable.
D23 Payer Account O X(35) Payer Account Payer Account if available.
D24 Payer Bank Code O X(50) Payer BankCode Payer Bank Code if available.
D25 Payer Name O X(50) Payer Name Payer Name if available.
D26 Client Identity O X(50) Corporate Identity Client proxy if available.
D27 GST Amount O X(22) GST Amount GST Amount if available
D28 Tax Amount O X(22) Tax Amount Tax Amount if available
D29 Total Charge Amount O X(22) Total Charge Amount Total Charge Amount if available

Sample Settlement Report

"Corp ID","Country Code","Payment Method","Txn Type","Ref 1","Ref 2","Ref 3","Ref 4","Ref 5","Unique Ref","Settlement Ref","CCYCODE","Preauth Amount","Settlement Date","Amount","Charge Amount","Net Amount","SCB Txn ID","Partner Txn ID","Created Date","Created Time","Refund Parent Txn ID","Payer Account","Payer BankCode","Payer Name","Corporate Identity","GST Amount","Tax Amount","Total Charge Amount"
"S2BPAY02","BD","BDSSLWLT","NEW","7896541","xxx","1234567889","","","7896541","","BDT","","2020-02-20","100.50","","","20000000001","BMB38922019010215598","2020-02-19","09:21:19","","","BDBKASH1","","","","",""
"S2BPAY02","BD","BDSSLWLT","NEW","7896542","xxx","1234567890","","","7896542","","BDT","","2020-02-20","200.50","","","20000000002","BMB38922019010215599","2020-02-19","11:24:38","","","BDBKASH1","","","","",""
"S2BPAY02","BD","BDSSLWLT","SETTLEMENT","Total Txns : 2","","","","20-Feb-2020","20000000011","","BDT","","2020-02-20","301.00","","","20000000011","","2020-02-20","15:00:35","","","","","","","",""

Bulk File Upload - Refund

Straight2Bank Pay offers following channels to initiate refund against the transactions that are collected via Straight2Bank Pay

  • Via API. Please refer Integration Guide for more details.
  • Via manual file upload in S2B Web or any H2H channels. This method supports bulk refund initiation using CSV file format.
Straight2Bank Pay does the following validation for refund request:
  • Refund request can be initiated only against a transaction that was successfully collected via Straight2Bank Pay.
  • Refund requested amount should not be greater than the corresponding collected transaction amount.
  • Multiple refund requests can be initiated, but total amount of all refunds, should not exceed the collected transaction amount.

Straight2Bank Pay process the refund request based on PSP of the collected transaction.

If PSP supports processing of refund, then the following process will be applied:

For each refund request, Straight2Bank Pay will initiate fund transfer from Merchant's account to internal account, this transfer will be initiated using Merchant's S2B Group ID as like Merchant has initiated Book Transfer (BT) payment to credit into internal account. Merchant can locate this payment in their regular Payable report from S2B channels.

Once funds have been successfully debited from Merchant's account, Straight2Bank Pay will call API of PSP and request for refund to the Buyer. Buyer will be identified based on the reference number of the collected transaction that was done by buyer to pay to Merchant. Hence Merchant does not need to populate Creditor Name, Creditor Account Number and Creditor Bank code as part of refund file.

If PSP does not support refund, then the following process will be applied:

For each refund request, Straight2Bank Pay initiates outgoing payment to the beneficiary via country's domestic payment method like (ACH or RTGS or FAST), this payment will be initiated using Merchant's S2B Group ID as like Merchant has initiated domestic payment to the Beneficiary. Merchant can locate this payment in their regular Payable report from S2B channels.

Under this category, there are 2 set of PSPs (Payment Methods), one setup of PSPs, payer information (payer name, payer account number and payer bank code) is available in Straight2Bank Pay. For such PSPs, Merchant does not need to populate Creditor Name, Creditor Account Number and Creditor Bank code as part of refund file. Straight2Bank Pay populates beneficiary information for the outgoing payment from the corresponding collected transaction.

Another setup of PSPs, payer information does not reach to Straight2Bank Pay due to regulatory restriction or any other reason. For such scenario, Merchant is expected to collect beneficiary details (Creditor Name, Creditor Account Number and Creditor Bank code) from their Buyer and then populate in refund file.

Refund status will be reported in Transaction Report.

Bulk REFUND file format needs to be in CSV file format. The file needs to have one header row with the field title and followed by data. There is no validation on the header row and it will be ignored.

Seq Num Field Name M/O/C Type & Length Remarks
R1 corpid M X(8) Corp ID of Merchant.
R2 Unique Ref of collected txn C X(100)

Reference number to locate collected transaction for which refund is being initiated, one of the following field is mandatory, other 2 fields to be kept blank.

Unique Ref of collected txn - Transaction Reference that was assigned by Merchant.

SCB Txn ID of collected txn - Transaction ID that is assigned by Straight2Bank Pay, Merchant can get this value from notification message or from Transaction Report.

Partner Txn ID of collected txn - Transaction Reference that was assigned by partner (PSP). Merchant can get this value from notification message or from Transaction Report.

R3 SCB Txn ID of collected txn C X(100)
R4 Partner Txn ID of collected txn C X(100)
R5 Refund Amount M N(16,3) Amount to be refunded.
R6 Refund Unique Ref M X(16) Unique reference of this refund request.
R7 Refund value Date O X(8) Format: DDMMYYYY

If value date populated is future date, then it will be considered to process the refund on the value date.

If no value is provided, then Straight2Bank Pay will process the refund request with the current date.

R8 Refund Debit account number O X(8) Merchant's account that needs to be debited to process the refund request.

If no value is provided for this field, then it will be defaulted to the account that has been configured in profile.

R9 Type O X(8) If any PSP supports both Refund and VOID (same day cancellation), then it is mandatory to be explicitly to be mentioned. Possible value: VOID REFUND
R10 Credit account number C X(10) Beneficiary Account Number or Beneficiary Proxy to which the fund to be sent. It is mandatory for the PSP for which Straight2Bank Pay does not receive Buyer Account Number from PSP or Clearing House.
R11 Credit bank Code C X(34) Beneficiary Bank Code. If Bank Code is mandatory for outgoing payment, then it is not avaialble in Straight2Bank Pay, then it is mandatory.
R12 Creditor Name C X(11) Beneficiary Name. It is mandatory for the PSP for which Straight2Bank Pay does not receive Buyer Name from PSP or Clearing House.
R13 Payment Type C X(70) It will indicate either Payment Type or sub-payment-type, coded value. The value will be provided during the implemenatoin if it is applicable.

Sample Refund File

Corp ID,Unique Ref of collected txn,SCB Txn ID of collected txn,Partner Txn ID of collected txn,Refund Amount,Refund Unique Ref,Refund value Date,Refund Debit account number,Type,Credit account  number,Credit bank Code,Creditor Name,Payment Type
SGS2BPAY,200008737931,,,10,RefundQR06,,,,,,,
SGS2BPAY,200008737945,,,10,RefundQR07,,,,,,,
SGS2BPAY,200008737980,,,10,RefundQR08,,,,,,,
SGS2BPAY,200008737986,,,10,RefundQR09,,,,,,,
SGS2BPAY,200008737995,,,10,RefundQR10,,,,,,,

Manual Steps to upload Refund file via Straight2Bank Web

Steps to upload bulk refund file manually via Straight2Bank Web portal:
  1. Login to Straight2Bank Web.
  2. Navigate to the menu as shown below.

    RefundFileStep2

  3. Choose S2BPAY from 'FILE UPLOAD' dropdown list box, REFUND from 'DATA TEMPLATE / FILE FORMAT' dropdown list box, choose the file to be uploaded in 'UPLOAD FILE' and click on 'CONTINUE' button.

    RefundFileStep3

  4. Enter the Challenge Code into Vasco token and enter the Response code back on the screen as shown below.

    RefundFileStep4





Bulk File Upload - Present Invoice

For 'Invoice Presentment and Payment' module, it is mandatory for Merchant to upload the outstanding invoices that need to be presented to the Payer and collect using payment method of Straight2Bank Pay. Invoice files can be uploaded manually via S2B Web or automatically via any H2H channels.

Straight2Bank Pay applies following logic while processing the invoice file:

  1. Identifies the corp_id by using the following rule:
    • Corp ID is auto-derived if there is just one corp_id created under Merchant's S2B Group ID.
    • If more than one Corp ID is available under Merchant's S2B Group ID and Invoice file to be uploaded to just for one Corp ID always, then that corp_id alone to be configured with the key 'PRESENT_INVOICE_CORPID' with the value as Corp ID (enclosed with square bracket [ ]).
    • If more than one Corp ID is available under Merchant's S2B Group ID and Invoice File to be created for more than one Corp ID, then the Corp ID needs to be populated as part of the filename. The Position in the file name from where the corp_id to be read needs to be configured with the key PRESENT_INVOICE_CORPID with the value as 'FILENAME,<position of the corp_id>'
  2. Deletes all the PENDING Invoices (if any) that was uploaded earlier. (this can be disabled if required at Corp_id level)
  3. Captures Invoices from the File against the corp_id, with status as PENDING. If any invoice in the file is already available with PAID status in Straight2Bank Pay database, then it will be ignored, similarly if invoice does not have all the mandatory fields, then it will be ignored also.
  4. Following types of line items are supported in the file:
    1. Invoice
    2. Debit Note
    3. Credit Note
    4. Credit Voucher
  5. If any item from the file is ignored, then an output file will be sent to the same channel on which the file is uploaded. The output file contains all the data of rejected line item with an additional field as 'REJECTED REASON' as last field. Option is available to send the output file to other channel like S2B Web or any H2H channel or via pre-configured email ids.

After uploading the invoice file, Merchant can send the payment link of the corp_id to their payers to fetch the outstanding invoices and make the payment. S2BPay reports both the payment data and its associated invoice lines items in a report for Merchant.

Merchant can choose which data from Invoice File to be shown for the payer and assign the column title for Invoice table in 'Invoice Presentment' page. PRESENT_INV_UI_FIELDS parameter to be configured at corp_id level.

PRESENT-INVOICE file format needs to be in CSV file format. The file can have title for each column, in such case, it needs to be configured at corp_id level to say how many rows to be ignored with the parameter key PRESENT_INV_SKIP_LINES.

Below table provides the list of fields that can be included in the file. If any field value needs to be populated with static value by default, then it can be configured at corp_id level.

In case, Merchant csv file does not follow the field order as per below table, field order of merchant file can be configured at corp_id level. Even few optional fields can be configured as mandatory.

Seq Num Field Name M/O/C Type & Length Remarks
L1 Invoice Type M X(20)

Type of line item, eg. INVOICE, CREDIT NOTE, CREDIT VOUCHER, etc.

Merchant can retain same Type value as familiar for their payers. Each Merchant-specific-Type will be mapped to the following standard Type of Straight2Bank Pay to compute the total payable amount:

INVOICE (included in payable amount)

DEBITNOTE (included in payable amount)

CREDITNOTE (subtracted from payable amount)

L2 Date1 M Date

Date of the line item.

Format: ddMMyyyy. (other date format is supported with a configuration)

Eg: 01062022 to represent 01st June 2022.

L3 Date2 O Date

Additional Date of the line item (Eg. Due Date).

Format: ddMMyyyy.

Eg: 01062022 to represent 01st June 2022.

L4 Date3 O Date

Additional Date of the line item.

Format: ddMMyyyy.

Eg: 01062022 to represent 01st June 2022.

L5 Payer Reference 1 M X(100)

Payer Reference 1 to 5 fields to be used to provide the data that is known to the payer or Merchant to communcate to the payer. Eg. Payer ID or Dealer ID or Agent ID or Vendor ID, etc.

Merchant can decide how many Payer Reference fields will be used to validate the payer.

Payer will be prompted in 'Invoice Presentment' screen to enter the value for all enabled Reference fields. The Invoice line itmes that are matching with the data entered by Payer will be presented to the payer.

L6 Payer Reference 2 M X(100)

Payer Reference 1 to 5 fields to be used to provide the data that is known to the payer or Merchant to communcate to the payer. Eg. Payer Name or Dealer Name or Agent Name or Vendor Name, etc.

Merchant can decide how many Payer Reference fields will be used to validate the payer.

Payer will be prompted in 'Invoice Presentment' screen to enter the value for all enabled Reference fields. The Invoice line itmes that are matching with the data entered by Payer will be presented to the payer.

L7 Payer Reference 3 O X(100)

Payer Reference 1 to 5 fields to be used to provide the data that is known to the payer or Merchant to communcate to the payer. Eg. Location, Biz Unit Name, etc

Merchant can decide how many Payer Reference fields will be used to validate the payer.

Payer will be prompted in 'Invoice Presentment' screen to enter the value for all enabled Reference fields. The Invoice line itmes that are matching with the data entered by Payer will be presented to the payer.

L8 Payer Reference 4 O X(100)

Payer Reference 1 to 5 fields to be used to provide the data that is known to the payer or Merchant to communcate to the payer.

Merchant can decide how many Payer Reference fields will be used to validate the payer.

Payer will be prompted in 'Invoice Presentment' screen to enter the value for all enabled Reference fields. The Invoice line itmes that are matching with the data entered by Payer will be presented to the payer.

L9 Payer Reference 5 O X(100)

Reference 1 to 5 fields to be used to provide the data that is known to the payer or Merchant to communcate to the payer. Eg. Location, Biz Unit Name, etc

Merchant can decide how many Payer Reference fields will be used to validate the payer.

Payer will be prompted in 'Invoice Presentment' screen to enter the value for all enabled Reference fields. The Invoice line items that are matching with the data entered by Payer will be presented to the payer.

L10 Invoice Number M X(100)

Invoice number or Credit Note number , etc.

It needs to be unique at Payer level.

L11 Invoice Description O X(100) Further details of Invoice.
L12 Country Code M X(2) Country Code of Invoice.
L13 Currency M X(3) Currency Code of Invoice.
L14 Invoice Amount M N(16, 3) Amount of Invoice. No negative sign is allowed.
L15 Invoice Amount 1 O N(16, 3) Other amount of Invoice (like Due Amount or Gross Amount or WHT Amount or VAT, or GST, etc). No negative sign is allowed.
L16 Invoice Amount 2 O N(16, 3) Other amount of Invoice (like Due Amount or Gross Amount or WHT Amount or VAT, or GST, etc). No negative sign is allowed.
L17 Invoice Amount 3 O N(16, 3) Other amount of Invoice (like Due Amount or Gross Amount or WHT Amount or VAT, or GST, etc). No negative sign is allowed.
L18 Invoice Amount 4 O N(16, 3) Other amount of Invoice (like Due Amount or Gross Amount or WHT Amount or VAT, or GST, etc). No negative sign is allowed.

Sample PRESENT_INVOICE File

Input File

Type, Date1, Date2, Date3, Ref1, Ref2, Ref3, Ref4, Ref5, Document Number, Description, Country,Currency, Amount, Amount1, Amount2, Amount3, Amount4
INVOICE,24032022,24042022,,1002345,XYZ COMPANY LIMITED,,,,100100,PO 123,SG,SGD,100.00,,,,
DEBIT NOTE,24032022,24052022,,1002345,XYZ COMPANY LIMITED,,,,DN100100,PO 123 - ADJ,SG,SGD,50.00,,,,
CREDIT NOTE,24032022,24042022,,1002345,XYZ COMPANY LIMITED,,,,CN100100,PO 123 - REV DN,SG,SGD,50.00,,,,
CREDIT VOUCHER,01062022,01072022,,1002345,XYZ COMPANY LIMITED,,,,CV100100,PO 123 - DISCOUNT,SG,SGD,20.00,,,,
INVOICE,24032022,24052022,,1002345,XYZ COMPANY LIMITED,,,,100120,PO 100,SG,SGD,200.00,,,,
INVOICE,24032022,24052022,,1002345,XYZ COMPANY LIMITED,,,,100150,PO 103,SG,SGD,0.03,,,,
INVOICE,24032022,24052022,,1002345,XYZ COMPANY LIMITED,,,,100160,PO 104,SG,SGD,0.02,,,,
INVOICE,24032022,24052022,,1002345,XYZ COMPANY LIMITED,,,,100170,PO 105,SG,SGD,0.01,,,,
INVOICE,24032022,24052022,,1002345,XYZ COMPANY LIMITED,,,,100180,PO 106,SG,SGD,0.01,,,,
INVOICE,24032022,24052022,,1002345,XYZ COMPANY LIMITED,,,,100190,PO 107,SG,SGD,0.01,,,,
CREDIT NOTE,24032022,24042022,,1002345,XYZ COMPANY LIMITED,,,,CN100120,PO 100 - DISCOUNT,SG,SGD,20.00,,,,
CREDIT NOTE,24032022,24042022,,1002345,XYZ COMPANY LIMITED,,,,CN100160,PO 104 - DISCOUNT,SG,SGD,0.01,,,,
INVOICE,01062022,01072022,,2002345,AAA COMPANY LIMITED,,,,200100,PO 123,SG,SGD,100.00,,,,
INVOICE,01062022,24052022,,2002345,AAA COMPANY LIMITED,,,,200120,PO 789,SG,SGD,10.00,,,,
INVOICE,01062022,24052022,,2002345,AAA COMPANY LIMITED,,,,200130,PO 111,SG,SGD,5.00,,,,
DEBIT NOTE,01062022,24052022,,2002345,AAA COMPANY LIMITED,,,,DN200100,PO 123 - ADJ,SG,SGD,10.00,,,,
CREDIT NOTE,01062022,01072022,,2002345,AAA COMPANY LIMITED,,,,CN200100,PO 123 - REV DN,SG,SGD,10.00,,,,
CREDIT VOUCHER,01062022,01072022,,2002345,AAA COMPANY LIMITED,,,,CV200100,PO 123 - DISCOUNT,SG,SGD,50.00,,,,

Output File

Type, Date1, Date2, Date3, Ref1, Ref2, Ref3, Ref4, Ref5, Document Number, Description, Country,Currency, Amount, Amount1, Amount2, Amount3, Amount4,REJECTED REASON
INVOICE,24032022,24052022,,1002345,XYZ COMPANY LIMITED,,,,100150,PO 103,SG,SGD,0.03,,,,,Failed capturing Invoice
INVOICE,24032022,24052022,,1002345,XYZ COMPANY LIMITED,,,,100150,PO 103,SG,SGD,,,,,,Invalid Amount

Transaction Report with Invoice

Transaction Report includes Invoice line items for the Transactions that are initiated from 'Invoice Presentment' module of Straight2Bank Pay. This report can be further customized to remove field title or to remove certain fields.

Sample default Transaction Report:

Record, Corp ID,Country Code,PSP ID,Transaction Type,Reference 1,Reference 2,Reference 3,Reference 4,Reference 5,Unique Reference,Currency Code,Amount,S2BPay AssignedTransaction ID,Partner assigned transaction ID,Status Date Time,Status,Status Remarks,Refund Parent Transaction ID,Payer Account,Payer Bank Code,Payer Name,Client Identity,Pre-auth Amount,GST Amount,Tax Amount,Charge Amount,Net Amount,Total Charge Amount
P,S2BPAY04,SG,SGPAYNOW,NEW,1002345,XYZ COMPANY LIMITED,,,,22003039657,SGD,0.01,22003039657,C100092760951,2022-03-24,CREDITED,,,,DBSSSGSGBRT,NOORULLAH,,,,,,,
Record,Corp ID,S2BPay AssignedTransaction ID,Invoice Type,Reference 1,Reference 2,Reference 3,Reference 4,Reference 5,Country,Currency Code,Amount,DocumentNumber,Description,Status,Date1,Date2,Date3,Amount1,Amount2,Amount3,Amount4
I,S2BPAY04,22003039657,CREDIT NOTE,1002345,XYZ COMPANY LIMITED,,,,SG,SGD,0.02,CR100300,PROMOTION ORDER - CREDIT NOTE,PAID,2021-12-26,2021-12-26,,,,,
I,S2BPAY04,22003039657,INVOICE,1002345,XYZ COMPANY LIMITED,,,,SG,SGD,0.03,100150,ADHOC ORDER 2,PAID,2021-12-26,2021-12-26,,,,,

Manual Steps to upload PRESENT_INVOICE file via Straight2Bank Web

Steps to upload bulk generate-link file manually via Straight2Bank Web portal:
  1. Login to Straight2Bank Web.
  2. Navigate to the menu as shown below.

    PresentInvFileStep2

  3. Choose S2BPAY from 'FILE UPLOAD' dropdown list box, PRESENT-INVOICE from 'DATA TEMPLATE / FILE FORMAT' dropdown list box, choose the file to be uploaded in 'UPLOAD FILE' and click on 'CONTINUE' button.

    PresentInvFileStep3

  4. Enter the Challenge Code into Vasco token and enter the Response code back on the screen as shown below.

    PresentInvFileStep4


eMandate Report

This report can be configurable at Merchant Profile level with a timing, to generate a report with the details of eMandate authorized via Straight2Bank Pay.

Seq Num Field Name M/O/C Type & Length Column Title Remarks
D1 Record M X(1) Record Identifier "M"
D2 Corp ID M X(8) Corp ID Corp ID of Merchant
D3 Payer ID M X(50) Payer ID Payer ID to uniquely identify the payer in merchant's system
D4 Type M X(30) Mandate Type Possible value: MANDATE
D5 Reference 1 O X(250) Ref 1 Reference 1 as provided by Merchant.
D6 Reference 2 O X(250) Ref 2 Reference 2 as provided by Merchant.
D7 Reference 3 O X(250) Ref 3 Reference 3 as provided by Merchant.
D8 Reference 4 O X(100) Ref 4 Reference 4 as provided by Merchant.
D9 Reference 5 O X(250) Ref 5 Reference 5 as provided by Merchant.
D10 Reference 6 O X(250) Ref 6 Reference 6 as provided by Merchant.
D11 Reference 7 O X(250) Ref 7 Reference 7 as provided by Merchant.
D12 Reference 8 O X(250) Ref 8 Reference 8 as provided by Merchant.
D13 Reference 9 O X(250) Ref 9 Reference 9 as provided by Merchant.
D14 Reference 10 O X(250) Ref 10 Reference 10 as provided by Merchant.
D15 Transaction Reference M X(100) Transaction Reference Transaction reference created by Straight2Bank Pay for this mandate
D16 Country Code M X(2) Country Code 2-character country code.
D17 Currency Code M X(3) CCYCODE 3-character currency code.
D18 Payment Method M X(8) Payment Method Payment Service Provider ID. S2BPay assigns 8 characters code for each Payment Method. Eg: SG: SGPAYNOW, SGENETS1, SGFDMS01
D19 Mandate Reference M N(14) Mandate Reference Mandate Reference created by Straight2Bank Pay for this mandate
D20 Maximum Amount O N(18,5) Maximum Amount Maximum Amount authorised by user for this mandate
D21 Mandate Valid From O X(10) From Date

Date from which this mandate is valid

Format: YYYY-MM-DD

D22 Mandate Expiry Date O X(10) To Date

Date till which this mandate is valid

Format: YYYY-MM-DD

D23 Segment O X(50) Segment "Retail" or "Corporate"
D24 Payer Name O X(50) Payer Name Payer Name if available.
D25 Payer Bank Code O X(50) Payer Bank Code Payer Bank Code if available.
D26 Payer Account O X(35) Payer Account Payer Account if available.
D27 Status M X(50) Status Possible values: PENDING, SUCCESS, CANCELLED, FAIL, AUTHORIZED
D28 Status Remarks O X(250) Status Remarks Remarks on status if available.
D29 Default Flag M X(1) Default Flag

Possible values: Y, N

Default flag chosen by user in case of multiple mandates for a payerid

In case of only one mandate present for a payerid, that mandate will have value as Y by default

D30 Created Date Time M X(19) Created Date

Date Time on which the Mandate is created. Date is in GMT+08:00 time zone.

Format : YYYY-MM-DD HH:Mi:SS

D31 Updated Date Time M X(19) Updated Date

Date Time on which the Mandate is updated recently. Date is in GMT+08:00 time zone.

Format : YYYY-MM-DD HH:Mi:SS

Sample eMandate Report:

"Record","Corp ID","Payer ID","Type","Reference 1","Reference 2","Reference 3","Reference 4","Reference 5","Reference 6","Reference 7","Reference 8","Reference 9","Reference 10","Transaction Reference","Country","Currency Code","Payment Method","Mandate Reference","Maximum Amount","Mandate Valid From","Mandate Expiry Date","Segment","Payer Name","Payer Bank Code","Payer Account","Status","Status Remarks","Default Flag","Created Date Time","Updated Date Time"
M,S2BPAY03,2023020902,MANDATE,2023020902,Ploen02,2023020902,,,,,,,,BODHL0524Z01DHL20230210022130000214,SG,SGD,SGRTDDI1,2023020902,3,2023-02-10,2023-03-31,Retail,Ploen02,SCBLSG22XXX,6209564988,SUCCESS,,N,2023-02-10 02:21:30,2023-02-10 02:25:08
M,S2BPAY03,2023020902,MANDATE,2023020902,Ploen02,2023020902,,,,,,,,BODHL0524Z01DHL20230210055841000259,SG,SGD,SGRTDDI1,2023020902,3,2023-02-10,2023-04-30,Retail,Ploen02,SCBLSG22XXX,0128034688,CANCELLED,,N,2023-02-10 05:58:41,2023-02-10 06:01:33

Appendix

Possible Values for 'status'

Service Possible Status

Notification Request (Straight2Bank Pay to Merchant Server)

For NEW Transaction:

  • SUCCESS or SUCCESSFUL or PRE_AUTHORIZED

For REFUND Transaction:

  • SUCCESS or SUCCESSFUL
  • FAILED or REJECTED or UNSUCCESSFUL

bCollect Response (Straight2Bank Pay to Merchant Server via user's browser)

Or

Possible value as part of browser re-direction to rurl (applicable for bcollect and s2bpay.js)

For NEW transaction:

  • SUCCESS or SUCCESSFUL
  • FAILED or REJECTED or UNSUCCESSFUL
  • PENDING

Query Response (Straight2Bank Pay to Merchant)

For NEW Transaction:

  • SUCCESS or SUCCESSFUL
  • REJECTED or UNSUCCESSFUL or FAILED
  • ERROR
  • PENDING
  • CREDIT_INITIATED
  • CREDIT_FAILED
  • CREDITED
  • VOIDED
  • PRE_AUTHORIZED

For REFUND Transaction:

  • SUCCESS or SUCCESSFUL
  • PENDING
  • REJECTED or UNSUCCESSFUL or FAILED
  • ERROR

For VOID Transaction:

  • SUCCESSFUL
  • VOID_FAILED

Collect Response (Straight2Bank Pay to Merchant Server)

For NEW Transaction:

  • PENDING
  • ERROR

Refund Response (Straight2Bank Pay to Merchant Server)

For REFUND Transaction:

  • ACCEPTED
  • ERROR
  • VOID_FAILED
  • SUCCESSFUL

PostAuth Response(Straight2Bank Pay to Merchant Server)

For NEW Transaction:

  • SUCCESS or SUCCESSFUL
  • REJECTED or FAILED
  • ERROR
  • PENDING
  • PARTNER_ERROR

Generation of Digital Signature

In all Request message from Merchant Server, digital signature is mandatory as part of the payload, payload needs to be signed using Merchant's private key using RS256 algorithm. This section provides how to create digital signature for Query API as an example:

  1. Form the key-value pair for all non-empty field values and sort the key-value pair based on the key in alphabetical order. Then concatenate the sorted key-value pair with a delimiter "&". corpid=CUIMOMO1&corpref=9999999991&datetime=10012018103420
  2. Pass this string to RS256 algorithm to get the value that needs to be populated for key 'sign' in all API request.

corpid=CUIMOMO1&corpref=9999999991&datetime=10012018103420&sign=u3nTf91HKNLzJrDhnglqUb58bknWLhxcyxyDAcYKOaGhGiCVuaFSBCvtjzekA112n7Akpdzxt2ZjFA93UY4dw9X5x1MiKn2ZXZNV5pZbyCaWX/id0SYGNbi11nWleSsNJ8qwHlpHz4yvrCuvTJlWTdG4kVHFFaQJ1S1Tyz98rF6tSAuF/N1DBTD2GvENA4xyhnhp0B41vsqCBVHWIyt6pSj71hIpo0dmPj1Kpywt2O1SySDQr/bxCOFN1iNWcr1/RgPASlM1id9oxyuRF5zNmRyQfLMwGuCg42KqGF1WUSZGZt4Ma40dYzxaLDfjJTM038doIDeaKKIeeW7H6Xmq9w==

Sample Java Code to generate digital signature:

							//sort the key value pair
public static String sortParameterString(String args[]){
  StringBuilder parameterString = new StringBuilder("");
  try{
       Arrays.sort(args);
       for (int counter=0; counter < args.length; counter++) {
              parameterString.append(args[counter]);
              if (counter != args.length-1) parameterString.append("&");
       }
  }
  catch(Exception e){
      //do catch code
  }
  return parameterString.toString();
}
//RS256 Signing
public static String doRSASHA256Signing(String plainText, String privateKeyStr, String password) throws Exception {
   EncryptedPrivateKeyInfo ePKInfo = new EncryptedPrivateKeyInfo(Base64.decodeBase64(privateKeyStr.getBytes()));
   Cipher cipher = Cipher.getInstance(ePKInfo.getAlgName());
   PBEKeySpec pbeKeySpec = new PBEKeySpec(password.toCharArray());
   SecretKeyFactory skFac = SecretKeyFactory.getInstance(ePKInfo.getAlgName());
   Key pbeKey = skFac.generateSecret(pbeKeySpec);
   AlgorithmParameters algParams = ePKInfo.getAlgParameters();
   cipher.init(Cipher.DECRYPT_MODE, pbeKey, algParams);
   KeySpec pkcs8KeySpec = ePKInfo.getKeySpec(cipher);
   PrivateKey privateKey = KeyFactory.getInstance("RSA").generatePrivate(pkcs8KeySpec);
   Signature signature = Signature.getInstance("SHA256withRSA");
   signature.initSign(privateKey);
   signature.update(plainText.getBytes());
   return new String(Base64.encodeBase64(signature.sign()));
}

						

Verification of Hash Value

In all notification and response messages from Straight2Bank Pay, security attribute 'hash' key is included as part of payload. Merchant is expected to validate the hash value to make sure no one has tampered with the payload during transmission.

Steps to be followed to validate the 'hash' value:

  1. Decrypt the payload using random key that has been sent in the message. After decryption, ensure that the resultant key value pair is sorted in alphabetical order.
  2. Encrypted

    vYusFLuU5LtOwTU1GOVz58xFvbxnCC3Gw/vk67zzGQe3MW4iE5fsDSmVcCp3CIktHaGD7ud3uN+1UMhTiPxJmxvGmcVwSrCo3GNXmFnhxyMyAk8hF87P5ixEZXVvTzZTnzKvJOrocaNvy6z8rcgao5L11v7lyLuxEmqI0VMTMiBuethINqdLw4Gvl+pYma4mpLyvR63xczQleSQEeLhseVBowKIcA37XLggUVZL04f/zLVGI7WurX96sNfqCXQDrud08K6G+Xb4eR3COjhd1UIWmkoUwUpDqmCCZfi/Ybys4ft/o9WPzYIkzmUQIOn1YHsLeU7DN5jLNzdcWjvLAahXcz+aQDa1JkuJVqzaw2L2GrJOt3hISxsh4A9pOV0KpFZh+qb/I+UHbWiCRBDksdQ==

    Decrypted

    ack=PASS&amt=10000.00&ccy=VND&corpid=CUIMOMO1&corpref=7000082842&ctry=VN&date=10012018104609&optxnid=131761303&ref1=test1&ref2=test2&ref3=test3&ref4=test4&status=SUCCESSFUL&statusdesc=RECONCILED&txnid=7000082842&txntype=NEW&hash=563A18112C42882DA15ADDF5AC22E4CCA6B3CC1E42C09A8BB01C4E66D1E5E714

    String to be used for hash verification (same as decrypted string except hash key and its value):

    ack=PASS&amt=10000.00&ccy=VND&corpid=CUIMOMO1&corpref=7000082842&ctry=VN&date=10012018104609&optxnid=131761303&ref1=test1&ref2=test2&ref3=test3&ref4=test4&status=SUCCESSFUL&statusdesc=RECONCILED&txnid=7000082842&txntype=NEW

  3. Pass the above string to HMAC-SHA256 algorithm (with Shared Secret Key) to get the value of hash value. Compare this hash value against the hash-value received in the payload from Straight2Bank Pay server. If both are not the same, then the message needs to be rejected and response message needs to be sent back to Straight2Bank Pay server as 'Hash Error'.

AES256 encryption/decryption

In all Request and Response message of each API or Java Script Plugin, the payload is encrypted using 'Secret Key' or random key. Merchant needs to build a function to decrypt a payload that comes from Straight2Bank Pay server and also encrypt the payload that needs to be sent to Straight2Bank Pay.

Sample Java code to do encrypt and descript using AES-256 CBC algorithm:

							public class EncryptUtil {
       static final int gcmIVSize = 12;
       public static String doAES256CBCEncryption(String raw, String key) throws InvalidKeyException,
                     NoSuchAlgorithmException, NoSuchPaddingException, InvalidAlgorithmParameterException,
                     IllegalBlockSizeException, BadPaddingException, UnsupportedEncodingException {
              byte[] ivBytes=new byte[gcmIVSize];
                                    new SecureRandom().nextBytes(ivBytes);
                                    final Cipher cipher = generateCBCCipher(key, 1, ivBytes);
                                    byte[] enc = cipher.doFinal(raw.getBytes(StandardCharsets.UTF_8));
                                    byte[] combined= ArrayUtils.addAll(ivBytes,enc);
                                    return Base64.encodeBase64String(combined);
       }
       public static String doAES256CBCDecryption(String encrypted, String key) throws InvalidKeyException,
                     NoSuchAlgorithmException, NoSuchPaddingException, InvalidAlgorithmParameterException,
                     IllegalBlockSizeException, BadPaddingException, UnsupportedEncodingException {
              byte[] combined= Base64.decodeBase64(encrypted);
                                    byte[] ivBytes= ArrayUtils.subarray(combined,0,gcmIVSize);
                                    byte[] enc=ArrayUtils.subarray(combined,gcmIVSize,combined.length);
                                    final Cipher cipher = generateCBCCipher(key, 2, ivBytes);
                                    return new String(cipher.doFinal(enc));
       }
       private static Cipher generateCBCCipher(String key, int mode,byte[] IV)
                     throws NoSuchAlgorithmException, NoSuchPaddingException, InvalidKeyException,
                     InvalidAlgorithmParameterException, UnsupportedEncodingException {
              GCMParameterSpec iv = new GCMParameterSpec(128,IV);
              String newKey = key.toUpperCase();
              Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
              SecretKeySpec secretKeySpec = new SecretKeySpec(newKey.getBytes(), "AES");
              if (mode == 1)
                     cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, iv);
              else if (mode == 2)
                     cipher.init(Cipher.DECRYPT_MODE, secretKeySpec, iv);
              return cipher;
       } }
						

Sample Codes for Python can be retrieved from:

https://test-s2bpay.sc.com/s2bpaysit/resources/merchant/samples/python

Sample Codes for 'C Sharp' - C# can be retrieved from:

https://test-s2bpay.sc.com/s2bpaysit/resources/merchant/samples/csharp


RSA 2048 encryption/decryption

For the payloads sent by S2BPAY, the string is encrypted with AES-256 Algorithm using Random Key. The Random key is encrypted with RSA 2048 using Merchant's Public Key.

Sample Java code to do encrypt and descript using RSA 2048 algorithm:

							public static String encryptRsaWithPublicKey(String plainText, String publicKeyString) {
	try {
		X509EncodedKeySpec keySpecPv = new X509EncodedKeySpec(Base64.decodeBase64(publicKeyString.getBytes()));
		PublicKey publicKey = KeyFactory.getInstance("RSA").generatePublic(keySpecPv);
		final Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding");
		cipher.init(Cipher.ENCRYPT_MODE, publicKey);
		byte[] enc = cipher.doFinal(plainText.getBytes());
		return DatatypeConverter.printBase64Binary(enc);
	} catch (Exception e) {
		System.out.println(e);
		throw new RuntimeException();
	}
}

public static String decryptRsaWithPrivateKey(String encryptedString, String privateKeyString, String password) {
try {
      EncryptedPrivateKeyInfo ePKInfo = new EncryptedPrivateKeyInfo(Base64.decodeBase64(privateKeyString.getBytes()));
      Cipher cipher = Cipher.getInstance(ePKInfo.getAlgName());
      PBEKeySpec pbeKeySpec = new PBEKeySpec(password.toCharArray());
      SecretKeyFactory skFac = SecretKeyFactory.getInstance(ePKInfo.getAlgName());
      Key pbeKey = skFac.generateSecret(pbeKeySpec);
      AlgorithmParameters algParams = ePKInfo.getAlgParameters();
      cipher.init(Cipher.DECRYPT_MODE, pbeKey, algParams);
      KeySpec pkcs8KeySpec = ePKInfo.getKeySpec(cipher);
      PrivateKey privateKey = KeyFactory.getInstance("RSA").generatePrivate(pkcs8KeySpec);
      final Cipher cipher1 = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding");
      cipher1.init(Cipher.DECRYPT_MODE, privateKey);
      return new String(cipher1.doFinal(DatatypeConverter.parseBase64Binary(encryptedString)));
      } catch (Exception e) {
             System.out.println(e);
	      throw new RuntimeException();

      }
}
						

Key Pair Generation

As part of on-boarding process or testing process, Merchant is expected to generate key pair using the following steps:

  1. Command to generate the private key:

    openssl genrsa -aes256 -passout pass:{password to protect the Private Key} -out {location of private key file} 2048

  2. Following command to generate private key in pkcs8 format which needs to be used in the coding:

    openssl pkcs8 -in {location of private key file} -topk8 -out {location of pkcs8 private key file} -v1 PBE-SHA1-3DES

    • Enter the password used in Command 1 when prompted : Enter pass phrase for privatekey file.
    • Then Enter a new password to encrypt this pkcs8 private key file when asked: Enter Encryption Password, and Confirm the password. This password to be used every time this private key is used via code.
  3. Following command to generate public key from pkcs8 private key:

    openssl rsa -pubout -in {location of pkcs8 private key file} -out {location of output public key file}

    • Enter the password used to encrypt pkcs8 private key when prompted : Enter pass phrase for "pkcs8 private key file"

Public Key:

  • Public key to be shared with Bank to configured in Merchant's Profile.
  • Straight2Bank Pay will make use of this key to verify the digital signature that is received as part payload in request message from Merchant.
  • Straight2Bank Pay will make use of this key to encrypt the random key and populate in 'enc_key' element of the message in response or notification messages from Straight2Bank Pay server to Merchant server.

Private Key:

  • Merchant needs to maintain private key safely within their application. It should not be shared with any party and it should not be made public.
  • Merchant needs to use private key to generate digital signature in all Request message to Straight2Bank Pay server.
  • Merchant needs to use private key to decrypt 'enc_key' element of the message from Straight2Bank Pay server, to obtain the random key.

Browser Support

Straight2Bank Pay supports the following browser versions:

Browser Version
Internet Explorer 11+
Chrome 36+
FireFox 27+
Opera 23+
Safari 9+
Android Webview Android 4.4.2 or higher


JWE Encryption and Decryption

For APIs where JWE security is used, clients to encrypt using Straight2Bank Pay's public key for encryption. Upon receiving the response, JWE string to be decrypted using Merchant's Private Key.

Sample Java code to Encrypt JWE and Decrypt JWE:

								import org.jose4j.jwa.AlgorithmConstraints;
import org.jose4j.jwa.AlgorithmConstraints.ConstraintType;
import org.jose4j.jwa.AlgorithmConstraints;
import org.jose4j.jwe.ContentEncryptionAlgorithmIdentifiers;
import org.jose4j.jwe.JsonWebEncryption;
import org.jose4j.jwe.KeyManagementAlgorithmIdentifiers;

       public static String getEncryptedJWE(String scbPublicKey, String jws) {
             try {
X509EncodedKeySpec keySpecPv = new X509EncodedKeySpec(Base64.decodeBase64(scbPublicKey.getBytes()));
                  RSAPublicKey publicKey = KeyFactory.getInstance("RSA").generatePublic(keySpecPv);
                    JsonWebEncryption jwe = new JsonWebEncryption();
                    jwe.setEncryptionMethodHeaderParameter("A256GCM");
                    jwe.setKey(publicKey);
                    jwe.setAlgorithmHeaderValue("RSA-OAEP-256");
                    jwe.setPayload(jws);
                    return  jwe.getCompactSerialization();
             } catch (Exception e) {
                    log.error("Error encrypting JWS...");
             }
       }

       public static String doJWEDecrypt(String payload,String  privateKeyStr) {
             try {

                    KeyFactory keyFactory = KeyFactory.getInstance("RSA");
                    byte privateKeyBytes[] = Base64.decodeBase64(privateKeyString);
                    PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(
                                 privateKeyBytes);
                    RSAPrivateKey  rsaPrivateKey = (RSAPrivateKey) keyFactory.generatePrivate(keySpec);

                    JsonWebEncryption receivedJwe = new JsonWebEncryption();
                    AlgorithmConstraints algConstraints = new AlgorithmConstraints(ConstraintType.WHITELIST, KeyManagementAlgorithmIdentifiers.RSA_OAEP_256);
                    receivedJwe.setAlgorithmConstraints(algConstraints);
                    AlgorithmConstraints encConstraints = new AlgorithmConstraints(ConstraintType.WHITELIST, ContentEncryptionAlgorithmIdentifiers.AES_256_GCM);
             receivedJwe.setContentEncryptionAlgorithmConstraints(encConstraints);

                    receivedJwe.setKey(privateKey);
                    receivedJwe.setCompactSerialization(payload);
                    log.info("Decrypted text: "+receivedJwe.getPayload());
                    return receivedJwe.getPayload();
             } catch(Exception e) {
                    log.error("Error decrypting JWE message.." + e.getMessage());
             }
       }
						

Generation and Verification of JWS:

Merchant to generate the JWS when preparing payload to send to Straight2Bank Pay. JWS contains 3 Parts - Header.Payload.Signature (delimited by dot(.)). The below codes are used to create Signature when preparing payload and to verify Signature when validating the response from Straight2Bank Pay.

Sample Java Code to Generate Signature:

								private String doRSASHA256Signing(String plainText, String privateKeyString) {
             try {
                    //Here plaintext is URL-Base64 encoded Header. URL-Base64 encoded Payload
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
                    byte privateKeyBytes[] = Base64.decodeBase64(privateKeyString);
                    PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(
                                 privateKeyBytes);
                    RSAPrivateKey  rsaPrivateKey = (RSAPrivateKey) keyFactory.generatePrivate(keySpec);
                    Signature signature = Signature.getInstance("SHA256withRSA");
                    signature.initSign(rsaPrivateKey);
                    signature.update(plainText.getBytes());
                    return new String(Base64.encodeBase64URLSafe(signature.sign()));
             } catch (Exception e) {
                    logger.error(e.getMessage());
             }
       }
						

Sample Java Code to Verify Signature:

								private boolean doRSASHA256Verifying(String plainText,
                    String signatureString, String scbPublicKey) {
             try {
                    //Here plaintext is Header.Payload value received
                    //Here signatureString is the signature received
X509EncodedKeySpec keySpecPv = new X509EncodedKeySpec(Base64.decodeBase64(scbPublicKey.getBytes()));
                  RSAPublicKey publicKey = KeyFactory.getInstance("RSA").generatePublic(keySpecPv);
                    Signature signature = Signature.getInstance("SHA256withRSA");
                    signature.initVerify(publicKey);
                    signature.update(plainText.getBytes());
                    return signature.verify(Base64.decodeBase64(signatureString));
             } catch (Exception e) {
                    logger.error(e.getMessage());
             }
       }
						

Public Key of Straight2Bank Pay

Test:

								MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3fPMGgPN79lmrN8P6OegcY9Z2QnM0C8UuVlZzFc4VPyQwzUlRY1UtENxb4g5QjqXu/MyH3F18mFss8u9ZI3o748+cyRwmY6Ru2JgRTYZczUine+nycWz41fJLNrqktAYQPGFTnWUTzd7c+Cv3CSVt4LKSxH1wVUlqeXTUiQGcw4haTawx56MaEHrjcx1dXMHT3VnaVdjoY2uSd9RKlN5wH51re3bUqKugAj06kjWKLXNyg2steYSWXEJ0i+uAD8j0t9umbSml8Pyaz8CBigMP+FGwdmYXvRxej7iL9DPGkklF+rbGHoBbvh48hJJoyrXAd0NFRCcfoCpAYMpexRE2wIDAQAB
						

Prod:

								MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArV40/7K7VlLpfnEZjqAX3LAlnPvjSRSAHcX6cLIxN3YRL/l834Tfg4EyLG/qEHEy6t4gyxcU7k1DTQhGLriRSKPcR36ZOZJBZs9G2wZZJDsgO172Fq6nBnzajUwBjNhuTCDoqFDLN+Rxo9hDSif3ogGnEptJe6iAemHKHSECuu0IEteqHVO1+GZehK4DZy4OdJffgqRi31lvJD8NKoWzCjwqxrZ5dPCv5EcBa6sbwhb+nnHh5/LLoiPYfT75J67/FCzcE0rVy+ePzbMPXxueG8TeKdA6l5BgiFuBetBuQn/3g+4aqHfrE/YLIVcMsPyRxKs5Iw1epuaUSGx6KU3TrQIDAQAB
						

Useful Tools

AES256 Encryption/Decryption

Input Fields

Please choose the required option:

Encryption Key
Clear Text Payload
Submit request
Output
Encrypted Payload

RSA Encryption/Decryption

Input Fields

Please choose the required option:

Please enter the key in single line removing -----BEGIN PUBLIC KEY----- -----END PUBLIC KEY-----

Public Key
Clear Text Payload
Submit request
Output
Encrypted Payload

RSA Sign Generation/Sign Verify

Input Fields

Please choose the required option:

Please enter the keys in single line removing -----BEGIN RSA PRIVATE KEY------ -----END RSA PRIVATE KEY-----

Private Key
Clear Text Payload
Signature to Verify
(Base64 encoded)
Submit request
Output
Signature (Base64 encoded)

JWE Encryption/Decryption

Input Fields

Please choose the required option:

Please enter the keys in single line removing -----BEGIN PUBLIC KEY----- -----END PUBLIC KEY-----

Public Key
Clear Text Payload
Submit request
Output
Encrypted Payload

Base64 Encode/Decode

Input Fields

Please choose the required option:

Clear Text Payload
Submit request
Output
Encrypted Payload

URI Encode/Decode

Input Fields

Please choose the required option:

Clear Text Payload
Submit request
Output
Encrypted Payload