איך לחבר סליקה של HYP

Base Configuration
Hypay Gateway Base URL:
https://pay.hyp.co.il/p/

All requests MUST include:

UTF8=True
UTF8out=True
A transaction is considered approved ONLY if GetTransDetails returns CCode=0

Supported Payment Flow (Mandatory)
Hypay does NOT return a payment page directly. The integration MUST follow the exact flow defined below.

No other payment creation flow is allowed.

Step 1 - Create Payment Link (APISign SIGN)
The integration MUST expose a backend function named:

createPaymentLink

This function is the ONLY supported way to create a hosted payment page.

Function behavior
The function MUST execute an APISign SIGN request server-side
The function MUST construct and return a final hosted payment URL
The function MUST NOT expose the raw SIGN response to the frontend
SIGN request requirements
The SIGN request MUST be sent server-side with the following parameters:

action=APISign
What=SIGN
KEY from HYPAY_API_KEY
PassP from HYPAY_PASSP
Masof from HYPAY_MASOF
Order (string, required)
Amount (string or number, required)
Info (string, optional)
Coin (optional, default 1 for ILS)
Tash (optional, default 1)
UTF8=True
UTF8out=True
Sign=True
MoreData=True
Step 2 - Build Hosted Payment Page URL (Mandatory)
The APISign SIGN response ALWAYS returns a full query string containing all required payment parameters.

This response is NOT a payment page. It MUST be converted into a hosted payment page URL exactly as described below.

Required behavior
After receiving the SIGN response:

The integration MUST treat the response as a complete query string
The integration MUST NOT modify, remove, or transform any parameters
The integration MUST concatenate the response as-is to the Hypay gateway base URL
Final payment URL format
https://pay.hyp.co.il/p/?[SIGN_RESPONSE_QUERY_STRING]

Example
SIGN response returned by Hypay: Amount=10&Masof=0010238925&MoreData=True&PageLang=HEB&Tash=5&UTF8out=True&action=pay&tmp=10&signature=fb34d05bd6f50f065f2eb97b98b133cd43964360397f16911abd51589d073442

Final hosted payment page URL:

https://pay.hyp.co.il/p/?Amount=10&Masof=0010238925&MoreData=True&PageLang=HEB&Tash=5&UTF8out=True&action=pay&tmp=10&signature=fb34d05bd6f50f065f2eb97b98b133cd43964360397f16911abd51589d073442

The integration MUST NOT attempt to rebuild or reinterpret the query string. The response MUST be concatenated exactly as received.

Output contract
The createPaymentLink function MUST return JSON in the following structure:

{
  "paymentUrl": "https://pay.hyp.co.il/p/?Amount=10&Masof=0010238925&MoreData=True&PageLang=HEB&Tash=5&UTF8out=True&action=pay&tmp=10&signature=fb34d05bd6f50f065f2eb97b98b133cd43964360397f16911abd51589d073442"
}

The frontend MUST open this URL using redirect, new tab, or iframe. The frontend MUST NOT alter the URL in any way.

Payment Completion and Redirect

After the user completes the payment, Hypay redirects the browser to the Success or Failure URL configured in the Hypay terminal.

The redirect includes transaction parameters in the query string (GET).

These parameters MUST NOT be trusted on the client.

Step 3 - Retrieve Transaction Details (GetTransDetails) (Mandatory)
After receiving the payment redirect, the backend MUST retrieve the transaction identifier and invoke GetTransDetails to determine the final transaction status.

The integration MUST expose a backend function named:

getTransactionDetails

This function is the PRIMARY authority for determining the final transaction status.

Purpose
GetTransDetails retrieves the authoritative transaction record directly from the Hypay system after payment completion.

A transaction is considered successful ONLY if GetTransDetails returns CCode=0.

Request requirements
The request MUST be executed server-side and signed.

Required parameters:

Masof from HYPAY_MASOF
id (transaction identifier received from Hypay)
type (string, e.g. trans or integration-specific identifier)
partner=hyp
signature (HMAC calculated according to Hypay specification)
Example request
GET https://icom.yaad.net/cgi-bin/yaadpay/getdetails.pl/GetTransDetails?Masof=0010212011&id=TRANSACTION_ID&partner=hyp&type=base44&signature=...

Approval rule
The transaction MUST be marked as successful ONLY if:

