Integrating with Payment Pages

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

On the Basic Settings step of the Payment Page configuration wizard, select the More Settings dropdown

Under Page Forwarding, toggle on Approval Auto Forward Configure approval send POST in Helcim Payment page step 2

In the Approval URL field, enter the URL for your server endpoint where you would like the POST response to be delivered Configure approval send POST in Helcim Payment page step 3

Configure approval send POST in Helcim Payment page step 3

Under Developer Settings, toggle on Approval Send POST

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: https://nodejs.org/en/learn/getting-started/introduction-to-nodejs https://developer.mozilla.org/en-US/docs/Learn/Server-side/Node_server_without_framework Building a Simple Node.js Server: https://runjs.app/blog/how-to-start-a-node-server Writing to Files in Node.js: https://www.w3schools.com/nodejs/nodejs_filesystem.asp Working with JSON in Node.js: https://www.geeksforgeeks.org/express-js-express-json-function/

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

Integrating with Payment Pages

What is Approval Send POST?

How to configure Approval Send POST

Configuring your back-end server endpoint

Potential POST response body

Credit card transactions

Bank verify transactions

Bank withdraw transactions

What's Next