Integrating with Payment Pages
    • 22 Aug 2024
    • 6 Minutes to read

    Integrating with Payment Pages


    Article summary

    If you're looking for a simple way to integrate payments into your existing website, software, or application, then Payment Pages are a great payment tool to consider. Payment Pages are an easy to set-up and configure, no code solution, that lets you take payments from your customers online.

    Payment Pages are hosted checkouts that can be customized to serve a number of functions. They can be used as part of a shopping cart's checkout flow, as a simple "Pay Now" function on a website, as a customer registration form, and more.

    If you're looking to utilize Payment Pages within a more complex integration or work flow within your system, then there are some additional developer settings that can allow for communication from the Helcim system back to yours.

    What is Approval Send POST?

    Approval Send POST is a developer setting for the Helcim system to send a POST response to a specific URL endpoint, when customers process a payment through your Payment Page.

    Utilizing this functionality would allow you update your internal systems based on the outcome of payments processed by your customers, and redirect your customers once a successful payment has been processed.

    POST responses to your server endpoint will only be sent for successful payments processed through your Payment Pages.

    How to configure Approval Send POST

    For help on configuring your Payment Pages, follow the instructions in our Creating a Payment Page from Template support article

    1. On the Basic Settings step of the Payment Page configuration wizard, select the More Settings dropdown
    2. Under Page Forwarding, toggle on Approval Auto Forward
    3. In the Approval URL field, enter the URL for your server endpoint where you would like the POST response to be delivered
    4. Under Developer Settings, toggle on Approval Send POST
    5. Continue with your Payment Page configuration outlined in the Creating a Payment Page from Template support article
    Requirements for Approval Send POST
    When using Approval Send POST, it is a requirement that Approval Auto Forward is enabled and you have a valid server endpoint address in the Approval URL field.

    Configuring your back-end server endpoint

    In the example below, we have set up a Node.js server that consumes the POST response and writes it to a .csv file.

    You could have your server store the data in a database, make other API calls to the Helcim system, or make updates to your own internal systems. Once done, you can redirect your customer to a client facing URL of your choosing.

    Send POST is ON

    Example Approval Send URL

    https://api.client.com/write-to-csv

    Example code using Node.js


    const express = require('express');

    const fs = require('fs');

    const app = express();


    app.use(express.json());


    app.post('/write-to-csv', (req, res) => {

        const data = req.body;


        const csv = `${data.response},${data.responseMessage},${data.notice},${data.accountType},${data.accountCorporate},${data.bankAccountToken},${data.bankAccountNumber}\n`;


        fs.appendFile('output.csv', csv, () => {

            res.send('Data written to file.');

        });

    });


    app.listen(3000, () => {

        console.log('Server running on port 3000');

    });


    Example request

    Note: Please, refer to the response body structure in the below table. This example is a “Bank verify transaction response.”


    {

        "response": 200,

        "responseMessage": "APPROVED",

        "notice": "ACH VERIFY TRANSACTION",

        "accountType": "Checking",

        "accountCorporate": "ABC Corp",

        "bankAccountToken": "sample-unique-token",

        "bankAccountNumber": "0300"

    }


    Example output in output.csv


    200,APPROVED,ACH VERIFY TRANSACTION,Checking,ABC Corp,sample-unique-token,0300


    Resources

    These resources should help you get a good grasp of building a Node.js server, handling JSON data, and writing to files.


    Getting Started with Node.js:

    Building a Simple Node.js Server:

    Writing to Files in Node.js:

    Working with JSON in Node.js:


    Potential POST response body

    The Helcim system may send one of three potential responses, depending on the type of Payment Page you have configured and the type of payment processed by the customer.

    • Credit card transactions - POST responses are triggered for any credit card payment processed using the Customer Registration, Invoice Payment, Editable Amount, Fixed Amount, Subscription, or Product Purchase templates
    • Bank verify transactions - POST responses are triggered for any ACH payment processed using the Customer Registration template
    • Bank withdraw transactions - POST responses are triggered for any ACH payment processed using the Invoice Payment, Editable Amount, Fixed Amount, Subscription, or Product Purchase templates 

    Review the table below to understand the potential values that can be returned in the POST response and under which circumstances each response would be triggered.

    Credit card transactions

    Response body

    Field

    Type

    Description


    {

        response: number,

    responseMessage: string,

    transactionId: number,

    type: string,

    date: string,

    time: string,

    avsResponse: string,

    cvvResponse: string,

    approvalCode: string,

    cardHolderName: string,

    cardNumber: string,

    expiryDate: string,

    cardType: string,

    cardToken: string

    }



    response

    number

    Indicates if the server response is good or not. The value is either 0 or 1. If it’s 0 then it means that the request to the Helcim server failed. The Helcim server always returns “1”.

    responseMessage

    string

    This is the message sent by the Helcim server to the client server indicating the transaction response. This is always “APPROVAL”.

    transactionId

    number

    This is the ID of the transaction that was processed.

    type

    string

    This is the type of the transaction, either one of the following: purchase, preauth, verify.

    date

    string

    This is the date of when the transaction process was completed.

    time

    string

    This is the date of when the transaction process was completed.

    Note: This has no difference with the date.

    avsResponse

    string

    This is returned during the authorization process that tells if the billing address entered is the same as the one associated with the cardholder’s account.

    cvvResponse

    string

    This is returned during the authorization process that verifies that the person making the purchase has a physical possession of the card.

    approvalCode

    string

    Is a 2-6 digit alphanumeric code that indicates whether a transaction has been approved or declined. This specific code provides information about the reason for the decline.

    cardHolderName

    string

    This is the name of the card owner.

    cardNumber

    string

    This is the F6L4 (first 6, last 4 digit) of the card number

    expiryDate

    string

    This is the card’s 4-digit expiry date in the format “MMYY”

    cardType

    string

    This is the card’s type name, e.g. Visa, Mastercard, American Express, Discover, etc.

    cardToken

    string

    This is the card’s unique and randomly generated identifier that is used during transactions.

    Bank verify transactions

    Response body

    Field

    Type

    Description


    {

        response: number,

    responseMessage: string,

    notice: string,

    accountType: string,

    accountCorporate: string,

    bankAccountToken: string,

    bankAccountNumber: string

    }


    response

    number

    Indicates if the server response is good or not. The value is either 0 or 1. If it’s 0 then it means that the request to the Helcim server failed. The Helcim server always returns “1”.

    responseMessage

    string

    This is the message sent by the Helcim server to the client server indicating the transaction response. This is always “APPROVED”.

    notice

    string

    This is a notice sent by the Helcim server to the client server. This is always “ACH VERIFY TRANSACTION”.

    accountType

    string

    This is the bank’s account type, i.e. Checking or Savings.

    accountCorporate

    string

    This is the bank’s corporate type, i.e. Personal or Corporate

    bankAccountToken

    string

    This is the bank account’s unique and randomly generated identifier that is used during transactions.

    bankAccountNumber

    string

    This is the L4 (last four digits) of the bank account number

    Bank withdraw transactions

    Response body

    Field

    Type

    Description


    {

        response: number,

    responseMessage: string,

    notice: string,

    transactionEFTId: number,

    type: string,

    date: string,

    time: string,

    approvalCode: string,

    accountType: string,

    accountCorporate: string,

    bankAccountToken: string,

    bankAccountNumber: string

    }



    response

    number

    Indicates if the server response is good or not. The value is either 0 or 1. If it’s 0 then it means that the request to the Helcim server failed. The Helcim server always returns “1”.

    responseMessage

    string

    This is the message sent by the Helcim server to the client server indicating the transaction response. This is always “APPROVED”.

    notice

    string

    This is a notice sent by the Helcim server to the client server. This is always “ACH VERIFY TRANSACTION”.

    transactionEFTId

    number

    This is the ID of the EFT transaction that was processed.

    type

    string

    This is the type of the EFT transaction, which in this case for payment pages is always WITHDRAWAL

    date

    string

    This is the date of when the transaction process was completed.

    time

    string

    This is the date of when the transaction process was completed.

    Note: This has no difference with the date.

    approvalCode

    string

    Is a 2-6 digit alphanumeric code that indicates whether a transaction has been approved or declined. This specific code provides information about the reason for the decline.

    accountType

    string

    This is the bank’s account type, i.e. Checking or Savings.

    accountCorporate

    string

    This is the bank’s corporate type, i.e. Personal or Corporate

    bankAccountToken

    string

    This is the bank account’s unique and randomly generated identifier that is used during transactions.

    bankAccountNumber

    string

    This is the L4 (last four digits) of the bank account number


    Was this article helpful?