Low-Profile Interface – Charging, Token Creation, etc. [Steps 1 + 2]
New development for programmers – use the new JSON interface at:
JSON interface: Article link
JSON interface link:
Create a new Iframe \ Redirect page
API interface for redirecting to a PCI-compliant payment page [Low-Profile page]: charge / charge and token creation / token creation / suspended transaction.
If anything is unclear, you can contact Support for a requirements consultation.
Phone: 03-9436100, then select Developer Support.
You can also contact us directly by email: dev@secure.cardcom.co.il
*When displaying the payment page as an IFRAME on your website, the IFRAME height must be at least 1000 pixels and its width must be 100%.
This interface is primarily suitable for:
An e-commerce website with a shopping cart managed by the programmer, with the final payment page provided by Cardcom. For a closed platform such as WooCommerce, use this guide.
A website with dynamic products and prices.
If there is no shopping cart or programmer to transfer parameters from the website, use Golden Authorization pages.
This interface supports:
Charge only – a regular credit-card charge.
Charge and token creation – charge the customer and create a token for future charges; suitable for subscription websites.
Token creation only – create a token without charging the card.
Suspended transaction – a pending transaction. You can later enter the Golden Authorization management system and charge or modify the transaction details before charging.
Name-to-Value interface:
POST is recommended.
You must apply urlencode to all values transferred to the system.
Address: https://secure.cardcom.solutions/Interface/LowProfile.aspx
Legend:
Red parameter – required
Bold parameter – recommended
Neither red nor bold – optional
Step 1: Request to open a payment page for charging (Low-Profile page)
The function address in Name to Value is: https://secure.cardcom.solutions/Interface/LowProfile.aspx
| No. | Parameter | Example values | Description |
|---|---|---|---|
| 1 | Operation | 1 – charge only 2 – charge and create token 3 – create token only 4 – suspended transaction | The operation that the Golden Authorization system must perform. Token creation and suspended transactions have additional optional parameters below. |
| 2 | TerminalNumber | 1000 | The internal terminal (not Shva) that performs the operation. |
| 3 | UserName | MyTestUser | The merchant's interface username. A test environment can be opened with Cardcom Support. Phone: 03-9436100; email: support@secure.cardcom.co.il. |
| 4 | SumToBill | 100.50 | Amount to charge. |
| 5 | CoinId | 1 – shekel 2 – dollar | Transaction currency. See the currency-code list. The dollar exchange rate is taken from the representative rate published by the Bank of Israel on the previous day. |
| 6 | Language | he – Hebrew (designs 5 + 6) en – English (designs 5 + 6) ru – Russian ar – Arabic | See the additional languages. |
| 7 | ProductName | Order C101G | Product name displayed to the user; maximum 50 characters. If an invoice is created, invoice details are displayed instead. |
| 8 | APILevel | 10 | API version. Latest version: 10. |
| 9 | Codepage | 65001 | Character encoding transferred to the system; in this case, Unicode. |
| 10 | MaxNumOfPayments | 12 | Maximum number of payments the user may select. Terminal payment-tier settings may impose additional limits. |
| 11 | MinNumOfPayments | 3 | Minimum number of payments the user may select. |
| 12 | HideCreditCardUserId | false | Whether to hide the customer's ID field; used when charging customers abroad. |
| 13 | SuccessRedirectUrl | http://www.site.com/Success.html | Page to which the cardholder is redirected after a successful transaction. For an IFRAME, use https, not http. An external address is required; localhost is not allowed. Default: https://secure.cardcom.solutions/SuccessAndFailDealPage/Success.aspx |
| 14 | ErrorRedirectUrl | http://www.site.com/Error.html | Page to which the cardholder is redirected after a failed transaction. For an IFRAME, use https. An external address is required; localhost is not allowed. Default: https://secure.cardcom.solutions/SuccessAndFailDealPage/Fail.aspx |
| 15 | IndicatorUrl | http://www.site.com/hide.aspx | A hidden webhook page for receiving transaction details. The system calls this page before redirecting the customer to the success or failure page. After receiving the details, query the Golden Authorization server to verify them; see Step 2. This must be an external server address, not localhost. Do not rely on the success page, because the customer may close the page or receive a mobile popup. It is recommended to send an order number and receive it back in ReturnValue. If the merchant server does not return HTTP 200, Cardcom retries the report seven times. Duplicate webhook notifications may occur in rare cases; the programmer must check for duplicates. |
| 16 | HideCVV | false | Whether to hide the CVV field; used for recurring-payment terminals where CVV is not required. |
| 17 | CreditType | 1 – regular charge 6 – installment credit | If omitted, a regular charge or regular installments are performed. Credit-card companies may limit the number of installments and minimum amount. |
| 18 | ReturnValue | AA-1234 | Value sent to the payment system and returned to IndicatorUrl, up to 250 characters. Usually the order number. |
| 19 | DefaultNumOfPayments | 10 | Number of payments preselected for the customer. Required when using first payment plus fixed payment. |
| 20 | CardOwnerName | Eli Cohen | Cardholder name. |
| 21 | HideCardOwnerName | true | Whether to hide the cardholder-name field. |
| 22 | SapakMutav | 1234 | Customer number in a multiple-beneficiary arrangement. |
| 23 | RefundDeal | true | Whether to enable a refund to the card details; active for charge-only operations. |
| 24 | ShowCardOwnerPhone | true | Whether to display the cardholder phone field. |
| 25 | CardOwnerPhone | 0548976523 | Cardholder phone. |
| 26 | ReqCardOwnerPhone | false | Whether the cardholder phone field is required. |
| 27 | CardOwnerEmail | eli1960@gmail.com | Customer email; included in transaction details, not in the invoice. |
| 28 | ShowCardOwnerEmail | true | Whether to display the cardholder email. |
| 29 | ReqCardOwnerEmail | true | Whether the cardholder email is required. |
| 30 | ShowInvoiceHead | true | Whether to display and allow the customer to edit invoice details. Active when an invoice is produced. |
| 31 | AutoRedirect | true | In test mode, when true, the customer is redirected directly to the payment page instead of receiving a URL. GET is recommended for testing; POST is recommended for a live terminal. |
| 32 | InvoiceHeadOperation | 0 – do not create or display an invoice 1 – create an invoice from the transferred details (default) 2 – display invoice details without creating an invoice 3 – create an invoice if the module exists; otherwise display only | See the invoice-parameter table. |
| 33 | IsVirtualTerminalMode | true | Whether this is merchant-side processing. The page behaves like a virtual terminal and displays additional fields. For EMV devices, pass true to display the “Charge on PINPAD” button. Use secure.cardcom.solutions. Supported only in page designs 4 and 5, not design 6. |
| 34 | IsOpenSum | true | Works only when IsVirtualTerminalMode=true and allows the merchant to update the amount during charging. |
| 35 | ChargeOnSwipe | true | When a magnetic stripe (track 2) is transferred, charge immediately. |
| 36 | DocTypeToCreate | 1 – tax invoice/receipt 3 – nonprofit receipt 101 – website order confirmation 400 – regular receipt 303 – receipt account 405 – donation receipt | Optional. It is recommended not to pass this parameter; the system determines the document according to terminal settings. |
| 37 | CSSUrl | https://www.site.co.il/mycss.css | URL of a CSS file added to the payment page. HTTPS is recommended. Intended mainly for providers/dealers with many Cardcom terminals. |
| 38 | IsAVSEnable | Cardholder city, address and ZIP code | Whether to display AVS fields. Requires support from the credit-card companies. |
| 39 | deferMonths | 1 – one month (current +30) 2 – two months (current +60) 3 – current +90 4 – current +120 5 – current +150 | Number of months to defer the transaction. Requires approval from the credit-card companies. |
| 40 | FirstPayment | First payment | In an installment transaction, the first payment may be higher than the remaining payments. Not supported for credit transactions. |
| 41 | ConstPayment | Fixed payment | Used with FirstPayment. Example: total 100, three payments, first payment 50, fixed payment 25. The split is processed server-side. |
Additional optional parameters for operations 2 and 3 – charge and create token / create token only:
| Parameter | Example | Description |
|---|---|---|
| CreateTokenDeleteDate | 01/01/2025 | Date until which the token details are stored in Cardcom's database. If omitted, the token is stored until the card expires. |
| CreateTokenJValidateType | 2 – J2 validation 5 – J5 validation | Validation performed when creating a token only. J2 validates the card; J5 validates and reserves the amount and returns a one-time approval code. J5 requires approval from the credit-card companies. The returned parameter is TokenApprovalNumber. |
Additional optional parameters for operation 4 – suspended transaction:
| Parameter | Example | Description |
|---|---|---|
| SuspendedDealJValidateType | 2 – J2 5 – J5 | Validation performed on the card. J5 requires credit-card-company approval. |
| SuspendedDealGroup | 0 | Group code used to display customers by report segments. After receiving and storing LowProfileCode, redirect the customer to the payment page using the returned URL. |
Additional UTM parameters returned to the success page and webhook
| utm_source | |
| utm_medium | medium |
| utm_campaign | campaignNAME |
| utm_content | content |
| utm_term | term |
The response:
| Parameter | Example | Description |
|---|---|---|
| ResponseCode | 0 | 0 means the operation is valid; otherwise there is a development error. To determine whether the transaction succeeded, including BIT, PayPal and digital wallets, check OperationResponse. |
| Description | OK | Response description. If different from 0, log it and alert the system administrator. |
| LowProfileCode | f47b241e-1861-4cf8-a9a2-bf0c05f9f36d | Unique transaction identifier. Save it with the order in the database. |
| url | https://secure.cardcom.solutions/External/lowProfileClearing/1000.aspx?LowProfileCode=... | URL of the created page to which the cardholder must be redirected. |
| PayPalUrl | PayPal redirect URL | URL for redirecting the cardholder directly to PAYPAL, suitable for a “Buy with PAYPAL” button and especially for IFRAME use. PAYPAL must be configured in the terminal first. |
| BitUrl | BIT payment URL | URL for redirecting the cardholder directly to BIT for payment. |
Step 2: Receiving or retrieving a response from the payment server
Request to retrieve the response:
After retrieving the data, mark in your system that it has been retrieved to prevent repeated retrievals. Customers or crawlers may revisit or refresh the success page, which can create duplicate transactions or orders. If the data is marked as retrieved, do not retrieve it again. The request is sent using GET.
Name to Value: https://secure.cardcom.solutions/Interface/BillGoldGetLowProfileIndicator.aspx
Apply urlencode to all transferred values.
To determine whether the transaction was successfully charged, check that OperationResponse == 0.
Notes:
- Red parameters are always returned. Other parameters are returned only when relevant; for example, token parameters are not returned if no token was requested.
- Parameters are sent to the configured page using HTTP GET, for example: http://www.site.com/Indicator.aspx?terminalnumber=1000&lowprofilecode=aa-bb-cc&Operation=1.
- When a token is created, save the token-related parameters in the database.
- It is recommended to save all data received in this response.
Parameters for querying the server again:
| Parameter | Example | Description |
|---|---|---|
| TerminalNumber | 1000 | Terminal performing the operation. |
| UserName | APIUserName | Interface username. |
| LowProfileCode | AA-BB-CC | Unique transaction code. |
| codepage | 65001 | Encoding type. |
GET example:
https://secure.cardcom.solutions/Interface/BillGoldGetLowProfileIndicator.aspx?terminalnumber=1000&username=APIUserName&lowprofilecode=AA-BB-CC
Response parameters:
| Parameter | Example | Description |
|---|---|---|
| TerminalNumber | 1000 | Internal terminal performing the operation. |
| LowProfileCode | 5BAF4BD5-76FB-4C81-8654-DF481B22EDF3 | Unique transaction code. |
| Operation | 1 – charge only 2 – charge + token 3 – token only 4 – suspended transaction | Operation performed. |
| OperationResponse | 0 – valid Otherwise, no charge was performed. | Whether the charge succeeded. |
| DealResponse | 0 – valid 3 – declined 4 – stolen | Credit-card charge response code. |
| InternalDealNumber | 654354685 | Unique credit transaction number; may be Int64/BigInt. |
| TokenResponse | 0 – valid | Token-creation response code. |
| Token | 12F678C4-BC08-4607-ACF2-755FD7FCD3DE | Token number. Must be saved in the database. |
| TokenExDate | YYYYMMDD | Token expiration date, like the card expiration date. Must be saved. |
| CoinId | 1 – shekel 2 – dollar | Currency code of the transaction. |
| CardOwnerId | 012345678 | Cardholder ID. Must be saved. |
| CardValidityYear / CardValidityMonth | 2021 / 12 | Card expiration year and month; save when creating a token. |
| TokenApprovalNumber | 12345 | One-time approval number returned when a token is created with J5 validation. Save it for future charging. |
| SuspendedDealResponseCode | 0 – valid | Suspended-transaction response code. |
| SuspendedDealId | 1234 | Suspended transaction number. |
| SuspendedDealGroup | 90 | Suspended transaction group. |
| InvoiceResponseCode | 0 – success | Invoice-creation response code. |
| InvoiceNumber | 555 | Invoice number. |
| InvoiceType | 1 – charge invoice 2 – credit invoice 3 – receipt 4 – customer refund | Document type created. |
| CallIndicatorResponse | ok | Response description from your server when IndicatorUrl was called. |
| ReturnValue | 1234 | Value passed when the charge request was created. |
| NumOfPayments | 3 | Number of payments selected by the customer. |
| CardOwnerEmail / CardOwnerName / CardOwnerPhone | eli@gmail.com / Eli Cohen / 0508855881 | Cardholder contact details. |
| AccountId | 1001 | Customer number in the Golden Authorization system, only if a customer card was created or merged. |
| ForeignAccountNumber | 21451 | Customer bookkeeping account number, only if a customer card was created or merged. |
| SiteUniqeId | 1005412 | Unique customer identifier, only if a customer card was created or merged. |
| ExternalPaymentVector | PayPal=10, ApplePay=11, uPayBit=12, PayMeBit=14, GooglePay=15, EmvPinpad=100, TAP=103, CardcomBit=104 | External transaction source, such as BIT. |
| ExternalUniqueID | CB999872-45F3-4019-85C6-A28C22369DC2 | External identifier for ApplePay, uPayBit, PayMeBit, GooglePay and other external transactions. |
Additional parameters received from credit-card companies
In addition to internal payment-system data, a credit-card charge may return data directly from the credit-card company. These parameters are returned only when present and when a request was made to the credit-card companies. The fields are dynamic and may be expanded.
| Parameter | Description |
|---|---|
| ExtShvaParams.Status1 | Response code for the request to the credit-card companies. Some codes other than 0 may still indicate a valid transaction. |
| ExtShvaParams.Sulac25 | Acquiring company code. |
| ExtShvaParams.CardNumber5 | Last four digits of the customer's card. |
| ExtShvaParams.JParameter29 | Card validation type: 0 default, 2 checksum only, 5 approval from credit-card companies. |
| ExtShvaParams.Tokef30 | Card expiration date. |
| ExtShvaParams.Sum36 | Amount paid in minor currency units. |
| ExtShvaParams.SumStars52 | Amount paid in points. |
| ExtShvaParams.ApprovalNumber71 | Transaction approval number. |
| ExtShvaParams.FirstPaymentSum78 | First payment amount. |
| ExtShvaParams.ConstPayment86 | Amount of each additional payment. |
| ExtShvaParams.NumberOfPayments94 | Number of additional payments; for credit type 6, this represents the total number of payments. |
| ExtShvaParams.CardTypeCode60 | Issuing credit-card company code. |
| ExtShvaParams.Mutag24 | Card-brand code: Mastercard, Visa, Diners, Amex, Isracard, JCB, Discover or Maestro. |
| ExtShvaParams.CardOwnerName | Cardholder name entered by the payer. |
| ExtShvaParams.CardToken | Card token, if created. |
| ExtShvaParams.CardHolderIdentityNumber | Cardholder ID. |
| ExtShvaParams.CreditType63 | Credit charge type. |
| ExtShvaParams.AbroadCard119 | Card type, such as Israeli, tourist, fuel, debit or gift/prepaid. |
| ExtShvaParams.DealType61 | Transaction type. |
| ExtShvaParams.ChargType66 | Transaction channel, such as regular, contactless, telephone or internet. |
| ExtShvaParams.BinId | Card-type identifier. |
| ExtShvaParams.FirstCardDigits | First six card digits. |
| ExtShvaParams.InternalDealNumber | Cardcom internal transaction number (Int64). |
| ExtShvaParams.CouponNumber | Voucher number. |
| ExtShvaParams.DealDate | Transaction date. |
| ExtShvaParams.CardOwnerPhone | Cardholder phone. |
| ExtShvaParams.Uid | Unique transaction identifier. |
Custom fields – API 10
You can send additional information fields that will be saved in the Golden Authorization payment system and displayed in system reports. No advance configuration is required. Maximum length is 50 characters per field. You can configure whether the fields are displayed to the cardholder under Settings > Low Profile Page > Custom Fields.
| Parameter | Example | Description |
|---|---|---|
| CustomFields.Field1 | Shipping address | Custom field 1. |
| CustomFields.Field2 | Shipping city | Custom field 2. |
| CustomFields.Field3–25 | Value up to 50 characters | Additional custom fields. |
HTTPS POST
There are 25 fields; the last field is CustomFields25. Add them as follows:
CustomFields.Field1=XXXX&CustomFields.Field2=YYYY
Sample code:
LowProfile-Operation1(step_1) – code for opening a payment page only, without a document
LowProfile-Operation1+invoice.(step_1) – code for opening a payment page plus an accounting document
GetLowProfileIndicator(step_2) – retrieve data after the IndicatorUrl notification
Note regarding storage of card details:
When charging a credit card, Cardcom creates a token and stores it for software use, for example, if the merchant wants to refund the transaction later.
If the merchant has a token/recurring-payments module, the token is stored until the card expires.
If the merchant does not have a recurring-payments/token module, the token is stored for six months בלבד for future refunds. Therefore, a regular transaction can be refunded only within six months of the transaction date.
Link to Step 3 – charging with tokens