grow-payment-gateway

name	grow-payment-gateway
description	Integrate Grow by Meshulam payment gateway into Israeli applications -- covers payment pages (iframe/redirect/SDK), tokenization, recurring billing, payment links, refunds, invoices, webhooks, and 3DS authentication via the Grow Light API. Use when user asks to accept payments via Grow or Meshulam, set up "slikat ashrai" with Grow, create payment links (drishat tashlum), handle recurring charges (hora'ot keva) via Grow tokens, process refunds or Bit cancellations, integrate Grow webhooks, or mentions "Grow", "Meshulam", "grow-il", "meshulam.co.il", Grow payment page, or Grow API. Prevents costly integration mistakes by guiding correct FormData request format, server-side-only restrictions, and the mandatory approveTransaction step that many developers miss. Do NOT use for Cardcom integration (use cardcom-payment-gateway), Tranzila integration (use tranzila-payment-gateway), general payment orchestration across multiple gateways (use israeli-payment-orchestrator), or non-payment queries.
license	MIT

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: [e-mail]

Instructions

Step 1: Understand Grow's Authentication

Grow uses three credentials provided during merchant onboarding:

Credential	Purpose	Notes
userId	Merchant identifier	Unique per business account
pageCode	Payment page configuration	Different page codes for different payment types (credit card, Bit, recurring, etc.)
apiKey	API authentication	Required when managing multiple businesses or specific configurations

Environments:

Environment	Base URL
Sandbox (testing)	https://sandbox.meshulam.co.il
Production	https://secure.meshulam.co.il

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. This is a common mistake -- if you send application/json, the API will reject the request.

Step 2: Choose Your Integration Pattern

Pattern	How It Works	Best For
Payment Page (iframe/redirect)	Grow hosts the payment form; you embed via iframe or redirect	E-commerce checkout, one-time payments
SDK Wallet	Modular JS SDK embedded in your page	Custom UX without iframe/redirect overhead
Payment Link	Generate a URL to send to customers	Invoicing, freelancer billing, remote payments
Token Charge (server-to-server)	Charge a saved token directly	Recurring billing, subscriptions, repeat customers

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:

Parameter	Type	Description
pageCode	string	Payment page identifier (provided by Grow)
userId	string	Your merchant ID
sum	number	Payment amount (e.g., 10.99)
successUrl	string	Redirect URL after successful payment (HTTPS required)
cancelUrl	string	Redirect URL if payment is cancelled
description	string	Product/service description
pageField[fullName]	string	Customer name (must contain at least two names)
pageField[phone]	string	Valid Israeli mobile phone number

Optional parameters:

Parameter	Type	Description
pageField[email]	string	Customer email
paymentNum	integer	Fixed number of installments (1-12)
maxPaymentNum	integer	Max installments customer can choose (2-N)
chargeType	integer	1 = regular charge
notifyUrl	string	Server-to-server callback URL
invoiceNotifyUrl	string	Invoice webhook URL
cField1 - cField9	string	Custom merchant fields (passed back in callbacks)
transactionTypes[]	array	Restrict which payment methods appear (SDK-wallet pages only). Each method is a fixed array index, see table below

Payment methods (transactionTypes) -- SDK-wallet pages only. Each method maps to a FIXED array index (there are no numeric value-codes; include a method by setting its index):

Index	Payment Method
transactionTypes[0]	Credit Card
transactionTypes[1]	Bit
transactionTypes[2]	Apple Pay
transactionTypes[3]	Google Pay
transactionTypes[4]	Bank transfer
transactionTypes[5]	Pay Box

Invoice line items (optional):

Parameter	Type	Description
productData[0][catalogNumber]	integer	Item catalog number
productData[0][quantity]	integer	Item quantity
productData[0][price]	number	Item price
productData[0][itemDescription]	string	Item description

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]=[e-mail]" \
  -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: The payment page URL is valid for 10 minutes. Generate a fresh URL for each checkout session.

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

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"

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

Step 6: Query Transaction Details

Get transaction info:

POST /api/light/server/1.0/getTransactionInfo

Parameter	Type	Description
pageCode	string	Page identifier
transactionId	string	Transaction ID to query

Get payment process info:

POST /api/light/server/1.0/getPaymentProcessInfo

Parameter	Type	Description
pageCode	string	Page identifier
processId	string	Process ID from createPaymentProcess

Step 7: Process Refunds

Refund a credit card transaction:

POST /api/light/server/1.0/refundTransaction

Parameter	Type	Description
pageCode	string	Page identifier
transactionId	string	Transaction to refund
refundSum	number	Amount to refund (partial or full)

Cancel a Bit transaction:

POST /api/light/server/1.0/cancelBitTransaction

Parameter	Type	Description
pageCode	string	Page identifier
transactionId	string	Bit transaction to cancel

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

Parameter	Type	Description
pageCode	string	Page identifier
userId	string	Merchant ID
sum	number	Payment amount
description	string	Payment description
pageField[fullName]	string	Customer name
pageField[phone]	string	Customer phone
pageField[email]	string	Customer email

