API References
Create AccountSubmit FeedbackAI Assist (BETA)
Start typing to search…

Feature: Pre-Authorization

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"
  }
}
{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "credit_card": {
    "card": {
      "number": "4811111111111114",
      "expiry_month": "03",
      "expiry_year": "2020",
      "cvv": "123"
    },
    "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

type

Flag to indicate if the transaction is pre-authorized or automatically captured. Valid value: authorize.

String

token_id

Token ID represents customer's card information acquired from Get Card Token response.

String

credit_card

The details of the payment card used for the transaction.

Object](ref:credit-card-object)

credit_card.card

The details of the payment card used for the transaction.

Object

credit_card.card.number

Primary Account Number (PAN) of credit card.

Integer (13-19)

credit_card.card.expiry_month

The card expiry month in MM format.

String (2)

credit_card.card.expiry_year

The card expiry year in YYYY format.

String (4)

credit_card.card.cvv

Also known as Card Verification Code (CVC) shown at the back of the credit card.
Note: If card.cvv is not passed, then transaction will be treated as recurring.

Integer (3-4)



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: challenge to accept it or, the transaction will get cancelled automatically during settlement.



Capture Transaction Method


EndpointHTTP MethodDefinition
BASE_URL/capturePOSTCapture 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 AttributeDescriptionType
transaction_idTransaction ID from Charge Pre-Authorization Response.String
gross_amountTotal 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:deny on capture response and keep transaction_status:authorize as 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 are
capture: 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 are
accept: 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