Why is ipAddress required on every payment request?

Helcim uses the customer IP for fraud screening. The API rejects requests without a valid ipAddress — this is part of their anti-fraud compliance. Always pass the actual client IP, not your server's.

What is the difference between test and live API tokens?

Your helcimApiToken controls which environment the request hits. Test tokens route to the sandbox, live tokens to production. The API does not warn you if you accidentally use a live token in development.

Can I use Helcim's hosted payment page instead of collecting card data directly?

Yes. Helcim offers a hosted checkout URL that keeps card data off your servers entirely. You generate a session, receive a checkout URL, and redirect the customer. MockGateway simulates both the direct API and the hosted page redirect flow.

What do interchangeFee and processorMarkup mean in the response?

interchangeFee is the card network's cut (set by Visa or Mastercard, varies by card type). processorMarkup is Helcim's fixed margin. totalRate is the sum. Flat-rate processors bundle these into one opaque number — interchange-plus keeps them separate.

How should I handle a DECLINED response?

A DECLINED status means the card network or issuing bank rejected the transaction. Surface a clear error to the customer. Never retry automatically — a declined charge should prompt the customer to use a different card or contact their bank.

Every Helcim request requires ipAddress.
Miss it and nothing reaches the bank.

Helcim is built around transparent pricing — you see exactly what the card network charges versus what Helcim adds on top. Their REST API supports direct card charges, saved card tokens, and hosted payment pages. Explore the full payment lifecycle here without registering a merchant account.

Use this template Helcim docs ↗

Pricing model

Interchange+

Card storage

Card tokens

To start

0 signup

helcim_response.json

{

"data": {

"transactionId": "txn_mock_Hel...",

"status": "APPROVED",

"approvalCode": "MOCK01",

"interchangeFee": 0.0195,

"processorMarkup": 0.0025,

"totalRate": 0.022

}

Helcim is a Canadian payment processor focused on small and medium businesses with a transparent interchange-plus pricing model. Unlike flat-rate processors, Helcim's API response includes the interchange fee (set by Visa/Mastercard), the processor markup (Helcim's fee), and the total rate charged — all as separate fields. This lets you show merchants exactly what they are paying for each transaction.

The ipAddress field is required on every payment request and trips up most integrations. Helcim uses it as part of its fraud prevention — a missing IP address returns a validation error before the request reaches the bank. You need to pass the customer's real IP from your server, not a placeholder. For server-side integrations, this means reading the IP from the incoming HTTP request and forwarding it to Helcim.

Card tokenization is one of Helcim's main features for repeat billing. Charge a card once with saveToVault: true, get back a cardToken, and use that token for all future charges. The token scope is tied to your merchant account — tokens from one merchant account cannot be used in another. This mock lets you test the full tokenize-then-charge cycle without creating a Helcim merchant account.

What is interchange-plus pricing?

Every card transaction involves two separate fees. The first is interchange — the fee paid to the cardholder's bank, set by Visa or Mastercard. It varies by card type, reward level, and whether the card is present. The second is the processor markup — what Helcim charges for its service.

Flat-rate processors bundle both into one number. You can never tell how much went to the bank versus the processor. Interchange-plus splits them every time — you see exactly what you're paying and to whom.

This matters most at volume. A debit card carries a lower interchange rate than a premium rewards card — with interchange-plus, you pay less for cheaper cards automatically. Flat-rate processors pocket that difference.

Rate visibility comparison

Flat-rate processor

2.6%

total rate — no breakdown

No visibility into how the rate is split

Helcim interchange-plus

1.95%

interchange

0.25%

processor

2.20%

total

Card tokenization

Helcim stores card details server-side and returns a cardToken in every transaction response. Use the token for future charges instead of asking the customer to re-enter their card. Tokens are scoped to your merchant account and cannot be transferred.

Save cardget token

First charge returns cardToken for this card.

Charge saveduse token

Pass cardToken instead of cardData on future charges.

Update cardnew token

Replacing a card issues a new token — update your records.

Delete cardinvalidate token

Token becomes invalid immediately on deletion.

curl -X POST https://mockgateway.dev/api/base/helcim/init \
  -H "Authorization: Bearer YOUR_MOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4999,
    "currency": "USD",
    "ipAddress": "203.0.113.42",
    "cardData": {
      "cardNumber": "4111111111111111",
      "cardExpiry": "1228",
      "cardCVV": "123",
      "cardHolderName": "Jane Smith"
    },
    "customerCode": "CUST-00412",
    "orderNumber": "ORD-7731"
  }'

Request parameters

Sent to POST /api/base/helcim/init

Request parameters
Parameter	Type	Required	Description
`amount`	number	required	Transaction amount as a decimal. `e.g. 100.99`
`currency`	string	required	Three-letter ISO currency code. `e.g. CAD`
`ipAddress`	string	required	The customer's IP address, which Helcim requires on every purchase. `e.g. 192.168.1.1`
`cardData.cardToken`	string	required	A stored card token, or full card details in its place. `e.g. 5454HCMXTEST5454`
`invoiceNumber`	string	optional	Your own invoice reference. `e.g. INV2022`

Response fields

Response fields
Field	Type	Description
`transactionId`	integer	Helcim transaction ID
`transactionType`	string	Transaction type
`status`	enum	Transaction status
`authCode`	string	Authorization code
`created_at`	datetime