# Handling Two-Phase Commits A two-phase commit is a transaction split into two steps: authorization and capture. Instead of charging the customer right away, you first "lock" the funds on their card to make sure they're available, and then finalize the charge later. In Israeli payment terminology, the authorization step is commonly called **J5**, while the capture step is known as **J4**. Hyp Pay supports two-phase commits through its payment page and API. It also offers a separate [postponement](/pay/common-use-cases/postponing-transactions.md) mechanism which, while it sounds similar, actually serves a different purpose. ## Two-phase commits vs postponing Two-phase commits and postponement handle things like card company approvals, transaction amounts, and fund holds differently. Use this table to help you pick the right one for your business: | Property | Two-phase commits (J5) | Postponing | | ----------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **Amount commitment** | You can authorize an amount and later charge that amount or less. | You must commit to the exact amount you initially requested. | | **Card compatibility** | Requires pre-approval from the issuer and may not support all card types. | Works independently of the issuer and supports all credit cards without special configuration. | | **Finalization window** | Provides a longer window, usually around 5 days. | Must be committed within 72 hours of the initial request. | ## When to use two-phase commits Two-phase commits are a great fit when you need to be 100% sure that funds are available before you commit to providing a service or product — especially if the final amount might change. * **Usage-based billing**. This is perfect for services like car rentals, hotel stays, or taxi rides. You can authorize an **estimated maximum amount** when the customer starts their journey to make sure they have enough credit. Once they're done, you capture the **actual final amount** due (as long as it doesn't exceed what you initially held). * **Large transactions**. For high-value purchases, you might want to verify that the customer's **credit limit** is enough before you start fulfilling the order. Since a J5 authorization actually blocks the funds, you get the peace of mind that the payment will go through when you're ready to capture it. * **Complex inventory management**. If your fulfillment process takes more than three days, two-phase commits are a better choice than postponing. The **longer authorization window** (typically around 5 days) gives you more time to check your stock and prepare the shipment before you finalize the charge. ## Implementing a two-phase commit Performing a two-phase commit with Hyp Pay takes three steps: starting the authorization through the payment page, getting the card token, and then finalizing the charge via the API. ### Step 1: Authorization (J5) To start a two-phase commit, add the `J5=True` parameter to your [payment page request](/pay/getting-started/creating-a-payment-page.md#create-a-payment-page-request). This tells Hyp Pay to check with the credit card company and **block the customer's funds** until you're ready to capture them. You should also include `MoreData=True` so that Hyp Pay passes the `UID` and `UserId` parameters in the redirect back to your site. You'll need these two values to finish the charge later. Here's an example of a payment page request for a J5 authorization: {% code overflow="wrap" %} ```http https://pay.hyp.co.il/p/?action=APISign&What=SIGN&KEY=your-api-key&PassP=your-api-password&Masof=0010345518&Amount=100&PageLang=ENG&J5=True&MoreData=True ``` {% endcode %} When a customer is done entering their payment details, Hyp Pay will redirect them back to your site. In this [payment completion redirect](/pay/getting-started/creating-a-payment-page.md#handle-the-redirect-back-to-your-website), a `CCode=700` means success — the authorization was granted and the funds are being held. If you're using a [custom error page](/pay/getting-started/prerequisites-and-initial-setup.md#configure-success-and-error-pages), Hyp will redirect the customer to it even though the authorization request was successful. If you've chosen to display errors on the payment page instead of using a custom error page, Hyp Pay will redirect to the success page. In either case, your page logic should check for `CCode=700` in the redirect URL. If it's present, **display a success message to the customer** confirming that their payment has been requested and will be charged later. From the redirect URL, you'll need to **save the values for `Id`, `ACode`, `UserId`, and `UID`**. You'll use `Id` to get a token, and the other three parameter values to perform a capture. ### Step 2: Saving a card token Between the authorization and the capture, you'll need to [get a card token](/pay/common-use-cases/tokenization.md). This token lets you reference the customer's card details in the capture step without you ever having to touch the card data yourself. To get the token, make a GET request to `https://pay.hyp.co.il/p/` with `action` set to `getToken`: {% code overflow="wrap" %} ```http https://pay.hyp.co.il/p/?action=getToken&Masof=0010020610&PassP=your-api-password&TransId=401594866 ``` {% endcode %} The request includes these parameters: * `action`: Set this to `getToken`. * `Masof`: Your terminal number. * `PassP`: Your API password. * `TransId`: This takes the value of the `Id` you saved from the payment completion redirect. A successful response looks like this (look for `CCode=0`): {% code overflow="wrap" %} ``` Id=401594866&CCode=0&Token=0505743578473060772&Tokef=3105&Fild1=&Fild2=&Fild3= ``` {% endcode %} **Save both the `Token` and `Tokef` values** to use during the capture step. ### Step 3: Capture (J4) When you're finally ready to charge the customer, you perform a "capture" request. In Hyp Pay, this is done by making a server-to-server API call that references the original authorization. Here's an example API request to capture a J5 transaction: {% code overflow="wrap" %} ```http https://pay.hyp.co.il/p/?action=soft&Masof=0010345518&PassP=your-api-password&UserId=000000000&ClientName=Jenny&Token=True&CC=4652588708969300772&Tmonth=05&Tyear=31&AuthNum=0463077&Amount=15&inputObj.originalAmount=1500&inputObj.originalUid=26031819235508822860136&inputObj.authorizationCodeManpik=7&Info=final%20charge ``` {% endcode %} This request uses the following parameters: * `action`: Set this to `soft`. * `Masof`: Your terminal number. * `PassP`: Your API password. * `UserId`: The Israeli ID you saved from the redirect in step 1. If the customer didn't enter one, just use `000000000`. * `ClientName`: The customer's first name. * `Token`: Set this to `True` since you're using a card token. * `CC`: The `Token` you saved in step 2. * `Tmonth` and `Tyear`: The month and year from the `Tokef` parameter you saved in step 2. * `AuthNum`: The `ACode` from the redirect in step 1. * `Amount`: The amount you want to charge now. This can be the same as or less than the authorized amount. * `inputObj.originalAmount`: The original authorized amount in currency subunits (like agorot or cents). * `inputObj.originalUid`: The `UID` value you saved from the redirect in step 1. * `inputObj.authorizationCodeManpik`: This is a static value — just set it to `7`. * `Info`: Any extra info you want to include with the transaction. A successful capture response looks like this: {% code overflow="wrap" %} ``` Id=404274302&CCode=0&Amount=15&ACode=0463077&Fild1=&Fild2=&Fild3=&Hesh=EZ ``` {% endcode %} In this response, `CCode=0` indicates that the capture was successful and the customer has been charged. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.hyp.co.il/pay/advanced-features/two-phase-commits.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.