Pre-authorization payment feature temporarily blocks the fund from the customer's account. Successful Pre-authorization can be settled only if the transaction has been captured. You can initiate "capture" action through Capture API. By default, reserved fund will be released after seven days if there is no "capture" action for that transaction.
You need a token from Get Card Token response to charge with Pre-authorization feature.
Pre-Authorization Charge Request
{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "C17550",
"gross_amount": 145000
},
"credit_card": {
"token_id": "< your token ID >",
"bank": "bni",
"type": "authorize"
}
}
The credit_card object in Charge request to configure Pre-authorization feature is identical with Card Payment Charge Request, with the additional attributes given below.
| JSON Attribute | Description | Type |
|---|---|---|
| token_id | Token ID represents customer's card information acquired from Get Card Token response. | String |
| type | Flag to indicate if the transaction is pre-authorized or automatically captured. Valid value: authorize. | String |
Pre-Authorization Charge Response and Notifications
{
"status_code": "200",
"status_message": "Success, Credit Card transaction is successful",
"transaction_id": "be4f3e44-d6ee-4355-8c64-c1d1dc7f4590",
"order_id": "C17550",
"gross_amount": "145000.00",
"payment_type": "credit_card",
"transaction_time": "2016-07-02 14:00:27",
"transaction_status": "authorize",
"fraud_status": "accept",
"approval_code": "003873",
"eci": "05",
"masked_card": "48111111-1114",
"bank": "bca",
"channel_response_code": "0",
"channel_response_message": "Approved",
"currency": "IDR",
"card_type": "credit",
"on_us": true
}
{
"masked_card": "48111111-1114",
"approval_code": "003873",
"bank": "bca",
"eci": "05",
"transaction_time": "2016-07-02 14:00:27",
"gross_amount": "145000.00",
"order_id": "C17550",
"payment_type": "credit_card",
"signature_key": "7156a83f0beb052c689e3775e60049062dd84379eda494b929704955957a41949df03c7010a0ad888347828f04b9288bdf541e044569372d1ab957295a6c5a14",
"status_code": "200",
"transaction_id": "be4f3e44-d6ee-4355-8c64-c1d1dc7f4590",
"transaction_status": "authorize",
"fraud_status": "accept",
"status_message": "midtrans payment notification",
"channel_response_code": "0",
"channel_response_message": "Approved",
"card_type": "credit",
"on_us": false
}
Pre-authorization Charge response is different from the Card Payment Charge response.
Successful Pre-authorization transaction is described as authorize and can be settled only if the transaction has been captured. To charge the customer after Pre-authorization, Capture Transaction method is used with transaction_status set to authorize.
If the transaction is captured, the transaction status is updated to capture and is ready for settlement.
Note
Charge method in a Pre-authorized transaction checks and places a temporary hold on a customer’s card, and reserves funds.
For settling the Pre-authorized transaction, use below Capture Transaction's method within seven days. After that, the Pre-authorized funds will be released back to the cardholder.
Approve the transaction when
fraud_status: challengeto accept it or, the transaction will get cancelled automatically during settlement.
Capture Transaction Method
| Endpoint | HTTP Method | Definition |
|---|---|---|
| BASE_URL/capture | POST | Capture a Pre-authorized transaction. |
Capture Transaction Request
{
"transaction_id" : "1ac1a089d-a587-40f1-a936-a7770667d6dd",
"gross_amount" : 55000 // <--- Value should not exceed the Charge Value on Pre-Authorization
}
| JSON Attribute | Description | Type |
|---|---|---|
| transaction_id | Transaction ID from Charge Pre-Authorization Response. | String |
| gross_amount | Total amount of transaction in IDR. Note: This value should not exceed gross_amount specified in Pre-Authorization Charge request. If left undefined, capture full transaction amount specified in Pre-Authorization Charge request. | Long |
Capture Transaction Response and Notification
{
"status_code": "200",
"status_message": "Success, Credit Card capture transaction is successful",
"transaction_id": "1ac1a089d-a587-40f1-a936-a7770667d6dd",
"order_id": "A27550",
"payment_type": "credit_card",
"transaction_time": "2014-08-25 10:20:54",
"transaction_status": "capture",
"fraud_status": "accept",
"masked_card": "48111111-1114",
"bank": "bca",
"eci": "05",
"gross_amount": "55000.00",
"channel_response_code": "0",
"channel_response_message": "Approved",
"currency": "IDR",
"card_type": "credit"
}
{
"status_code": "202",
"status_message": "Deny by Bank [MANDIRI] with code [01] and message [Refer to card issuer]",
"channel_response_code": "01",
"channel_response_message": "Refer to card issuer",
"bank": "mandiri",
"transaction_id": "79e92a1c-01b4-4383-bfb5-e00af4bdf05f",
"order_id": "order-11236345131993942",
"merchant_id": "G479619422",
"gross_amount": "7.00",
"currency": "IDR",
"payment_type": "credit_card",
"transaction_time": "2023-02-15 17:28:12",
"transaction_status": "deny",
"fraud_status": "accept",
"approval_code": "001122",
"masked_card": "43650203-6407"
}
{
"masked_card": "48111111-1114",
"approval_code": "T67700",
"bank": "bca",
"eci": "05",
"transaction_time": "2014-08-25 10:20:54",
"gross_amount": "55000.00",
"order_id": "A27550",
"payment_type": "credit_card",
"signature_key": "23a7036edb8171b926e5292c7729c6bd26ed3250e22aead55110e34086dbc8fb393e7d3b7f764428a27c76e77d0a3bb6a7ba867066b2fbf5dae9e0f8a6c0dc0d",
"status_code": "200",
"transaction_id": "1ac1a089d-a587-40f1-a936-a7770667d6dd",
"transaction_status": "capture",
"fraud_status": "accept",
"status_message": "midtrans payment notification",
"channel_response_code": "0",
"channel_response_message": "Approved",
"card_type": "credit"
}
Note
Capture transaction is triggered to capture the transaction balance when
transaction_status:authorize.The transaction status is updated to capture and is ready for settlement if bank response is successfully captured.
If bank response with unsuccessfully captured, Midtrans will respond with
transaction_status:denyon capture response and keeptransaction_status:authorizeas the latest status on Midtrans Get Transaction Status. Merchant can try to re-capture or cancel the transaction. if there is no action for up to 8 days, the transaction will expire.
| JSON Attribute | Description | Type |
|---|---|---|
| status_code | Status code of transaction charge result. | String |
| status_message | Description of transaction charge result. | String |
| transaction_id | Transaction ID given by Midtrans. | String |
| order_id | Order ID specified by merchant. | String |
| gross_amount | Total amount of transaction in IDR. | String |
| payment_type | The payment method used by the customer. Value: credit_card. Note: For any transactions using payment card (credit or debit), payment_type is credit_card. | String |
| transaction_time | Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. | String |
| transaction_status | Transaction status after charge card transaction. Possible values arecapture: Transaction is accepted by the bank and ready for settlement. deny: Transaction is denied by the bank or FDS.authorize: Card is authorized in Pre-authorization feature. | String |
| fraud_status | Detection result by Fraud Detection System (FDS). Possible values areaccept: Approved by FDS.deny: Denied by FDS. Transaction automatically failed. | String |
| approval_code | Approval code from payment provider for successful transaction. It can be used for refund. | String |
| eci | The 3D secure ECI Code indicating the result of the 3DS process. | String |
| masked_card | First 8-digits and last 4-digits of customer's card number. | String |
| bank | The name of the Acquiring Bank. | String |
| channel_response_code | Response code from payment channel provider. | String |
| channel_response_message | Response message from payment channel provider. | String |
| card_type | Type of payment card used for the transaction. Possible values are credit, debit. | String |