# 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 FormPost 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 "FormPost", 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.
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
b_fname First Name
b_lname Last Name
b_email Email Address
b_phone Phone Number
b_company Company Name
b_addr1 Address Line 1
b_addr2 Address Line 2
b_city City
b_state State/Province Name
b_country Country Name
b_zip Zip/Postal Code

# 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
s_fname First Name
s_lname Last Name
s_email Email Address
s_phone Phone Number
s_company Company Name
s_addr1 Address Line 1
s_addr2 Address Line 2
s_city City
s_state State/Province Name
s_country Country Name
s_zip Zip/Postal Code

# 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
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
billing_entity-N Billing Entity
tax-N Tax amount
provider-N Training Provider Name

# 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
cf_value-N Custom Field Value

# 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 FormPost
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 FormPost
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&currency=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 FormPost or QueryString. If any parameter is detected in FormPost, then extra parameters in QueryString are ignored.

# Scenario 1 - Sending data as FormPost 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 FormPost, 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