Grow Payment Gateway (Meshulam)

Overview

Grow (formerly Meshulam) is one of Israel's leading payment gateways, powering thousands of businesses with credit card processing, Bit payments, Apple Pay, Google Pay, and more. Unlike other Israeli gateways, Grow offers a unified API (the "Light API") that covers payment pages, tokenization, recurring billing, payment links, invoices, and webhooks in a single integration.

This skill guides integration with Grow's Light API for the full payment lifecycle: accepting payments, saving tokens for recurring charges, creating payment links for invoices, processing refunds, and handling real-time webhook notifications.

Official docs: https://developers.grow.business/

Developer support: [email protected] (carried from an earlier cycle; not confirmed against Grow's published documentation this cycle, so confirm it in your merchant portal before relying on it).

Instructions

Step 1: Understand Grow's Authentication

Grow uses three credentials provided during merchant onboarding:

Environments:

Critical: Server-side only. All API requests must originate from your server. Client-side (browser) requests are blocked by Grow.

Critical: FormData format. All request bodies use multipart/form-data, NOT JSON. If you send application/json the API does not parse your fields at all, so you get a misleading validation error about a missing or invalid field rather than a content-type error.

Critical: every response is HTTP 200. The Light API signals failure in the body, never in the status line. A successful call returns status: 1; a failure returns status: 0 with an err object. Branch on status and err, never on the HTTP code. See the Error Codes section.

err changes shape, three ways. On a validation failure err is an object {"id": 707, "message": "..."}. On an unrecognised endpoint name err is the plain string "unknown method". And err.id is itself sometimes an OBJECT: getTokenTransactionsByExternalIdentifiers returns err.id = {"id": 1012, "content": "..."} with the useful text in err.id.content and a generic err.message. Code doing err.id === 54 silently mismatches there, and logging err.id prints [object Object]. Normalise before comparing.

status is sometimes a JSON string and sometimes a number. The same endpoint returns "status":"0" on one input and "status":0 on another. Compare loosely (coerce to string) rather than with a strict === 1.

Step 2: Choose Your Integration Pattern

Most Israeli merchants use Payment Page for the first payment (which also saves a token), then Token Charge for recurring billing.

Step 3: Implement a Payment Page

This is the most common integration -- create a hosted payment page and redirect or iframe the customer to it.

Endpoint: POST /api/light/server/1.0/createPaymentProcess

Required parameters:

Optional parameters:

Payment methods (transactionTypes) -- SDK-wallet pages only. Two things matter and earlier versions of this skill got the second one wrong. The ARRAY INDEX selects the slot, and the VALUE is an integer method code. Both come from the createPaymentProcess schema on the official reference page:

Invoice line items (optional):

Example request:

curl -X POST https://sandbox.meshulam.co.il/api/light/server/1.0/createPaymentProcess \
  -F "pageCode=YOUR_PAGE_CODE" \
  -F "userId=YOUR_USER_ID" \
  -F "sum=149.90" \
  -F "successUrl=https://example.com/payment/success" \
  -F "cancelUrl=https://example.com/payment/cancel" \
  -F "description=Monthly subscription" \
  -F "pageField[fullName]=Israel Israeli" \
  -F "pageField[phone]=0501234567" \
  -F "pageField[email][email protected]" \
  -F "paymentNum=1" \
  -F "notifyUrl=https://example.com/api/grow/webhook" \
  -F "cField1=order-12345"

The response includes a url field -- redirect the customer there or embed as an iframe.

Important: treat the payment page URL as short-lived and generate a fresh one for each checkout session. A 10-minute window is the figure carried by this skill from earlier cycles; it is not stated on any Grow documentation page this cycle could fetch, so do not rely on the exact number.

Step 4: Handle the Payment Response

After the customer completes payment, two things happen:

1. Client redirect: Customer is redirected to successUrl with response=success appended
2. Server callback: Grow sends a POST to your notifyUrl with full transaction details

Always verify via server callback, not the client redirect (which can be spoofed). In the callback, confirm success by checking statusCode (2 = paid), do not treat the mere arrival of a redirect to successUrl as proof of payment.

Payload nesting (important): on the server-to-server notifyUrl callback the fields are nested under a data object (the top level is {err, status, data}), so read data.statusCode, data.transactionToken, and data.transactionId (the id you pass to approveTransaction), NOT the top level. The separate webhookKey webhook system (Step 11) delivers a flatter payload.

Step 5: Approve the Transaction (MANDATORY)

After receiving the server callback, you MUST call approveTransaction to confirm receipt. This does not alter the payment -- it closes the transaction loop with Grow.

Endpoint: POST /api/light/server/1.0/approveTransaction

approveTransaction requires both identifiers from the callback. Sending only transactionId fails with err.id 54 (חסרים נתונים:transactionToken), and sending only transactionToken fails with 54 for transactionId.

curl -X POST https://sandbox.meshulam.co.il/api/light/server/1.0/approveTransaction \
  -F "pageCode=YOUR_PAGE_CODE" \
  -F "transactionId=TRANSACTION_ID_FROM_CALLBACK" \
  -F "transactionToken=TRANSACTION_TOKEN_FROM_CALLBACK"

Do NOT call approveTransaction for: token-only saves, delayed (J4J5) transactions, or createTransactionWithToken charges.

What happens if you never call it is NOT documented and this skill does not guess. Grow's docs mark the step mandatory, and err.id 722 (לא ניתן לבצע אישור לעסקה שלא בוצעה או בוטלה) shows an approval can be refused. Whether funds are captured without it, whether there is an expiry window, and whether a late approval is still accepted could not be established without a merchant account. If you are recovering approvals after an outage, confirm the answer with Grow before choosing between replaying approvals and refunding, and do not assume either way.

Step 5.5: Do not trust the callback body on its own

The server callback is the trust anchor for fulfilment, and it is an unauthenticated public POST. Grow sends no signature header; webhookKey identifies the webhook, it is not a shared secret you can verify a payload against. Anyone who learns your notifyUrl can forge {statusCode: 2, ...} and take goods for free.

Before fulfilling any order:

1. Re-query Grow server-to-server with getTransactionInfo (transactionId + transactionToken) or getPaymentProcessInfo (processId + processToken). Treat the API answer as the truth, not the callback body.
2. Assert the returned amount equals the amount on YOUR order record. A forged or replayed callback that names a different sum must not fulfil.
3. Use an unguessable per-merchant notifyUrl path, and never log the URL where customers can see it.
4. Deduplicate on transactionId: a redelivered or replayed callback must fulfil once, not twice.

Step 5.6: Idempotency and retries

transactionUniqueIdentifier is your idempotency key on createTransactionWithToken. Send a value that is stable per logical charge, not per attempt.

• On a network timeout or a 5xx where you do not know whether the card was charged, do NOT blind-retry with a fresh identifier: that is how a customer gets billed twice. Re-send the SAME transactionUniqueIdentifier, or reconcile first with getTokenTransactionsByExternalIdentifiers.
• err.id 712 (העסקה כבר בוצעה) is the replay signal, not a bug. Treat it as "already charged, succeed" rather than as a failure to retry.

Step 6: Query Transaction Details

Get transaction info:

POST /api/light/server/1.0/getTransactionInfo

Get payment process info:

POST /api/light/server/1.0/getPaymentProcessInfo

Step 7: Process Refunds

Refund a credit card transaction:

POST /api/light/server/1.0/refundTransaction

Refund-specific failures worth handling: 105 and 218 (refund larger than the original), 130 and 207 (partial refund on a transaction settled or transmitted today), 210 (already refunded), 110 (funds already transferred to the bank, so the request goes to manual approval).

Cancel a Bit transaction:

POST /api/light/server/1.0/cancelBitTransaction

This endpoint is keyed by the PROCESS, not the transaction. Sending transactionId returns err.id 54 for processId.

Step 8: Create Payment Links

Payment links (drishat tashlum) let you send a payment URL to customers via email, SMS, or WhatsApp. Useful for invoicing and remote payments.

Endpoint: POST /api/light/server/1.0/createPaymentLink

The response includes a shareable payment URL. Query an existing link with getPaymentLinkInfo, which requires paymentLinkProcessToken (omitting it returns err.id 54 naming that field).

updatePaymentLink is not available on the Light API. Probed against both sandbox.meshulam.co.il and secure.meshulam.co.il, it returns {"err":"unknown method"}, the same response the router gives for an endpoint name that does not exist, and distinct from the permission errors (300, 714, 715) a real-but-unauthorised endpoint returns. Create a replacement link instead.

Step 9: Tokenization and Recurring Billing

Where the token comes from: the saved card token arrives in the payment webhook's transactionToken field after the first payment. Use that value as the cardToken in the createTransactionWithToken calls below.

getTokenOnly does not resolve on the Light API path. Grow's reference nav still lists a "Get Token Only" operation, but POST /api/light/server/1.0/getTokenOnly returns {"err":"unknown method"} on BOTH hosts and across casing variants, which is the router's answer for a name it does not know. Do not code against this path. To save a card without charging it, run a payment through a page code configured for tokenization and take the token from the callback, or confirm the current operation with Grow support.

Grow supports three recurring payment models:

Option A: Grow-Managed via Page Code

Use a dedicated recurring page code configured in the Grow dashboard:

1. Create payment with createPaymentProcess using the recurring page code
2. Set sum to the monthly charge amount and paymentNum to total iterations
3. Grow handles all subsequent charges automatically

Option B: Charge a Saved Token (server-to-server)

Charge a saved card token directly. The token parameter is cardToken (NOT token), and paymentType=2 is a Regular charge:

curl -X POST https://sandbox.meshulam.co.il/api/light/server/1.0/createTransactionWithToken \
  -F "userId=YOUR_USER_ID" \
  -F "sum=99.00" \
  -F "description=Monthly subscription" \
  -F "cardToken=SAVED_CARD_TOKEN" \
  -F "paymentType=2" \
  -F "pageField[fullName]=Israel Israeli" \
  -F "pageField[phone]=0501234567" \
  -F "transactionUniqueIdentifier=UNIQUE_PER_CHARGE"

cardToken is the saved card token; it arrives in the payment webhook's transactionToken field. Check statusCode in the response (2 = paid) to confirm the charge succeeded. This endpoint uses userId, not pageCode, and it also requires paymentNum (omitting it returns err.id 54 for paymentNum); send paymentNum=1 for a single non-instalment charge.

Option C: Premium Recurring Series (recurringDebitId)

For a Grow-managed recurring series, each charge carries a recurringDebitId that ties it to the series. That id is returned by the FIRST premium-recurring payment's response; pass it on every subsequent createTransactionWithToken call, alongside cardToken, paymentType=2, and the required fields above:

curl -X POST https://sandbox.meshulam.co.il/api/light/server/1.0/createTransactionWithToken \
  -F "userId=YOUR_USER_ID" \
  -F "sum=99.00" \
  -F "description=Monthly subscription" \
  -F "cardToken=SAVED_CARD_TOKEN" \
  -F "paymentType=2" \
  -F "pageField[fullName]=Israel Israeli" \
  -F "pageField[phone]=0501234567" \
  -F "recurringDebitId=RECURRING_DEBIT_ID" \
  -F "transactionUniqueIdentifier=UNIQUE_PER_CHARGE"

Confirm the exact premium-recurring initiation parameters on the createTransactionWithToken reference (see Reference Links) rather than assuming a flag name.

Update recurring payment:

updateRecurringPayment is NOT available on the Light API: probed against both hosts it returns {"err":"unknown method"}. The live endpoint for changing a direct-debit series is POST /api/light/server/1.0/updateDirectDebit. Confirm its parameter set on the Update Direct Debit reference page before wiring it, and expect err.id 180 (פעולת עידכון לא בוצעה, רשומה לא נמצאה) when the series id does not match.

Token transaction lookup:

POST /api/light/server/1.0/getTokenTransactionsByExternalIdentifiers -- find all transactions for a given token using external reference IDs.

Premium recurring features:

• Automatic card update on expiration (new expiry date applied to existing token)
• Card transfer support when customer switches cards
• Distinct billing line on customer's credit card statement

Step 10: Delayed Payments (J4J5 Installments)

J4J5 allows 4 interest-free installments (tashlumim l'lo ribit), a popular payment option in Israel:

Create delayed payment:

POST /api/light/server/1.0/createPaymentProcess with J4J5 page code

Settle when ready:

POST /api/light/server/1.0/settleSuspendedTransaction

This endpoint is keyed by userId, NOT pageCode. Sending pageCode returns err.id 54 for userId.

Settlement is capped: err.id 814 means the charge exceeded the authorised hold by more than 30 percent, and 804 means it exceeded the hold entirely. 803 means the J5 authorisation expired, and 808 means the transaction was already settled.

Related: createFarPaymentRequest also exists on the Light API (verified live on both hosts). It is not covered by this skill; read its reference page before using it.

Step 11: Configure Webhooks

Grow sends real-time notifications to your server for various events. Contact [email protected] to enable webhooks for your account.

Webhook trigger options:

Common webhook payload fields:

Recurring payment webhook (additional fields):

Failed recurring webhook (additional fields):

Invoice webhook (set via invoiceNotifyUrl):

Step 12: 3D Secure

3DS runs on Grow's hosted payment surface, not in your server code: the page or SDK wallet presents any challenge to the cardholder, and your integration sees only the final outcome in the callback. Grow documents it on a dedicated reference page (see Reference Links).

This skill does not restate the mechanics, because which page types run a challenge, whether it is merchant-configurable, and how the liability shift applies to a server-to-server createTransactionWithToken charge (a merchant-initiated transaction rather than a cardholder-present one) could not be verified without a merchant account. Read the 3DS reference page before you rely on a liability-shift assumption, and do not assume a token charge inherits the 3DS status of the original payment.

Step 13: Payment Page Types

Grow offers pre-configured payment page types, each with a different pageCode:

iframe integration:

<iframe src="PAYMENT_URL_FROM_API"
        width="100%" height="600"
        allow="payment"
        style="border: none;">
</iframe>

HTTPS is mandatory for iframe integrations. HTTP will not work.

Keep callback URLs short. Use cField1-cField9 to carry order context instead of long query strings. (Earlier cycles cited a 2000-character limit; that figure is not stated on Grow's published documentation, and 2000 is in any case the common browser rule of thumb rather than a Grow-specific API limit.)

Error Codes

Grow returns errors in the body with status: 0 and an err object carrying a numeric id. The full table is on the Errors reference page (see Reference Links); the codes an integration hits most often are below. Messages are Hebrew, as returned by the API.

Codes outside this published table exist. settleSuspendedTransaction with an unmatched userId returns err.id 743 (אין עסק תואם ל userId שנשלח), and createTransactionWithToken with an unknown userId returns 104. Treat any unrecognised err.id as a failure and surface err.message rather than assuming success.

Gotchas

• The most common integration mistake: Grow's API requires multipart/form-data for all requests, NOT application/json. Sending JSON does not produce a content-type error. The fields simply never parse, so you get a validation error about the first missing field (typically err.id 707, invalid amount), and agents then go hunting for a bug in the amount.
• Every response is HTTP 200, including every failure. An agent that checks response.ok or the status code will treat a declined or rejected call as a success. Branch on the body's status field (1 success, 0 failure) and on err.
• err is an object {id, message} for validation failures but the plain string "unknown method" when the endpoint name is not recognised. Type-check before reading err.id.
• All Grow API requests must originate from a server, but not because the API returns 403 to a browser. It answers a request carrying a browser Origin and Referer normally; what stops client-side use is that the API sends no CORS headers, so the browser blocks the response. The symptom is a CORS console error, not a 403. A real 403 from Grow means an X-API-KEY header was not sent.
• cardToken and transactionToken are not card data, but they ARE bearer credentials: anyone holding a cardToken can charge that card through your merchant account. Never log them, never put them in a URL or in client-side code, and encrypt them at rest. The hosted-page, iframe and payment-link patterns exist so raw card numbers never touch your server; do not accept, log, or proxy a PAN yourself.
• Amounts are Israeli shekels. The Bit ceiling (3,600) and the credit floor (25) in Grow's error table are both NIS. The API exposes no currency parameter in the calls this skill covers, so do not assume a foreign-currency charge can be expressed by changing sum.
• paymentNum and maxPaymentNum are mutually exclusive: sending both returns err.id 736. maxPaymentNum is also rejected on a standing-order page (739) and on an account configured for regular payments only (740).
• Bit has a per-transaction ceiling: err.id 271 is returned for a Bit payment above 3,600 NIS. A credit (kredit) transaction has its own floor, err.id 734: minimum 3 instalments and 25 NIS.
• After receiving a payment webhook, you MUST call approveTransaction to close the loop. Agents often skip this step, which leaves transactions in a pending state in Grow's system.
• Payment page URLs expire after 10 minutes. Agents may store and reuse a URL across sessions, leading to blank pages or errors.

Troubleshooting

Reference Links