Enabling a Hosted Payment Page
- 14 Mar 2022
- 3 Minutes to read
- DarkLight
Enabling a Hosted Payment Page
- Updated on 14 Mar 2022
- 3 Minutes to read
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
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
Log in to dashboard.nexudus.com if you aren't already.
Select Hosted payment page #1.
Activate the Enabled toggle.
Add a Name for your payment method.
This name is also the payment option name shown to customers on the Members Portal.
Add your Shared secret.
Add your full Payment URL.
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?