CCode=0 is returned by GetTransDetails
Any other result MUST be treated as:

failed
or pending (if data is unavailable)
Transaction Status Authority
The integration uses multiple mechanisms during the payment lifecycle:

Redirect parameters: UX indication only
APISign VERIFY: validation and logging
GetTransDetails: authoritative transaction status
Final transaction approval MUST be based on GetTransDetails only.

APISign VERIFY MUST still be executed for validation, logging, and discrepancy detection, but does not block or determine approval. The transaction identifier (id) MUST be extracted from the payment redirect parameters returned by Hypay.

Step 4 - Verify Transaction (APISign VERIFY)

The integration MUST expose a backend function named: verifyTransaction

This function is used for validation, logging, and discrepancy detection only.

Verification rules

The frontend MUST forward all received query parameters to the backend

The backend MUST perform an APISign VERIFY request

The backend MUST parse and log the verification response

VERIFY request requirements

action=APISign

What=VERIFY

KEY from HYPAY_API_KEY

PassP from HYPAY_PASSP

Masof from HYPAY_MASOF

All query parameters received from the Hypay redirect

Approval rule

VERIFY results MUST NOT determine final transaction approval and MUST NOT change the business status of the transaction.

Verification Failure Handling (Mandatory)
VERIFY failures MUST be logged and flagged for review, but do not determine the final transaction status.

Redirect parameters alone MUST NEVER be used to approve a payment. Final approval is determined only via GetTransDetails.

Output contract

The verifyTransaction function MUST return: { "ok": true, "raw": "full verify response" }

or { "ok": false, "raw": "full verify response" }

The raw field MUST be used for internal diagnostics only and MUST NOT be exposed to end users.

The frontend MUST NOT use the VERIFY result to determine payment success. User-facing success or failure MUST be based only on GetTransDetails.

Mandatory Security Rules

The frontend MUST NEVER approve payments based on URL parameters

APISign VERIFY MUST be executed server-side for validation and logging purposes only.

VERIFY results MUST NOT determine final transaction approval. Final approval is determined only by GetTransDetails.

The SIGN response MUST NEVER be exposed to the frontend

The hosted payment URL MUST always be created by the backend

Unsupported Patterns (Explicitly Forbidden)

The following patterns MUST NOT be implemented:

Returning raw SIGN responses to the frontend

Constructing the payment URL on the frontend

Skipping APISign VERIFY (required for validation and diagnostics)

Approving payments based on redirect parameters

Implementing multiple payment creation flows

Summary

This integration supports exactly one valid payment flow:

Backend creates a hosted payment URL using APISign SIGN

Frontend redirects the user to the returned payment URL

Backend performs validation and diagnostics using APISign VERIFY

Payment success is determined by querying the transaction status using GetTransDetails and verifying that CCode=0 is returned.

VERIFY and redirect parameters are informational and diagnostic only, and MUST NOT determine final transaction approval.

Any deviation from this flow is unsupported.

Logging and Diagnostics (Mandatory)
The integration MUST implement clear and structured logging for all interactions with the Hypay gateway.

Logging is required for troubleshooting, monitoring, and support.

General logging rules
Logs MUST be written server-side only
Logs MUST NOT expose secrets (KEY, PassP) or signatures
Logs SHOULD include a correlation identifier (Order / Transaction ID)
Logs MUST be descriptive enough to understand the failure reason
SIGN request logging
When executing APISign SIGN, the system MUST log:

The attempt to create a payment link
Order identifier
Amount
Result status (success / failure)
Error message or gateway response summary on failure
Example (conceptual):

"SIGN request started for Order=12345"
"SIGN request succeeded for Order=12345"
"SIGN request failed for Order=12345: timeout"
VERIFY request logging
When executing APISign VERIFY, the system MUST log:

Verification attempt started
Order / Transaction identifier
Verification result (CCode if returned)
Failure reason (network error, invalid response, non-zero CCode)
Example (conceptual):

"VERIFY started for Order=12345"
"VERIFY returned CCode=0 for Order=12345"
"VERIFY failed for Order=12345: gateway timeout"
GetTransDetails logging
The system MUST log:

GetTransDetails request started
Transaction ID
Returned CCode
Final business status decision (success / failed / pending)
Pending transaction logging
If GetTransDetails cannot be completed, the transaction MUST be marked as pending