Custom Payment Pages

Hosted Payment Pages allow developers to implement payment gateway integrations where the payment page is hosted externally, i.e. not in the Nexudus Platform.

Users will be redirected to this page to process their payment and then return back to the portal where they will see the result of the transaction.

You can have up to three different hosted payment providers enabled in each of your locations.

Enable Hosted Payment Pages

  1. If the side menu is not visible, click  .
  2. In the side menu, click Settings.
  3. Under the Payments section, click Payment Methods
  4. In the Available Payment Gateways list, click on one of the "Hosted Page Payments" options. You can add up to three different hosted payment providers if your customer has a set of options when it comes to paying their invoices.

    mceclip0.png

     5. In the configuration screen for the Hosted Page Payments gateway type the following details:

Field

Description

Name

The text to be displayed as the payment button in your portal. Customers will see this text.

Payment Page URL

The full URL where your payment page is hosted. This should always used HTTPS. Nexudus will add additional query string parameter to this URL as detailed below

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. Once the secret is saved, it cannot be seen again so make sure you keep that safe. Treat secrets as passwords.


For example: 

mceclip1.png

Update your portal templates

If you opened your Nexudus account before the 25th of June 2020, you will need to update the files below in your templates.

You can update these files from the template editor.

  • payment_history.htm
  • payment_scripts.htm

Request and Response Flow

When customers click on the payment button on your Nexudus portal for a Hosted Payment Page, we 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

Attributes
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.
signature: string
A signature calculated using a HMAC256 hash of the string resulting from concatenating "{amount}|{currencyCode}|{reference}|{identifier}". Use the secret you provided in the Hosted Payment Page settings as the key for the HMAC hash algorithm. Notice how each value is separated by a pipe (|) symbol.

For example: "20000|USD|5843|446f5f1b-8fb1-41b9-b606-0751e55cd9f6" and a secret key of 'Secret' would produce a hash of 'f5b4c156c29d8fe392fe633e42b42f60d1e394ff4075b480d3456fd67623703f'
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

Attributes
amount: int 
The actual amount you have processed, multiplied by 100. For example, if you processed a payment for $101.21, you should set the 'amount' parameter to 10121. Note that you can accept partial and over-payments and Nexudus will record those based on this amount
result: string. 
The result of the payment. Can only be "OK" or "FAIL".

signature: string
A signature calculated using a HMAC256 hash of the string resulting from concatenating "{result}|{amount}|{identifier}". Use the secret you provided in the Hosted Payment Page settings as the key for the HMAC hash algorithm. Notice how each value is separated by a pipe (|) symbol.

 

Example

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

Request

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

f5b4c156c29d8fe392fe633e42b42f60d1e394ff4075b480d3456fd67623703f

The URL the user would be sent to 

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" which results in hash

bb1fcc7b4d97a91f11253b1f1f34692719c540d9dd5d4669b32355f8d8d47eb5

The URL the user should 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?
3 out of 3 found this helpful
Have more questions? Submit a request

Comments

Please sign in to leave a comment.