The response includes a shareable payment URL. You can also update (updatePaymentLink) or query (getPaymentLinkInfo) existing links.

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 (or from the getTokenOnly endpoint, which saves a card without charging). Use that value as the cardToken in the createTransactionWithToken calls below.

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, or from getTokenOnly). Check statusCode in the response (2 = paid) to confirm the charge succeeded. This endpoint uses userId, not pageCode.

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:

POST /api/light/server/1.0/updateRecurringPayment -- change amount, pause, or cancel.

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

Parameter	Type	Description
pageCode	string	Page identifier
transactionId	string	Suspended transaction to settle

Step 11: Configure Webhooks

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

Webhook trigger options:

Trigger	Description
All one-time transactions	Every payment across all pages
Specific payment pages	Filter by page code
Specific payment links	Filter by payment link
Recurring payments	From 2nd charge onward
Failed recurring	When a recurring charge fails
POS transactions	In-person payments
Invoice creation	When invoices are generated
Mobile app transactions	Payments via Grow app

Common webhook payload fields:

Field	Description
webhookKey	Unique webhook identifier
statusCode	Payment status code, 2 = paid (success). Branch on this server-side to confirm the payment succeeded before fulfilling; a client redirect alone is not proof
transactionToken	Saved card token, keep it to charge later via createTransactionWithToken for recurring/repeat billing
transactionCode	Transaction reference
paymentSum	Amount charged
paymentDate	Transaction timestamp
fullName	Payer name
payerPhone	Payer phone
payerEmail	Payer email
cardSuffix	Last 4 digits of card
cardBrand	Card brand (Visa, Mastercard, etc.)
asmachta	Reference number (asmakhta)
paymentSource	Origin (page, link, POS, etc.)

Recurring payment webhook (additional fields):

Field	Description
directDebitId	Recurring series identifier
paymentsNum	Payment number in series
allPaymentNum	Total number of payments in the series (newer PaymentLinks payloads spell it allPaymentsNum)
periodicalPaymentSum	Recurring charge amount

Failed recurring webhook (additional fields):

Field	Description
error_message	Failure reason
charges_attempts	Number of retry attempts
regular_payment_id	Failed recurring payment ID

Invoice webhook (set via invoiceNotifyUrl):

Field	Description
transactionCode	Related transaction
invoiceNumber	Generated invoice number
invoiceUrl	URL to download invoice PDF

Step 12: Payment Page Types

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

Page Type	Description	Notes
SDK Wallet	Modular JS widget	No iframe/redirect needed
Generic	Credit card + Bit	Customizable, up to 2 extra fields
Credit Card	Card payments only	Supports regular and recurring
Google Pay	Google Pay only	Chrome on Android; requires allow="payment" on iframe
Apple Pay	Apple Pay only	Requires domain verification for iframe
Bit	Bit mobile payment	Best on mobile, full-screen recommended
Bit QR	QR code for Bit	For desktop/in-store display

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.

URL length limit: 2000 characters. Use cField values instead of long query strings.

Gotchas

• The most common integration mistake: Grow's API requires multipart/form-data for all requests, NOT application/json. Agents almost always default to JSON, which causes the API to reject the request silently or return a parsing error.
• All Grow API requests must originate from a server. Client-side (browser) requests are blocked with 403. Agents may generate frontend fetch() calls that will never work.
• 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

Problem	Cause	Solution
API returns 403 or empty response	Client-side request	Move API calls to your server; Grow blocks browser requests
Request returns parsing error	Using JSON content type	Switch to multipart/form-data (FormData), not application/json
Payment page URL expired	URL older than 10 minutes	Call createPaymentProcess again for a fresh URL
Webhook not received	Webhooks not enabled	Contact [e-mail] to enable
Transaction not found	Wrong environment	Ensure sandbox transactions are queried against sandbox URL
Recurring charge failed	Expired card	Enable premium recurring for automatic card expiry updates
localhost in successUrl	Not allowed	Use a tunnel (ngrok) or deployed URL for testing
iframe blank on HTTP	HTTPS required	Serve your page over HTTPS
Apple Pay iframe fails	Domain not verified	Complete Apple domain verification via Grow dashboard

Reference Links

Source	URL	What to Check
Grow API Reference	https://developers.grow.business/reference/overview	Current endpoints, transactionTypes indices, request/response shapes
Grow Documentation	https://developers.grow.business/docs	Tokenization, recurring, J-code installments, webhooks
Grow Product Overview	https://developers.grow.business/docs/about-grow-products	Which Grow products exist and how they map to API surface
Meshulam (Grow) Production Base	https://secure.meshulam.co.il/	Confirms production host; do not point production traffic at sandbox.meshulam.co.il
Wix Integration Guide	https://support.wix.com/en/article/connecting-grow-by-meshulam-as-a-payment-provider	High-level integration walkthrough for Wix merchants