Hosted payment gateway

Configuration

To start developing and testing your hosted payment gateway, enable and configure it inside the OfficeRnD admin console, following these steps:

1. Login to the OfficeRnD admin console as an Owner and navigate to Settings > Integrations.
2. Locate the Hosted Payment Gateway under the Payment Gateways section.
3. Click the Activate link and then Configure

A dialog is shown that allows you to input and get all necessary information for the integration to work.

• The Name field is used to define the name of the integration. If you input Cool Payments, the customer will see that as Pay with Cool Payments
• The Secret field is read-only. Its value is initially hidden and you can retrieve it by hitting the "eye" button next to it. You must use the value of this field to verify requests and sign your responses. This secret should be used only on your servers and should never be shown, served or shared with the end user.
• The Gateway URL should be a fully formed url i.e. - https://your.integration.url/path. You can put parameter placeholders that will be populated when OfficeRnD initiates the customer redirect request. The placeholders that you can use are as follows: {{ amount }}, {{ reference }}, {{ transactionId }}, {{ signature }}, {{ redirectUrl }}.
  • Example: https://pay.cool-payments.com/hosted?amount={{ amount }}&ref={{ reference }}&tId={{ transactionId }}&signature={{ signature }}&redirectUrl={{ redirectUrl }}

How it works

1. The customer chooses to pay with the hosted payment gateway, configured in OfficeRnD.
2. OfficeRnD redirects the customer to your gateway's URL, submitting the correct Request parameters. Your gateway must verify the signature parameter value and present a hosted payments page to the customer.
3. The customer payment is processed on the hosted payment page that you provide.
4. Upon completing the payment, customers should be redirected back to the redirectUrl with all required Response parameters in the query string. This includes the signature. If the payment was successful, the status parameter should have a success value. Otherwise the status should be - fail.
5. OfficeRnD accounts for the payment to the respective invoice and shows a success or failure message the customer.

Developing your hosted payment gateway integration

OfficeRnD enables you to extend the system so that you can process payments using a custom-developed payment page. OfficeRnD checkout will redirect the customer to the configured payment gateway page. The page should be able to handle predefined request parameter values. After the customers complete the payment, they will be redirected back to OfficeRnD, with predefined response parameter values.

It is the responsibility of the payment gateway to build the page that handles the payment requests.

Request and Response signing mechanism

All requests and responses must be signed and verified using HMAC-SHA256. The signing should use the following rules:

• For key you must use the value if the Secret field defined in your integration configuration page.

• The value of message must be a string comprised of the values of all key parameters concatenated by the pipe symbol ('|') as a separator.

  • The key parameters for the request are amount, reference and transactionId.

    Example: If the request amount is 12.34, it has a reference INV-001 and a transactionId - 6f47c19b-eb9d-4ee5-a144-19f7b9263183, then the message should be the following string:

    12.34|INV-001|6f47c19b-eb9d-4ee5-a144-19f7b9263183

  • The key parameters for the response are status and transactionId.

    Example: If the response status is success and its transactionId is 6f47c19b-eb9d-4ee5-a144-19f7b9263183, then the message should be the following string:

    success|6f47c19b-eb9d-4ee5-a144-19f7b9263183

• Resulting codes must be hex-encoded and passed as value of the signature parameter. Make sure to use case-insensitive comparison when verifying the provided signature values.

Assuming your HMAC key is "11111111-1111-1111-1111-111111111111", the signatures of the example messages should be:

• 12.34|INV-001|6f47c19b-eb9d-4ee5-a144-19f7b9263183 - 617b0b7d29e57db460208904f0e64c11092872d86faf581598c3ba9b8b0e00ae
• success|6f47c19b-eb9d-4ee5-a144-19f7b9263183 - 2c6d0e09f76011cebf9073a4fa08d752e5c5c440e750c6ee1f8ad5d5cce70bad

Request parameters

Response parameters