Pelecard Payment Gateway

Pelecard Payment Gateway

Problem

Pelecard is a Payment Service Provider (PSP) that aggregates Israeli merchants onto the card acquirers over Shva, but its public documentation is scattered across a Postman workspace, a sandbox UI, a WordPress plugin listing and third-party PHP libraries, with no single canonical reference. Agents integrating Pelecard end up treating the hostname as an environment switch (it is not), inventing a refund endpoint that does not exist, picking the wrong ActionType (which silently changes whether money moves), or trusting a browser-side ConfirmationKey instead of re-verifying server-side. Each mistake leaks revenue or ships an exploitable "free order" path.

Overview

Card transactions clear on the Israeli Shva network (https://www.shva.co.il/, שב"א); Pelecard handles merchant onboarding, the iframe surface, tokenization and reconciliation on top. Your acquirer, not Pelecard, answers the PCI-tier and broadcast-policy questions below.

Pelecard's dominant integration is an iframe payment page: your server posts a credentials triple (terminal + user + password) plus the transaction parameters, gets back a URL and a ConfirmationKey, and redirects or embeds it. After the customer pays, Pelecard calls your server-side feedback URL. Store the Phase-1 ConfirmationKey keyed by your order; on the callback you MUST (a) match it byte-for-byte and (b) re-call PaymentGW/GetTransaction before treating the order as paid.

Pelecard has two server-to-server surfaces with different parameter-naming conventions. /PaymentGW/* is the iframe surface and has exactly three endpoints. /services/* is where every other operation lives: charges on a saved token, authorizations, voids, tokens, lookups, settlement, 3DS, invoices. Pelecard publishes a live request builder for them at https://gateway21.pelecard.biz/services with a preset body for each; that page is the authoritative endpoint reference, ahead of any third-party wrapper.

The newer "Match API" at match-api.pelecard.biz exists, but its docs page still returns an empty client-side shell (HTTP 200, ~37 characters of text as of 2026-08-27). Verify with Pelecard first.

Instructions

Step 1: Choose Integration Pattern

Step 2: Set Up Authentication

Every Pelecard call needs a credentials triple, sent server-side only:

• terminal -- your terminal ID issued by Pelecard
• user -- API username
• password -- API password

These three values open your terminal to charges. They MUST live in server-side environment variables. Never embed them in browser JavaScript, mobile app bundles, or git history.

The hostname is not an environment switch. gateway20.pelecard.biz and gateway21.pelecard.biz serve the same API: both answer PaymentGW/init, PaymentGW/GetTransaction and PaymentGW/ValidateByUniqueKey identically, and a 404 on gateway21 redirects to an error page on gateway20. gateway21 is the current gateway generation and gateway20 the older one; gateway20.pelecard.biz/sandbox is a sandbox UI page, not a separate API host.

What decides whether a call is a test or a real charge is the terminal number and credentials you send, not the host. Ask Pelecard which host your test terminal was issued on, keep host + terminal + credentials in one config object you swap as a unit, and never write code that infers "this is safe" from a hostname: a build pointed at gateway20 with live credentials is a live charge. Post to gateway21.pelecard.biz unless Pelecard tells you otherwise.

Step 3: Create the Iframe Payment Page

Build the request body from your credentials, Total, Currency, ActionType and the feedback URLs.

Money fields use minor units (agorot). Send Total: 9900 for ₪99.00. Two independent confirmations: the dofinity wrapper documents FirstPayment as "the amount is in agorot/cents", and Pelecard's own builder sends the same 1 shekel as total: "100" on /services/DebitRegularType and as TotalX100: "100" on ValidateByUniqueKey. Still do a 1 ₪ test charge before going live.

The create-session path is PaymentGW/init, verified live on both gateway hosts.

POST https://gateway21.pelecard.biz/PaymentGW/init
Content-Type: application/json

{
  "terminal": "<your-terminal>",
  "user": "<api-user>",
  "password": "<api-password>",
  "ActionType": "J4",
  "Currency": 1,
  "Total": 9900,
  "MaxPayments": 12,
  "MinPayments": 1,
  "GoodURL": "https://example.com/pay/success",
  "ErrorURL": "https://example.com/pay/error",
  "CancelURL": "https://example.com/pay/cancel",
  "ServerSideGoodFeedbackURL": "https://example.com/api/pelecard/ipn-success",
  "ServerSideErrorFeedbackURL": "https://example.com/api/pelecard/ipn-error",
  "ParamX": "order-2026-0042",
  "ShopNo": "main-shop",
  "CreateToken": true
}

On success Pelecard responds with a URL and a ConfirmationKey. Persist the ConfirmationKey server-side keyed by your order (you will compare it on the callback in Step 4). Then redirect the customer to that URL or embed it as an iframe.

A failed init still returns HTTP 200, as the same two fields blank plus an Error object:

{"URL":"","ConfirmationKey":"","Error":{"ErrCode":501,"ErrMsg":"Login for user x failed"}}

Check Error.ErrCode before using URL; treating HTTP 200 as success renders a blank iframe with no diagnostic. Resolve the code via /services/GetErrorMessageEn (Step 8).

init does not return a transaction id. There is no transaction until the customer transacts, so correlate on the ParamX you sent, not on an id you do not have.

ActionType reference (full table in references/payment-parameters.md):

Step 4: Validate the Callback Server-Side

When the customer finishes paying, Pelecard hits your ServerSideGoodFeedbackURL with a PelecardStatusCode, ConfirmationKey, and PelecardTransactionId. Before you treat the order as paid, you MUST do all of the following server-side:

1. Compare your stored Phase-1 ConfirmationKey byte-for-byte to the callback value. No match, refuse the payment.
2. Re-call PaymentGW/GetTransaction with terminal/user/password/TransactionId (the callback's PelecardTransactionId).
3. Confirm the debited amount matches the order's expected price and the transaction id matches the callback. GetTransaction does not return the ConfirmationKey, so this amount/id match is what authenticates the lookup.

Pelecard does NOT sign IPN deliveries with HMAC. A browser-side ConfirmationKey can be forged, so the only authoritative source is the server-to-server GetTransaction lookup.

The lookup call is the credentials triple plus the TransactionId:

POST https://gateway21.pelecard.biz/PaymentGW/GetTransaction
{
  "terminal": "<terminal>",
  "user": "<user>",
  "password": "<password>",
  "TransactionId": "<PelecardTransactionId from callback>"
}

The response is not flat. It is {"StatusCode":"...","ErrorMessage":"...","ResultData":{...}}. Read StatusCode first ("000" = success), then take the transaction fields from inside ResultData: the authoritative debited amount, the Shva approval number, the installment count, masked card last 4, expiry, and your ParamX echoed back. Compare the debited amount against the order's expected price; a mismatch means tampering, so do NOT mark the order paid.

Inbound dedupe. Pelecard may legitimately deliver the same IPN twice (timeout retry; plugin v1.5.1: "Fixed timeout-retry issues"). Dedupe on PelecardTransactionId, unique per attempt, not on ParamX, which is your order id and repeats across deliveries.

Reconciliation safety net. The server-side feedback URL fires only when the transaction reaches a terminal state. If the customer closes the browser mid-flow, no IPN fires. Three status codes describe a broken merchant leg, and they do not mean the same thing:

Only 302 asserts that money moved. Treat 301 and 303 as unresolved until a lookup settles them.

In all three cases you have no PelecardTransactionId, and init never gave you one. Reconcile on a key you own:

• POST /services/CheckGoodParamX with your paramX and shvaSuccessOnly answers "was this order actually paid?" directly. /services/CheckGoodParamXList does it in a batch.
• POST /services/TrxLookUp with paramX returns the transaction.

PaymentGW/ValidateByUniqueKey also validates without credentials, but it keys on a UniqueKey and this skill has not established which init parameter sets one (the documented passthrough fields are ParamX, ShopNo, UserKey, UserData1-15). Don't build a safety net on it unless Pelecard confirms how your terminal accepts a merchant-supplied UniqueKey. paramX is the key this skill can actually show you how to send.

Run a lookup on a schedule for every session with no IPN inside your timeout window. Never re-charge to resolve an unknown outcome; look it up first.

Outbound idempotency (the double-charge you will otherwise ship). All of the above is inbound dedupe. When a token charge times out at the socket you do not know whether it landed, so paramX has to do double duty: make it <order-id>-<attempt-n> and reconcile with a prefix match on <order-id>, so CheckGoodParamX can still answer "was this order paid". (userKey is not available on the debit endpoints; in Pelecard's builder it appears only on the Pending*Type family and ClearPendingByUserKey.) Look the attempt up before retrying. Pelecard rejects some repeats with 308 "Duplicated transaction." or 425 "Double entry" -- proof your retry fired twice, not a transient error to retry again.

Run the bundled scripts/validate_pelecard_response.py against your callback while developing. It is a shape check, not a security gate: it cannot know your expected order amount and never verifies the transaction, so a passing result still requires both checks above. With the opt-in --resolve-codes flag it POSTs only the numeric status code to Pelecard's public code lookup; no callback content leaves your machine.

Step 5: Charge a Stored Token (Recurring Billing)

The first transaction sets CreateToken: true on the iframe request and Pelecard stores the token against TokenForTerminal. Save the token, the card last-4 and the expiry.

Renewals are a /services call, not an iframe parameter. Post to /services/DebitRegularType with the saved token instead of creditCard:

POST https://gateway21.pelecard.biz/services/DebitRegularType
{
  "terminalNumber": "<terminal>", "user": "<user>", "password": "<password>",
  "shopNumber": "001", "token": "<saved-token>", "creditCardDateMmYy": "1230",
  "total": "9900", "currency": "1", "paramX": "sub-2026-08-0042"
}

Note the casing: terminalNumber / total / currency / paramX on /services, versus terminal / Total / Currency / ParamX on /PaymentGW. Sending the /PaymentGW names to a /services endpoint is the most common silent failure here. Use /services/DebitPaymentsType (adds paymentsNumber, firstPayment) when the renewal is in installments.

Maintain the token, don't just create it. Cards get reissued and expiries roll, so /services/UpdateToken (plus ConvertToToken, RetrieveToken, CheckCreditCardForToken, all in references/api-endpoints.md) is what keeps a subscriber. Status 506 "Token number abnormal." means the stored token is no longer chargeable: re-tokenize or UpdateToken, never retry it. The Pelecard WordPress plugin has shipped "Saved payment methods (tokenization)" since v1.2.0 and "WooCommerce Subscriptions support" since v1.4.

Recurring charges + 3DS (MIT exemption). Under EMV 3DS 2.x, repeat charges on a stored token can qualify for the MIT (Merchant Initiated Transaction) exemption, meaning Shva will not step the customer up for a 3DS challenge on each renewal. Pelecard's plugin changelog references this pattern (v1.4.8: "Add 3D-Secure params to J4 after J5 requests"). Confirm the exact MIT-flag parameter for your terminal with Pelecard support before relying on the exemption; without it, recurring charges may intermittently fail with 3DS rejection errors.

Step 6: Process Refunds

There is no single "refund" endpoint, and there is no refund endpoint under /PaymentGW at all. Which primitive applies depends on whether the transaction has already been broadcast to Shva (see Step 6b). This is the ביטול / זיכוי distinction, and getting it wrong is the most expensive routine mistake in Israeli card integration.

Prefer the void whenever it is still available. A void never settles, so you pay no clearing fee; a זיכוי is itself a cleared transaction, so you pay a fee on the credit leg and generally do not get the original charge's fee back, meaning a sloppy charge-then-refund is paid for twice. The void is normally only available while the batch is open, on most terminals the same business day, so timing is the whole game. /services/GetTransDataBeforeBc shows what is still voidable.

The post-broadcast credit path is NOT documented in this skill, and you must not guess it. No /services endpoint in Pelecard's public builder is a card-not-present credit operation (DebitCreditType is a tashlumim kredit sale; EmvReversal is card-present hardware), and no preset exposes a negative total or a credit flag. Get the credit path for your terminal from Pelecard before you accept your first payment, because the Consumer Protection Law clock below starts without waiting for you. Never try a negative total on a debit endpoint: if the terminal accepts it at all, the likely result is a second charge.

Israeli consumer protection law (חוק הגנת הצרכן, סעיפים 14ג-14ה) governs distance-selling refunds: consumers may cancel within 14 days, the merchant must refund within 14 days of the cancellation notice, and cancellation fees are capped at 5% of the order value or 100 ₪, whichever is lower. Do not hard-code 14 days as the whole rule: customers who are people with disabilities, aged 65 or over, or new immigrants may cancel within 4 months where a conversation took place during the sale, and some service categories have their own shorter windows. Treat the above as a summary, not the full statute. A זיכוי settles on the issuer's cycle, so the money can reach the customer well after you issue it; the 14-day duty is on your issuing it. (Source: kolzchut, Consumer Protection Law remote-sales chapter.)

Step 6b: Broadcast (שידור) -- an approval is not money

An approved transaction holding an approval number is an authorization sitting in your terminal's open batch. It becomes a claim on the issuer only when the terminal broadcasts to Shva. Until then it is not settled and still voidable.

/services/Broadcast (credentials only) triggers it, /services/GetBroadcast and GetBroadcastsByDate report status, /services/GetTransDataBeforeBc lists what has not gone yet.

Terminals differ on whether broadcast is automatic or merchant-triggered. Find out which yours is. A terminal that quietly stops broadcasting accumulates approved-but-unsettled transactions while your database says "paid", surfacing only when you reconcile against bank deposits. Alert on anything in GetTransDataBeforeBc older than one broadcast cycle.

Step 7: Configure 3D Secure 2 and Bit

3D Secure 2 (EMV 3DS). On the iframe surface the sandbox UI exposes Initiate and AskForChallenge toggles (each: None default, False, True), and Pelecard runs the authentication for you.

On the server-to-server surface 3DS2 is an ordered sequence, not a flag:

1. POST /Services/Initiate3DSAuthenticationProcess with the amount, currency, card or Token, cardholder details, your RedirectUrl, and the browser fingerprint fields listed in references/api-endpoints.md.
2. The customer is either authenticated without interaction (frictionless) or challenged at your RedirectUrl.
3. Submit the debit carrying the authentication result: /services/DebitRegularType takes eci, xid and cavv for exactly this purpose.

Skipping step 3 wastes the authentication and forfeits the liability shift. Status 650 is "3DS process failed". The Pelecard plugin v1.4.19 changelog notes "Added Emv errors in order notes. ShvaResultEmv parameter" -- log ShvaResultEmv whenever it appears.

Bit wallet. Bit is a Bank-of-Israel-approved A2A wallet. Constraints to bake into the UX:

• Single payment only. From allpay.co.il: "No installments. You can only pay with Bit in one payment." Hide the tashlumim selector when Bit is the chosen method.
• ILS only. Bit only accepts shekels. Send Currency: 1 for any Bit transaction; non-ILS Bit transactions fail with no helpful error.
• Per-transaction cap is operator-set. The commonly-cited limit is 5,000 ₪ (allpay.co.il: "Payment via Bit cannot exceed 5,000 shekels"), but higher-tier merchants are cleared above it. Treat 5,000 ₪ as the design ceiling unless you have written approval otherwise.
• Bit is A2A, so the void/credit machinery in Step 6 does not apply the same way. Confirm the Bit refund and reconciliation path with Pelecard before enabling it.
• Bit also imposes a 20,000 ₪ per-merchant monthly cap and a 10-minute customer window (allpay.co.il).

Apple Pay. Pelecard hosts the SDK at ClientSecure.js, loaded into your own checkout page (see Step 9 on PCI scope). The plugin lists it as "optional, disabled by default".

Step 8: Handle Errors

Pelecard returns a numeric status code everywhere: PelecardStatusCode on the callback, StatusCode on a GetTransaction response, Error.ErrCode on a failed init. 000 is success.

Do not hard-code a hand-written mapping, and do not tell users to email support. Pelecard publishes the official message for every code through two endpoints that need no credentials:

POST https://gateway21.pelecard.biz/services/GetErrorMessageEn
POST https://gateway21.pelecard.biz/services/GetErrorMessageHe
{"ErrorCode": "033"}      ->  invalid credit card.  /  כרטיס לא תקין.

Because GetErrorMessageHe is credential-free, wire it directly into your failure path to show the customer a real Hebrew decline message instead of a number. Cache the responses; the table is stable.

references/error-codes.md carries the full enumerated table (254 assigned codes, both languages, swept 2026-08-27) plus a retry policy, including the merchant-unreachable codes 301 / 302 / 303 and which of them actually means money moved. EMV / 3DS results ride alongside in ShvaResultEmv, a separate code space.

Step 9: Keep your PCI scope where you think it is

The iframe pattern keeps card data off your servers, which is why it is the default recommendation here. Two things in this skill quietly move that line, so decide deliberately:

• Any /services call sending creditCard puts a PAN through your systems (typically SAQ D). A saved token does not. Prefer the token.
• Apple Pay via ClientSecure.js loads a Pelecard script into your own checkout page. A pure redirect/iframe merchant is normally SAQ A; a merchant page hosting a payment script is normally SAQ A-EP. Your acquirer decides; those names are the shape of the question to ask them.

Two logging rules follow from the rest of this skill. Do not log ConfirmationKey -- Step 4's entire verification scheme rests on an attacker not knowing it, and a log aggregator is not a secret store; log a hash if you need to correlate. Do not log CardHolderID (te'udat zehut) in plaintext; it is personal data under the Privacy Protection Law (Amendment 13) and carries retention duties your log pipeline probably does not meet.

Examples

Example 1: First-Time Iframe Checkout

User says: "I want to accept credit-card payments on my Israeli site via Pelecard, with up to 12 tashlumim." Actions:

1. Server: POST credentials + ActionType: J4 + Total: 9900 (₪99.00 in agorot) + Currency: 1 + MaxPayments: 12 to PaymentGW/init. Check Error.ErrCode before using the returned URL.
2. Persist the ConfirmationKey keyed by your order. Render the URL in an iframe (or redirect).
3. Listen on ServerSideGoodFeedbackURL, and run a CheckGoodParamX sweep for sessions that never call back.
4. Compare the callback ConfirmationKey to your stored value, then re-verify via PaymentGW/GetTransaction and confirm the debited amount before marking the order paid. Result: Customer pays in 1-12 tashlumim, against a verified transaction.

Example 2: Save a Card and Charge It Monthly

User says: "I run a SaaS, I need to charge users 99 ₪ every month with their saved card." Actions:

1. First payment: iframe POST with CreateToken: true and Total: 9900 (agorot). Save the token, last-4 and expiry.
2. Monthly cron: POST /services/DebitRegularType with token, total, currency and a paramX of <order>-<attempt>.
3. Verify each charge, dedupe inbound IPNs on PelecardTransactionId, and on any timeout look the attempt up before retrying.
4. Handle declines via the code table, and refresh reissued cards with /services/UpdateToken. Ask Pelecard about MIT-flag parameters so Shva does not challenge each cycle. Result: Recurring billing without storing a single PAN on your servers.

Example 3: Add Bit as a Checkout Option

User says: "Most of my Israeli customers want Bit, can I add it?" Actions:

1. Enable Bit on the Pelecard terminal (vendor-side configuration).
2. Send Currency: 1 and gate Bit to Total <= 5,000 ₪ unless your Bit agreement clears you higher.
3. Hide the tashlumim selector when Bit is chosen; Bit is single-payment only.
4. Same callback flow. Settle the Bit refund path with Pelecard before launch, not after. Result: Bit added cleanly, no failed charges from wallet-side constraints.

Example 4: Validate a Callback Payload Locally

User says: "My Pelecard callback came in, how do I sanity-check it before hitting GetTransaction?" Actions:

1. Run python scripts/validate_pelecard_response.py --resolve-codes --response '{"PelecardStatusCode":"000","ConfirmationKey":"...","PelecardTransactionId":"...","Total":9900,"Currency":1}'.
2. It flags a missing ConfirmationKey or PelecardTransactionId, requires the canonical "000", and resolves any failing code to Pelecard's own bilingual message. --explain 033 looks a code up on its own.
3. If it passes, do the two real checks: stored-vs-callback ConfirmationKey, then PaymentGW/GetTransaction for the debited amount. Result: Quick local check before hitting the Pelecard API.

Example 5: Authorize Now, Charge on Shipment (J5)

User says: "I want to authorize the customer's card at order time but only charge when I ship -- like Amazon." Actions:

1. Before writing any of this, get the capture contract from Pelecard. This skill verified that authorizationNumber is a parameter on every /services debit type, but did not verify that posting a debit with it captures the prior hold rather than starting a fresh authorization and charge. If your terminal is not provisioned for the pairing, the customer is charged twice.
2. First call: ActionType: J5 with CreateToken: true. /services/DebitRegularType requires a creditCard or a token, and an iframe J5 without CreateToken leaves you with neither, so the hold becomes uncapturable. Persist the token, and the authorization number from the IPN / GetTransaction ResultData (it is not in the init response).
3. On shipment, post /services/DebitRegularType with the saved token, the amount, and the authorizationNumber, per the contract you confirmed in step 1.
4. If you decide NOT to ship, release the hold with /services/DeleteIshur so the customer's credit line is freed. An abandoned hold is a support ticket.
5. Verify the captured transaction via PaymentGW/GetTransaction, and confirm it broadcasts. Result: Auth-then-capture pattern compatible with Israeli e-commerce flows.

Example 6: Refund a Failed Order

User says: "Customer disputed order #5678, I need to refund." Actions:

1. Pull the original PelecardTransactionId from your order record (you stored it from Phase 1 / IPN).
2. Check whether it has been broadcast (/services/GetTransDataBeforeBc). If it is still in the open batch, void it with /services/DeleteTran: it never settles, so no clearing fee. A pending line may still be visible in the customer's card app for a while, so don't promise otherwise. If it has already been broadcast you need a credit, and the credit path is not documented here (Step 6) -- get it from Pelecard rather than guessing.
3. Persist the identifier of the void or credit leg against the original order.
4. Honor the Israeli Consumer Protection Law deadlines: 14 days to refund from the cancellation notice, fee capped at 5% or 100 ₪ (whichever is lower).
5. Issue the credit note (חשבונית זיכוי) via your invoice provider, or via Pelecard's own /services/CreateInvoice family. Result: Refund processed within the legal window.

Bundled Resources

References

• references/api-endpoints.md -- The verified endpoint catalogue: host model, the three /PaymentGW endpoints with their real response envelopes, and the /services surface (charge, authorize, void, tokens, lookup, broadcast, 3DS, invoices) with parameter names.
• references/payment-parameters.md -- The iframe (PaymentGW/init) parameter reference: ActionType, Currency, tashlumim, tokenization, BIN controls, UI customization, feedback URLs, passthrough fields.
• references/error-codes.md -- The full status-code table (254 assigned codes, English + Hebrew, swept from Pelecard's credential-free lookup), plus a retry policy and the EMV/Shva note.

Scripts

• scripts/validate_pelecard_response.py -- Shape-checks a Pelecard callback JSON and, with --resolve-codes, resolves a failing status code to Pelecard's own bilingual message. --explain <code> looks one up directly. Run --help.

Recommended MCP Servers

No Pelecard MCP exists yet. Pair with the green-invoice skill for the Israeli tax document (חשבונית מס), or use Pelecard's own /services/CreateInvoice family.

Reference Links

Gotchas

• The hostname is not an environment switch. gateway20 and gateway21 serve the same API; both answer PaymentGW/init, GetTransaction and ValidateByUniqueKey identically, and gateway20.pelecard.biz/sandbox is a UI page, not a separate API host. Test-versus-live is decided by the terminal and credentials. Keep host + terminal + credentials in one config object and swap them as a unit; never let code infer safety from a hostname.
• There is no refund endpoint under /PaymentGW, and no credit endpoint anywhere in the public builder. Voids before broadcast are /services/DeleteTran; the post-broadcast credit path must come from Pelecard. Do not improvise one with a negative total.
• An approval number is not money. A transaction settles only after the terminal broadcasts to Shva. Alert on anything sitting in /services/GetTransDataBeforeBc longer than one broadcast cycle.
• 302 means the debit succeeded; 301 and 303 mean the outcome is unknown. Only 302 says money moved. Resolve the other two by lookup before touching the order.
• The two surfaces use different parameter casing. /PaymentGW takes terminal / Total / Currency / ParamX; /services takes terminalNumber / total / currency / paramX, and a couple of token endpoints use PascalCase credentials. Copy the preset from https://gateway21.pelecard.biz/services rather than guessing.
• A failed init returns HTTP 200 with a blank URL. Check Error.ErrCode, not the HTTP status.
• Wrong ActionType silently changes whether money moves. J2 is registration-only and does not charge, but the merchant UI looks identical to J4. Default to J4. Plugin v1.4.7: "Bypass validation for J2 transactions."
• A J5 taken without CreateToken may be uncapturable. The /services debit types need a creditCard or a token, and an iframe J5 gives you neither by default.
• Pelecard does NOT sign IPN deliveries with HMAC. Protections: re-verify every callback via PaymentGW/GetTransaction, restrict your feedback URLs to Pelecard's outbound IP allowlist, enforce TLS 1.2+. Never trust a payload just because its ConfirmationKey looks familiar.
• PelecardTransactionId is your inbound dedupe key, not ParamX. Pelecard may deliver one IPN twice (timeout retry). ParamX is your order id and repeats; PelecardTransactionId is unique per attempt.
• Bit's no-installments rule is absolute, the 5,000 ₪ cap is operator-tier-set. From allpay.co.il: "No installments. You can only pay with Bit in one payment." Hide the tashlumim selector, gate to your agreed cap, and send Currency: 1.
• The credentials triple is server-side only, and money fields are agorot (Total: 9900 = ₪99.00). Do a 1 ₪ test charge before going live.

Troubleshooting

Error: Callback received but PaymentGW/GetTransaction returns "transaction not found"

Cause: The terminal you are querying with is not the terminal the transaction was made on (a test terminal looking up a live transaction, or vice versa). Verified NOT to be a host problem: gateway20 and gateway21 serve the same API, so switching hosts will not fix this. Solution: Confirm the terminal number and credentials match the transaction. POST /services/GetTerminalName with the credentials triple is the cheapest check that your credentials resolve to the terminal you expect. Then re-run the lookup.

Error: ConfirmationKey missing from callback

Cause: The customer abandoned mid-flow, or the request was tampered with. Solution: Treat the order as unpaid. Do NOT mark it paid even if PelecardStatusCode looks like success; resolve it with a paramX lookup instead.

Error: Bit payment fails for amounts above 5,000 ₪

Cause: Bit's per-transaction cap is set by the merchant's Bit agreement and operator risk tier; 5,000 ₪ is the commonly-cited default. Solution: Gate the Bit option to the cap your agreement allows, surface a "Bit limited to " message, offer card as the alternative, and confirm Currency: 1.

Error: 3DS challenge appears in sandbox but transaction is rejected

Cause: A challenge on a test terminal needs specific test cards and challenge responses configured per terminal. Status 650 is "3DS process failed"; resolve any code with /services/GetErrorMessageEn. Solution: Ask Pelecard which test cards and challenge codes work against your terminal. The Initiate / AskForChallenge toggles control whether 3DS is invoked at all.

Error: Token charge succeeds but customer claims no payment

Cause: J5 (authorize) was used instead of J4 (sale), and capture was never triggered. Solution: Verify the ActionType on the original transaction via PaymentGW/GetTransaction. If it was J5 or J5h, capture it by posting a debit carrying the authorizationNumber from the authorization, or release it with /services/DeleteIshur. Default to J4 for one-shot sales. If the ActionType was J4 and it still has not settled, check /services/GetTransDataBeforeBc -- an un-broadcast J4 is approved but not yet money.