Authorize / Capture Request

🔄 Authorize / Capture

⚠️Important Note

Authorize and Capture features are only available with the MPGS payment gateway service.

📖 Refere more about Hesabe Payment Intergrations [ 🔗 Click Here ]

🔒

Two-Step Payment Process

The Authorize/Capture payment flow is a two-step process that allows merchants to authorize a transaction first (ensuring funds availability) and capture the funds later when ready to deliver the service or product.

🎯 Authorize Transaction Request

To authorize a transaction, include the following parameter in the checkout request:

🔐authorize: Boolean flag to indicate authorization

Authorize Transaction Request

🏷️ Environment	📝 End Points
Sandbox	http://sandbox.hesabe.com/api/checkout
Production	https://api.hesabe.com/api/checkout

To authorized transaction, send a POST request with the following parameters:

🏷️ Field	📋 Type	📝 Description
amount	Numeric	Amount in currency
currency	String	ISO currency code
responseUrl	String	Redirect URL on success
failureUrl	String	Redirect URL on failure
merchantCode	Numeric	Assigned by Hesabe
paymentType	Numeric	2 (Visa/MasterCard)
version	String	API version (e.g., 2.0)
orderReferenceNumber	String	Your reference/order ID
variable1-5	String	Optional key-value pairs (Label__Value)
name	String	Customer name
mobile_number	Numeric (8)	Customer mobile (no country code)
email	String	Customer email
saveCard	Boolean	Save card for tokenization
cardId	String	Tokenized card ID
authorize	Boolean	1 (Authorization-only transaction)
webhookUrl	String	Your endpoint for receiving payment status

Capture Transaction Request

🏷️ Environment	📝 End Points
Sandbox	http://sandbox.hesabe.com/api/capture
Production	https://api.hesabe.com/api/capture

To capture the authorized transaction, send a POST request with the following parameters:

🏷️ Parameter	📝 Description
merchantCode	Merchant Code is a unique identifier generated by Hesabe for each activated merchant
amount	Transaction amount equal to or less than the authorized transaction amount
paymentToken	Payment Token returned from the authorized transaction

Sample PHP Code for capture:

$baseUrl = 'http://sandbox.hesabe.com/api/'; // sandbox
$captureApiUrl = $baseUrl . 'capture';
$requestData = [
    'merchantCode' => 842217,
    'amount' => 10,
    'paymentToken' => '84221717175011419773484853173'
];
$encryptedData = HesabeCrypto::encrypt($requestData, $encryptionKey, $ivKey);
$checkoutRequestData = new Request([
    'data' => $encryptedData
]);
$checkoutRequest = Request::create($captureApiUrl, 'POST', $checkoutRequestData->all());
$checkoutRequest->headers->set('accessCode', $accessCode);

Response sample for capture

{
    "status": true,
    "message": "Your refund request is waiting for approval",
    "data": {
        "token": "521042117249344539468767555844",
        "amount": "1.000",
        "order_reference_number": "1724934434",
        "transaction_status": "SUCCESSFUL",
        "refund_status": "PENDING",
        "payment_type": "KNET",
        "service_type": "Payment Gateway",
        "transaction_datetime": "2024-08-29 15:27:38",
        "refund_requested_at": "2024-09-04 15:04:44"
    }
}

Cancel Authorized Transaction

To cancel the Authorized transaction for further Capturing the Amount.

$baseUrl =  'http://sandbox.hesebe.com/api/' // sandbox
$CancelApiUrl = {{$baseUrl}}/cancel/{paymentToken}
$checkoutRequest = Request::create($CaptureApiUrl, 'DELETE');
$checkoutRequest->headers->set('accessCode', $accessCode);