# 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:
|
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¤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 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¤cy=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¤cy=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¤cy=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