Enabling a Hosted Payment Page
  • 14 Mar 2022
  • 3 Minutes to read
  • Comment

Enabling a Hosted Payment Page

  • Comment

Once you've developed your own hosted payment page using the payment provider and Nexudus APIs, you can enable this payment method in just a few clicks on the Admin Panel.

You can enable up to three different hosted payment pages in each of your locations.

What You Need to Enable Your Hosted Payment Page

  • Your hosted payment page full URL
  • The shared secret you've defined while developing your hosted payment page

Enabling a Hosted Payment Page

  1. If the navigation menu isn't visible, click the menu icon in the top left corner of the page.

  2. Click Settings > Payments and currency > Payment methods.

  3. Select Hosted payment page #1.

  4. Activate the Enabled toggle.

  5. Add a Name for your payment method.

This name is also the payment option name shown to customers on the Members Portal.

image.png

  1. Add your Shared secret.

  2. Add your full Payment URL.

  3. Click the Save Changes button.

Hosted Payment Page Fields

The table below details every field available for the hosted payment page on the Admin Panel.

Field Details
Name Name of the payment method as it will be displayed to customers on the Members Portal.
Payment URL Full URL of your hosted payment page. The URl should always start with "https://". Nexudus will add additional query string parameter to this URL as detailed below.
Shared Secret A secret key used to hash messages between Nexudus and your payment page. You can use a GUID generator to get a unique secret for each of your hosted payment pages. You cannot see cannot see the shared secret once you save it. Make sure you treat it as you would a password and keep it somewhere safe.

Hosted Payment Page Request and Response Flow

When customers click on a hosted payment page option on the Members Portal, Nexudus will generate a URL with the following query string parameters and redirect the user to the URL you provided as the configuration of the payment page.

Request

Attribute Type Details
amount int The due amount of the invoice, multiplied by 100. For example, an invoice for $101.21 will generate an 'amount' parameter with a value of 10121.
currency string The ISO code for the currency this payment should be processed in.
reference string A reference for this invoice. This would normally be the invoice number.
identifier guid A globally unique identifier for this invoice. This is the UniqueId field for the CoworkerInvoice API entity being paid. The CoworkerInvoice data contains a CoworkerId, which refers to the Coworker API entity representing the customer this invoice is for. The CoworkerInvoice also has a IssuedById, which refers to the Business API entity, representing the location issuing the invoice.
signature string A signature calculated using a HMAC256 hash of the string resulting from concatenating "{amount}
returnUrl string The URL to send the customer to after the payment processing has been completed in your side.

Response

Once you have processed the payment, you should send the customer back to the returnUrl, appending the following query string parameters to the URL. If the amount included in the response is equal or greater than the outstanding amount to pay in the invoice, the invoice will be marked as paid.

Attribute Type Details
amount int The actual amount you processed, multiplied by 100. For example, if you processed a payment for $101.21, you should set the 'amount' parameter to 10121. You can accept partial and over-payments and Nexudus will record them based on this amount.
result string The result of the payment. It can only be "OK" or "FAIL".
signature string A signature calculated using a HMAC256 hash of the string resulting from concatenating result, amount, and identifier. Use the secret you provided in the Hosted Payment Page settings as the key for the HMAC hash algorithm. Each value is separated by a vertical bar.

Example

For an invoice for $200 with reference "5843" and unique identifier "446f5f1b-8fb1-41b9-b606-0751e55cd9f6"

f5b4c156c29d8fe392fe633e42b42f60d1e394ff4075b480d3456fd67623703f

Request

Nexudus will use the string "20000|USD|5843|446f5f1b-8fb1-41b9-b606-0751e55cd9f6" to be hashed. If your secret is "Secret" the hash you obtain would be:

f5b4c156c29d8fe392fe633e42b42f60d1e394ff4075b480d3456fd67623703f

The URL the user would be sent to would be:

https://yourdomain.com?
amount=20000&
currency=USD&
reference=5843&
identifier=446f5f1b-8fb1-41b9-b606-0751e55cd9f6&
signature=f5b4c156c29d8fe392fe633e42b42f60d1e394ff4075b480d3456fd67623703f&
returnUrl=https%3a%2f%2fxyz.spaces.nexudus.com%2fen%2fcallbacks%2fhostedPagePaymentsComplete%3finvoiceId%3d123456789%26providerKey%3d1

Response

Your response should calculate the hash for "OK|20000|446f5f1b-8fb1-41b9-b606-0751e55cd9f6" that results in the in hash:

bb1fcc7b4d97a91f11253b1f1f34692719c540d9dd5d4669b32355f8d8d47eb5

The URL the user would be sent to after payment would be:

https://xyz.spaces.nexudus.com/en/callbacks/hostedpagepaymentscomplete?
result=OK&
providerkey=1&
invoiceid=123456789&
amount=20000&
signature=bb1fcc7b4d97a91f11253b1f1f34692719c540d9dd5d4669b32355f8d8d47eb5

Was this article helpful?

What's Next