Generic Payment Integration Platform - Custom Payment Gateway

Custom Gateway provided by Cornestone's Generic Payment Integration Platform (GP-IP) is a payment gateway integration that allows integration with a wide variety of payment gateways. It is an open ended Integration which can be configured to work with any 3rd party application or customer hosted middleware/application or a payment gateway. It facilitates customized integration of Payment and Refund processing for Extended Enterprise customers.

Note: This application integrated with Custom Gateway is referred as middleware from here on.

Payment Flow

Following configuration can be specified for a payment processing.

Payment Configurations

Below table explains various configurations available for configuring a payment flow.

Configuration	Required	Description
Payment Section
Payment Redirect URL	Yes	Middleware URL to redirect the user to make a payment. It must be a secure HTTP URL (i.e. https://).
Redirection Type	Yes	It defines how data is sent to middleware. It can be set to either HttpPost or QueryString.
Payment Redirection Request Parameters	No	It can be used to provide a fixed set of key=value pairs that would be sent along with each payment request to the middleware. Ensure that the key=value pairs are comma-separated.
Payment Redirection Request Parameter Key Map	No	If middleware expects fields to be received with different names, this configuration can be used to specify the mapping. It supports mapping of Main Payment Request Fields. For example, refer to Scenario 3 - With Request parameter mapping for usage.
Payment Redirection Response Parameter Key Map	No	If middleware is going to return fields with different names, this configuration can be used to specify the mapping. It supports mapping of Payment Response Fields. For example, refer to Scenario 3 - Sending data as Pending with Response parameter mapping for usage.
Send Billing Address	No	Select this if Billing Address fields need to be sent to middleware as a part of the payment request.
Billing Address Key Map	No	Use this configuration if middleware expects a different name for Billing Address Fields.
Send Shipping Address	No	Select this if Shipping Address fields need to be sent to middleware as a part of the payment request.
Shipping Address Key Map	No	Use this configuration if middleware expects a different name for Shipping Address Fields.
Send Cart Items	No	Select this if Cart Item details need to be sent to middleware as a part of the payment request.
Send Custom Fields	No	Select this if Custom Field details need to be sent to middleware as a part of the payment request.
Common Section
Secret Key	Yes^#	This secret key is used for SHA256 hashing of the payload which is sent 'To' and 'From' Cornerstone to the middleware. Hashing is important to ensure the integrity of the message exchanged.
Success Code	Yes	Specify the value sent by middleware to indicate that the payment or refund is successful.
Pending Code	No	Use this if middleware needs to support delayed confirmation. Specify the value sent by middleware to indicate that the payment or refund is not yet successful but is in a pending confirmation state.

# - If you need to bypass this Secret Key configuration (not recommended), refer to product help documentation.

Once payment is initiated from Cornerstone to middleware, fields decribed in following section are posted based on configuration specified.

If "Redirection Type" is set as "HttpPost", all the fields are POSTed to the URL specified in "Payment Redirection URL" field.
If "Redirection Type" is set as "QueryString", all the fields are appened as query string to the URL specified in "Payment Redirection URL" field. Individual field values are Url encoded before sending. For example, space is replaced by '+' sign.

Along with below listed fields, additional fields can be sent to middleware by specifying key=value pairs in "Payment Redirection Request Parameters" field.

Once payment is completed, middleware should redirect User back to the URL provided in the "return_url" field. Middleware should also send additional fields as described in Payment Response Fields

Payment Request Fields

Following set of fields are sent to middleware as a part of payment request.

Main Payment Request Fields

These fields are always sent in the Payment request.

Use "Payment Redirection Request Parameter Key Map" to map below field names to corresponding middleware parameter name.

Field	Description
cart_id	Cart Id. It is only present for Cart based payments.
unique_id	Unique Identifier. It is used for identifying a transaction uniquely. It is 20 characters long.
currency	3 digit ISO Currency Code in upper case e.g. USD, CAD, EUR etc.
amount	Total amount to be paid by the user. Inclusive of fee, tax, discount etc. Amount field is sent in format with at least 2 digits after decimal point.
tax	Sales Tax amount. Amount field is sent in format with at least 2 digits after decimal point.
fee	Total Fee amount including Processing Fee. Amount field is sent in format with at least 2 digits after decimal point.
locale	Locale code e.g. en-US
return_url	Dynamically generated URL (along with query parameter) where middleware should redirect user back after payment is completed.
logo_url	Logo URL of customer logo that can be used to display on payment page.
tu_purchase	If it is a Training Unit purchase, it is sent to "true", otherwise "false"
signature	This is a dynamically calculated field. It is calculated by Hashing payload of all other key=value pairs without any delimiter. `signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase()` Refer to Payment Redirection Examples for details.

Billing Address Fields

These fields are sent in the Payment request only if "Send Billing Address" is selected.

Use "Billing Address Key Map" to map below field names to corresponding middleware parameter name.

Field	Description
b_title	Title/Salutation. It can have maximum of 100 characters.
b_fname	First Name. It can have maximum of 200 characters.
b_lname	Last Name. It can have maximum of 200 characters.
b_email	Email Address. It can have maximum of 100 characters.
b_phone	Phone Number. It can have maximum of 50 characters.
b_company	Company Name. It can have maximum of 100 characters.
b_addr1	Address Line 1. It can have maximum of 110 characters.
b_addr2	Address Line 2. It can have maximum of 55 characters.
b_city	City. It can have maximum of 35 characters.
b_state	State/Province Name. It can have maximum of 30 characters.
b_country	Country Name. It can have maximum of 100 characters.
b_zip	Zip/Postal Code. It can have maximum of 20 characters.

Shipping Address Fields

These fields are sent in the Payment request only if "Send Shipping Address" is selected.

Use "Shipping Address Key Map" to map below field names to corresponding middleware parameter name.

Field	Description
s_title	Title/Salutation. It can have maximum of 100 characters.
s_fname	First Name. It can have maximum of 200 characters.
s_lname	Last Name. It can have maximum of 200 characters.
s_email	Email Address. It can have maximum of 100 characters.
s_phone	Phone Number. It can have maximum of 50 characters.
s_company	Company Name. It can have maximum of 100 characters.
s_addr1	Address Line 1. It can have maximum of 110 characters.
s_addr2	Address Line 2. It can have maximum of 55 characters.
s_city	City. It can have maximum of 35 characters.
s_state	State/Province Name. It can have maximum of 30 characters.
s_country	Country Name. It can have maximum of 100 characters.
s_zip	Zip/Postal Code. It can have maximum of 20 characters.

Cart Item Fields

These fields are sent in the Payment request only if "Send Cart Items" is selected.

Based on number of items in cart, field name is suffixed with the number 'N', starting with 1.

Field	Description
qty-N	Quantity purchased
price-N	Price per item. Amount field is sent in format with at least 2 digits after decimal point.
loid-N	Training (learning object) Id. It can have maximum of 100 characters.
title-N	Training Title
subtotal-N	Total cost after discount and tax. Amount field is sent in format with at least 2 digits after decimal point.
total-N	Total cost after calculation of cost center, discount, processing fee, tax etc. Amount field is sent in format with at least 2 digits after decimal point.
discount-N	Discount. Amount field is sent in format with at least 2 digits after decimal point.
usage_type-N	defines Usage of purchase. Possible values are: 1 = Pay for Self 2 = Inventory Assignment 4 = Pre-purchase -1 = Training Unit Purchase
product_code-N	Product Code, applicable for Online Course and Material. It can have maximum of 20 characters.
billing_entity-N	Billing Entity
tax-N	Tax amount
provider-N	Training Provider Name. It can have maximum of 100 characters.

Custom Fields

These fields are sent in the Payment request only if "Send Custom Fields" is selected.

Based on number of custom fields, field name is suffixed with the number 'N', starting with 1.

Field	Description
cf_label-N	Custom Field Label. It can have maximum of 2000 characters.
cf_value-N	Custom Field Value. It can have maximum of 4000 characters.

Payment Redirection Examples

Scenario 1 - Basic payment request sent as Form Post

Suppose Configuration is done as follows,

Configuration Field	Value
Payment Redirect URL	`https://www.example.com/payment-redirect?source=csod.exe`
Redirection Type	`HttpPost`
SecretKey	`testSecretKey`

In this case, redirect URL would be, https://www.example.com/payment-redirect?source=csod.exe

And sample Form Post parameters would be,

Key	Value
`cart_id`	`12345`
`unique_id`	`20241216183904489836`
`currency`	`USD`
`amount`	`100.00`
`tax`	(empty value indicates no calculation of tax)
`fee`	`0.00`
`locale`	`en-US`
`return_url`	`https://portalname.csod.com/LMS/Ecom/PaymentProcessHandler.aspx?qs=Rdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQ`
`tu_purchase`	`false`
`signature`	`52BE459FED32567EEE17A403A7321E78B06DE914BACB6009A66F94492942B2EB`

Here, hash payload for signature calculation is,

cart_id=12345unique_id=20241216183904489836currency=USDamount=100.00tax=fee=0.00locale=en-USreturn_url=https://portalname.csod.com/LMS/Ecom/PaymentProcessHandler.aspx?qs=Rdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQtu_purchase=false

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. 52BE459FED32567EEE17A403A7321E78B06DE914BACB6009A66F94492942B2EB

Scenario 2 - Billing address and Cart Items sent as Query String

Suppose Configuration is done as follows,

Configuration Field	Value
Payment Redirect URL	`https://www.example.com/payment-redirect?source=csod.exe`
Redirection Type	`HttpPost`
SecretKey	`testSecretKey`
Send Billing Address	`Yes`
Send Cart Items	`Yes`

In this case, sample redirect URL would be,

https://www.example.com/payment-redirect?source=csod.exe&cart_id=12345&unique_id=20241216183904489836¤cy=USD&amount=100.00&tax=&fee=0.00&locale=en-US&return_url=https%3a%2f%2fportalname.csod.com%2fLMS%2fEcom%2fPaymentProcessHandler.aspx%3fqs%3dRdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQ&tu_purchase=false&b_title=Mr&b_fname=John&b_lname=Doe&b_email=john.doe@example.com&b_phone=1234567890&b_company=Example+Inc&b_addr1=123+Main+St&b_addr2=Apt+1&b_city=Anytown&b_state=California&b_country=United+States+Of+America&b_zip=12345&qty-1=2&price-1=50.00&loid-1=12345&title-1=Sample+Training&subtotal-1=100.00&total-1=100.00&discount-1=0.00&usage_type-1=1&product_code-1=&billing_entity-1=&tax-1=&provider-1=Training+Provider&signature=501A5189925EC99D8A2B6ABA1BC24FBD2F40DAFCAB55321FC61F38494F3222AD

Here, hash payload for signature calculation is,

cart_id=12345unique_id=20241216183904489836currency=USDamount=100.00tax=fee=0.00locale=en-USreturn_url=https://portalname.csod.com/LMS/Ecom/PaymentProcessHandler.aspx?qs=Rdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQtu_purchase=falseb_title=Mrb_fname=Johnb_lname=Doeb_email=john.doe@example.comb_phone=1234567890b_company=Example Incb_addr1=123 Main Stb_addr2=Apt 1b_city=Anytownb_state=Californiab_country=United States Of Americab_zip=12345qty-1=2price-1=50.00loid-1=12345title-1=Sample Trainingsubtotal-1=100.00total-1=100.00discount-1=0.00usage_type-1=1product_code-1=billing_entity-1=tax-1=provider-1=Training Provider

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. 501A5189925EC99D8A2B6ABA1BC24FBD2F40DAFCAB55321FC61F38494F3222AD

Scenario 3 - With Request parameter mapping

Suppose Configuration is done as follows,

Configuration Field	Value
Payment Redirect URL	`https://www.example.com/payment-redirect`
Redirection Type	`QueryString`
SecretKey	`testSecretKey`
Payment Redirection Request Parameter Key Map	`unique_id=txnId,amount=txn_amount`

In this case, sample redirect URL would be,

https://www.example.com/payment-redirect?source=csod.exe&cart_id=&txnId=20241216183904489836¤cy=USD&txn_amount=100.00&tax=&fee=0.00&locale=en-US&return_url=https%3a%2f%2fportalname.csod.com%2fLMS%2fEcom%2fPaymentProcessHandler.aspx%3fqs%3dRdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQ&tu_purchase=false&signature=F1FCAAE65F7A63D64E6AC9AD9A3E5DB29609D7B835D6D1967F54B6056BF22F44

Here, hash payload for signature calculation is,

cart_id=txnId=20241216183904489836currency=USDtxn_amount=100.00tax=fee=0.00locale=en-USreturn_url=https://portalname.csod.com/LMS/Ecom/PaymentProcessHandler.aspx?qs=Rdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQtu_purchase=false

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. F1FCAAE65F7A63D64E6AC9AD9A3E5DB29609D7B835D6D1967F54B6056BF22F44

Payment Response Fields

Following set of fields are expected from middleware while redirecting back User after payment request completion.

Use "Payment Response Parameter Key Map" to map below field names to corresponding middleware parameter name.

Field	Mandatory(M) / Optional(O) / Conditional (C)	Description
unique_id	M	Unique Identifier. It is used for identifying a transaction uniquely. It should be same as one that was sent in the payment request.
status	M	Status of payment. This field must be sent. Send it as value defined in "Success Code" to indicate successful payment. Send it as value defined in "Pending Code" to indicate delayed confirmation. Any other value would be considered as a failed payment.
transaction_id	C	Transaction Id of the payment. It is required for a successful payment.
paid_amount	O	Total amount paid by the user. If not sent, it is considered to be same as the requested amount.
error_msg	O	Error message in case of failure.
signature	M	This is dynamically calculated field. It should be calculated by Hashing payload of all other key=value pairs without any delimiter. `signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase()` Refer to Payment Response Examples for details.

Payment Response Examples

One can either send data as HttpPost or QueryString. If any parameter is detected in HttpPost, then extra parameters in QueryString are ignored.

Scenario 1 - Sending data as HttpPost with Status as Success

Suppose Configuration is done as follows,

Configuration Field	Value
SecretKey	`testSecretKey`
Success Code	`100`

And return_url was provided as, https://portalname.csod.com/LMS/Ecom/PaymentProcessHandler.aspx?qs=Rdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQ

In this case, User should be redirected to return_url with following parameters passed in Form Post

Key	Value
`unique_id`	`20241216183904489836`
`status`	`100`
`transaction_id`	`paymentTxnId12345`
`paid_amount`	`100.00`
`signature`	`B14FAB7D21A8C59191FFA869A8C14D585AD96DF55F50A61893C8E23CA1F703D0`

Here, hash payload for signature calculation is,

unique_id=20241216183904489836status=100transaction_id=paymentTxnId12345paid_amount=100.00

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. B14FAB7D21A8C59191FFA869A8C14D585AD96DF55F50A61893C8E23CA1F703D0 Note: In case of HttpPost, values should be sent as plain text without any encoding.

Scenario 2 - Sending data as QueryString with Status as Failure

Suppose Configuration is done as follows,

Configuration Field	Value
SecretKey	`testSecretKey`
Success Code	`100`

And suppose if return_url was provided as,

https://portalname.csod.com/LMS/Ecom/PaymentProcessHandler.aspx?qs=Rdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQ

In this case, User should be redirected to return_url, and remaining parameters should be appended in the Query String as,

https://portalname.csod.com/LMS/Ecom/PaymentProcessHandler.aspx?qs=Rdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQ&unique_id=20241216183904489836&status=101&error_msg=Payment+Failed&signature=35B24649549B87605C94E4B828E9EF7DFC2A85673EC23206EAF8BBA77B6763DF

Here, hash payload for signature calculation is,

unique_id=20241216183904489836status=101error_msg=Payment Failed

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. 35B24649549B87605C94E4B828E9EF7DFC2A85673EC23206EAF8BBA77B6763DF Note: In case of Query String, values should be Url encoded before sending. For example, space is replaced by '+' sign.

Scenario 3 - Sending data as Pending with Response parameter mapping

Suppose Configuration is done as follows,

Configuration Field	Value
Payment Redirection Response Parameter Key Map	`unique_id=uid,status=payment_result,error_msg=payment_result,transaction_id=txnId&signature=hashkey`
SecretKey	`testSecretKey`
Success Code	`100`
Pending Code	`300`

And suppose if return_url was provided as, https://portalname.csod.com/LMS/Ecom/PaymentProcessHandler.aspx?qs=Rdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQ

In this case, User should be redirected to return_url, and remaining parameters should be appended in the Query String

https://portalname.csod.com/LMS/Ecom/PaymentProcessHandler.aspx?qs=Rdqb7fIZHJzbckjfMVlYsBjNYayGpgBRHf8PVd8-oy4m6PhPETgIEcOztd1zLM7Rt6DxgKjWzJ8EsTin0oKrtQ&uid=20241216183904489836&payment_result=300&txnId=123456&hashkey=A74C381FE52C14B3FB2EF8DAA867A46A4EDE2E26A931DD5D109B8D765F495A86

Here, hash payload for signature calculation is,

uid=20241216183904489836payment_result=300txnId=123456

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. A74C381FE52C14B3FB2EF8DAA867A46A4EDE2E26A931DD5D109B8D765F495A86 Note: In case of Query String, values should be Url encoded before sending. For example, space is replaced by '+' sign.

Refund Flow

Below table explains various configurations available for configuring a refund flow.

Refund Configuration

Configuration	Required	Description
Refund Section
Refund API URL	No	Middleware API URL where a Refund request is POSTed for processing. It must be a secure HTTP URL (i.e. https://). This configuration is required to support Refund.
Refund API Header Parameters	No	It can be used to specify any fixed set of key=value pairs that would be sent in request header along with each refund request to the middleware Refund API. Ensure that the key=value pairs are comma-separated.
Refund API Request Parameters	No	It can be used to specify any fixed set of key=value pairs that would be sent in request as a query string along with the refund request parameters to the middleware Refund API. Ensure that the key=value pairs are comma-separated.
Refund Request Parameter Key Map	No	If middleware expects refund fields to be received with different names, this configuration can be used to specify the mapping. It supports mapping of Refund API Request Fields. For example, refer to Scenario 3 - Sending Refund Request with mapping defined in request and response (Pending Refund).
Refund Response Parameter Key Map	No	If middleware is going to return refund fields with different names, this configuration can be used to specify the mapping. It supports mapping of Refund API Response Fields.For example, refer to Scenario 3 - Sending Refund Request with mapping defined in request and response (Pending Refund).
Common Section
Secret Key	Yes^#	This secret key is used for SHA256 hashing of payload which is sent 'To' and 'From' Cornerstone to the middleware. Hash is important to ensure integrity of the message exchanged.
Success Code	Yes	Specify the value sent by middleware to indicate that the payment or refund is successful.
Pending Code	No	Use this if middleware needs to support delayed confirmation. Specify the value sent by middleware to indicate that the payment or refund is not yet successful but is in a pending confirmation state.

# - If you need to bypass this Secret Key configuration (not recommended), refer to product help documentation.

Refund integration is done via API.

A HTTP POST request is made to the configured Refund API URL. Refund Parameters are sent in the query string. Individual field values are Url encoded before sending. For example, space is replaced by '+' sign.

Use "Refund API Header Parameters" and "Refund API Request Parameters" to add extra parameters with fixed values to the request in header and in the query string respectively.

API can send refund response either as a JSON object or as a Form URL-encoded string by setting appropriate Content-Type header.

Refund API Request Fields

These fields are sent in the Refund request.

Use "Refund Request Parameter Key Map" to map below field names to corresponding middleware parameter name.

Field	Description
unique_id	Unique Identifier. It is used for identifying a refund transaction uniquely.
refund_amount	Amount to be refunded. Amount field is sent in format with at least 2 digits after decimal point.
currency	3 digit ISO Currency Code in upper case e.g. USD, CAD, EUR etc.
transaction_id	Transaction Id of the original payment which is used for refunding.
reason	Optional, reason for refund
signature	This is dynamically calculated field. It is calculated by Hashing payload of all other key=value pairs sent as a part of refund request without any delimiter. signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() Refer to Refund Examples for calculation

Refund API Response Fields

Following set of fields are expected from middleware API while responding back to a refund request.

Use "Refund Response Parameter Key Map" to map below field names to corresponding middleware parameter name.

List of fields are,

Field	Mandatory(M) / Optional(O) / Conditional (C)	Description
unique_id	M	Unique Identifier. It is used for identifying a transaction uniquely. It should be same as one that was sent in the refund request.
status	M	Status of refund. Send it as value defined in "Success Code" to indicate successful refund. Send it as value defined in "Pending Code" to indicate delayed confirmation. Any other value would be considered as a failed refund.
refund_transaction_id	C	Transaction Id of the refund. It is required for a successful refund.
refunded_amount	O	Total amount refunded. If not sent, it is considered to be same as the requested amount.
error_msg	O	Error message in case of failure.
signature	M	This is dynamically calculated field. It should calculated by Hashing payload of all other key=value pairs sent back as a part of refund response without any delimiter. signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase().. Refer to Refund Examples for calculation logic.

Refund Examples

Scenario 1 - Sending Refund Request and responding with JSON (Successful Refund)

Suppose Configuration is done as follows,

Configuration Field	Value
Refund API URL	`https://www.example.com/api/refunds`
SecretKey	`testSecretKey`
Success Code	`100`

In this case, sample Refund API call would be,

curl -X 'POST' \
  'https://www.example.com/api/refunds?unique_id=20250120102030123000&refund_amount=10.00&reason=&transaction_id=pi-123434345&currency=USD&signature=2BDE03CCE75DBEBB51C5AEA7F8CEC030947D01882A7F697EE55FFACD1A19423F'

And hash payload for signature calculation is, unique_id=20250120102030123000refund_amount=10.00reason=transaction_id=pi-123434345currency=USD

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. 2BDE03CCE75DBEBB51C5AEA7F8CEC030947D01882A7F697EE55FFACD1A19423F

This API would need to send response as shown below to indicate a successful refund.

{
  "unique_id": "20250120102030123000",
    "status": "100",
    "refund_transaction_id": "refund-id-23432",
    "refunded_amount": "10.00",
    "error_msg": "",
    "signature": "2066A3B43B34024DE7E217FE949B46465AE03CBD17FBD0C1D3CEF696F4A5B227"
}

Here, signature should be calculated by Hashing payload of all other key=value pairs without any delimiter

Hash payload would be, unique_id=20250120102030123000status=100refund_transaction_id=refund-id-23432refunded_amount=10.00error_msg=

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. 2066A3B43B34024DE7E217FE949B46465AE03CBD17FBD0C1D3CEF696F4A5B227

Scenario 2 - Sending Refund Request with extra parameters and responding with FormUrlEncoded Parameters (Failed Refund)

Suppose configuration is done as follows,

Configuration Field	Value
Refund API URL	`https://www.example.com/api/refunds`
Refund API Header Parameters	`username=usr1,password=pwd1`
Refund API Request Parameters	`refund_source=csod,auto_tax=false`
SecretKey	`testSecretKey`
Success Code	`100`

In this case, sample Refund API call would be,

curl -X 'POST' \
  'https://www.example.com/api/refunds?unique_id=20250120102030123000&refund_amount=10.00&reason=&transaction_id=pi-123434345&currency=USD&refund_source=csod&auto_tax=false&signature=AE6F225E094AD728746388D5898A1CE5EC09C33B6B38736704C6647C28770B3B' \
  -H 'username: usr1' \
  -H 'password: pwd1'

And hash payload for signature calculation is, unique_id=20250120102030123000refund_amount=10.00reason=transaction_id=pi-123434345currency=USDrefund_source=csodauto_tax=false

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. AE6F225E094AD728746388D5898A1CE5EC09C33B6B38736704C6647C28770B3B

This API would need to send response in the body as below to indicate failed refund.

unique_id=20250120102030123000&status=200&error_msg=Transaction+is+not+elligible+for+refund&signature=4234A7C70FFFC0F682F61E234ABA9BC906ED9644FE74C551459209476C45768C

And hash payload for signature calculation would be, unique_id=20250120102030123000status=200error_msg=Transaction is not elligible for refund signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. 4234A7C70FFFC0F682F61E234ABA9BC906ED9644FE74C551459209476C45768C

Scenario 3 - Sending Refund Request with mapping defined in request and response (Pending Refund)

Suppose Configuration is done as follows,

Configuration Field	Value
Refund API URL	`https://www.example.com/api/refunds`
Refund Request Parameter Key Map	`unique_id=uid,refund_amount=amount,transaction_id=paymentId,signature=hashkey`
Refund Response Parameter Key Map	`unique_id=uid,signature=hashkey`
SecretKey	`testSecretKey`
Success Code	`100`
Pending Code	`300`

In this case, sample Refund API call would be,

curl -X 'POST' \
  'https://www.example.com/api/refunds?uid=20250120102030123000&amount=10.00&reason=&paymentId=pi-123434345&currency=USD&hashkey=EAB0B32371B8C983F347AAE1463EB2B67C673BED0923B126047E6A3B0F847278' \
  -H 'username: usr1' \
  -H 'password: pwd1'

And hash payload for signature calculation is, uid=20250120102030123000amount=10.00&reason=paymentId=pi-123434345currency=USD

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. EAB0B32371B8C983F347AAE1463EB2B67C673BED0923B126047E6A3B0F847278

This API would need to send response in the body as below to indicate pending refund.

uid=20250120102030123000&status=300&refund_transaction_id=ref-12345&hashkey=831C1891F468506FAB9B2536AA6C6281CB21866A98A2EFFD715082878E03F10F

And hash payload for signature calculation would be, uid=20250120102030123000status=300refund_transaction_id=ref-12345 signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. 831C1891F468506FAB9B2536AA6C6281CB21866A98A2EFFD715082878E03F10F

Webhook

Webhook can be used for sending delayed confirmation/rejection of payment or refund. Usually rejections are not sent as any incomplete payment/refund are automatically considered as failed after 10 minutes by the system.

Below table explains various configurations related to Webhook implementation.

Webhook Configuration

Configuration	Required	Description
Common Section
Secret Key	Yes	This secret key is used for SHA256 hashing of payload which is sent 'To' and 'From' Cornerstone to the middleware. Hash is important to ensure integrity of the message exchanged.
Success Code	Yes	Specify the value sent by middleware to indicate that the payment or refund is successful.
Pending Code	No	Use this if middleware needs to support delayed confirmation. Specify the value sent by middleware to indicate that the payment or refund is not yet successful but is in a pending confirmation state.
Web Hook URL	NA	This URL indicates a Webhook URL which can be called from middleware to post delayed confirmation of payment and refund.

This feature does not work if Secret Key is not configured.

When a transaction is pending, and if an update using Webhook is not sent within 10 minutes, then it will be considered as failed. Delayed payments and refunds are recorded in the system but may not be effective. Reach out to product help document for more details.

Webhook can be posted by sending a POST request to the Webhook URL displayed in the Payment Account Configuration.

It should be sending following 2 headers and payload fields should be sent in Form URL Encoded format (i.e. Key=Value pairs)

Webhook Headers

Both the headers are mandatory.

Header Name	Description
x-custom-date	Current UTC Time should be provided in the format "yyyy-HH-mmTHH:mm:ss.fff" e.g. `"2024-12-25T18:30:52.120"`.
x-custom-signature	Signature of the request. It should be calculated by Hashing value of 'x-custom-date' header and payload of all the key=value pairs without any delimiter. Refer to Webhook Examples for details.

Webhook Fields

Field	Mandatory(M) / Optional(O) / Conditional (C)	Description
unique_id	M	Unique Identifier. It is used for identifying a transaction uniquely. It should be same as one that was sent in the payment/refund request.
event_type	M	Event type. It should be set to either Payment or Refund
status	M	Status of payment/refund. This field must be sent. Send it as value defined in "Success Code" to indicate successful payment/refund. Any other value would be considered as a failed refund.
transaction_id	C	Transaction Id of the payment or refund. It is required for a successful payment or refund.
amount	O	Total amount paid or refunded. If not sent, it is considered to be same as the requested amount.
error_msg	O	Error message in case of failure.

Webhook Examples

Scenario 1 - Successful Payment

Suppose Configuration is done as follows,

Configuration Field	Value
SecretKey	`testSecretKey`
Success Code	`100`

In this case, sample Webhook API call would be,

curl -X 'POST' \
  '<<webhook-url>>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-custom-date: 2025-01-22T18:30:52.120' \
  -H 'x-custom-signature: B2A255565CA13B6A10F83A2E18BEFF6AF6EB2F4C102C64A5B1C7646408124C38' \
  -d 'unique_id=20241216183904489836&event_type=Payment&status=100&transaction_id=pi-123434345&amount=10.00'

And hash payload for signature calculation is, 2025-01-22T18:30:52.120unique_id=20241216183904489836event_type=Paymentstatus=100transaction_id=pi-123434345amount=10.00

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. B2A255565CA13B6A10F83A2E18BEFF6AF6EB2F4C102C64A5B1C7646408124C38

Scenario 2 - Successful Refund

Suppose Configuration is done as follows,

Configuration Field	Value
SecretKey	`testSecretKey`
Success Code	`100`

In this case, sample Webhook API call would be,

curl -X 'POST' \
  '<<webhook-url>>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-custom-date: 2024-12-25T18:30:52.120' \
  -H 'x-custom-signature: A6BBD37DD8C9D06E9388BDE293755E720CEBE5D7C6C646F389410C4CE5DAEC8B' \
  -d 'unique_id=20250120102030123000&event_type=Refund&status=100&transaction_id=pi-123434345&amount=10.00'

And hash payload for signature calculation is, 2024-12-25T18:30:52.120unique_id=20250120102030123000event_type=Refundstatus=100transaction_id=pi-123434345amount=10.00

signature = HMACSHA256(secretKey, Hash Payload).Replace("-","").ToUpperCase() i.e. A6BBD37DD8C9D06E9388BDE293755E720CEBE5D7C6C646F389410C4CE5DAEC8B