--- title: Midtrans API Integration on Truto slug: midtrans category: Payment Gateway canonical: "https://truto.one/integrations/detail/midtrans/" --- # Midtrans API Integration on Truto **Category:** Payment Gateway **Status:** Generally available ## MCP-ready AI tools Truto exposes 44 tools for Midtrans that AI agents can call directly. - **midtrans_transactions_cancel** — Cancel a Midtrans transaction to void it. Use refund instead if the transaction is already settled. Returns: status_code, status_message, transaction_id, masked_card, order_id, payment_type, transaction_time, transaction_status, fraud_status, bank, gross_amount. Required: order_id_or_transaction_id. - **midtrans_transactions_refund** — Refund a settled Midtrans transaction to reverse money back to the customer. Supported for credit_card, gopay, shopeepay, dana, ovo, QRIS, kredivo, and akulaku. Returns: status_code, status_message, transaction_id, order_id, payment_type, transaction_time, transaction_status, gross_amount, refund_chargeback_id, refund_amount, refund_key, amount, reason. Required: order_id_or_transaction_id. - **midtrans_transactions_direct_refund** — Send a direct refund request to the bank or payment provider for a settled Midtrans transaction for faster processing than standard refund. Supported for GoPay, QRIS, ShopeePay, Credit Card, Akulaku, and Kredivo. Returns: status_code, status_message, transaction_id, order_id, gross_amount, payment_type, transaction_time, transaction_status, refund_chargeback_id, refund_amount, refund_key.… - **midtrans_transactions_expire** — Expire a Midtrans transaction by order ID or transaction ID, updating transaction_status to expire when the customer fails to complete payment. The expired order_id can be reused for the same or different payment methods. Returns: status_code, status_message, transaction_id, order_id, payment_type, transaction_time, transaction_status, signature_key, bank, gross_amount, permata_va_number.… - **midtrans_transactions_approve** — Approve a challenged Midtrans transaction by order ID or transaction ID, accepting a transaction flagged by the Fraud Detection System so it proceeds to settlement instead of being automatically canceled. Returns: status_code, status_message, transaction_id, masked_card, order_id, payment_type, transaction_time, transaction_status, fraud_status, bank, gross_amount, approval_code, signature_key,… - **midtrans_transactions_get_status_b_2_b** — Get the B2B transaction status for a specific order or transaction in Midtrans. Returns: status_code, status_message, transaction_id, masked_card, order_id, payment_type, transaction_time, transaction_status, fraud_status, approval_code, signature_key, bank, gross_amount, channel_response_code, channel_response_message, card_type, payment_option_type, shopeepay_reference_number, reference_id,… - **midtrans_transactions_capture** — Capture an authorized Midtrans card transaction to settle the transaction balance. Only applicable when transaction_status is 'authorize' (pre-authorized credit card or GoPay). Returns: status_code, status_message, transaction_id, masked_card, order_id, payment_type, transaction_time, transaction_status, fraud_status, bank, gross_amount. Required: transaction_id. - **midtrans_transactions_deny** — Deny a challenged card payment transaction in Midtrans. The transaction must have fraud_status challenge. Returns: transaction_id, order_id, gross_amount, payment_type, transaction_time, transaction_status, fraud_status, masked_card, status_code, bank, status_message. Required: order_id_or_transaction_id. - **create_a_midtrans_transaction** — Create a new Midtrans transaction charge with a specified payment type and transaction details. Returns: status_code, status_message, transaction_id, order_id, gross_amount, payment_type, transaction_time, transaction_status, fraud_status, masked_card, approval_code, bank, custom_field1, custom_field2, custom_field3, metadata, bank_transfer, transaction_details. Required: payment_type,… - **list_all_midtrans_transactions** — Get the status and details of a Midtrans transaction by order ID or transaction ID. For BI SNAP and DANA payment methods, only transaction ID works. Returns: status_code, status_message, transaction_id, order_id, gross_amount, payment_type, transaction_time, transaction_status, fraud_status, masked_card, approval_code, bank, signature_key, channel_response_code, channel_response_message,… - **midtrans_card_get_token** — Get a card token in Midtrans by securely sending credit card details to obtain a Token ID for card payment transactions. Returns: status_code, status_message, validation_messages, token_id, hash, id, name, amount, currency, created_at, schedule, status, token, payment_type, metadata, customer_details, gopay. Required: card_number, card_cvv, card_exp_month, card_exp_year. Applicable only for card… - **midtrans_card_register** — Register a card in Midtrans for future one-click and two-click transactions by submitting card number and expiry. Returns: status_code, saved_token_id, transaction_id, masked_card. Required: card_number, card_exp_month, card_exp_year. - **create_a_midtrans_payment_link** — Create a Midtrans payment link with desired transaction details. Returns: order_id, payment_url. Required: transaction_details containing order_id (and gross_amount for FIXED_AMOUNT links, omitted when payment_link_type is DYNAMIC_AMOUNT). - **midtrans_snap_create_token** — Create a Snap payment token in Midtrans by submitting transaction details and optional payment configuration. Returns: token, redirect_url. Required: transaction_details (including order_id and gross_amount). - **create_a_midtrans_subscription** — Create a Midtrans subscription or recurring transaction. Returns: id, name, amount, currency, created_at, schedule, status, token, payment_type, metadata, customer_details, gopay. Required: name, amount, currency, payment_type, token, schedule. Only IDR currency and credit_card or gopay payment types are supported. - **get_single_midtrans_subscription_by_id** — Get a single Midtrans subscription by id. Returns: id, name, amount, currency, created_at, schedule, status, token, payment_type, metadata, customer_details, gopay. Required: id. - **midtrans_subscriptions_disable** — Disable a Midtrans subscription so the customer is not charged in the future. Returns: status_message. Required: subscription_id. Pending retries from previous failed payments will still execute after disabling. - **midtrans_subscriptions_enable** — Enable a Midtrans subscription so the customer can start paying for the subscription immediately. Returns: status_message. Required: subscription_id. - **update_a_midtrans_subscription_by_id** — Update a Midtrans subscription's details or reactivate an expired subscription by updating its schedule. Returns: status_message. Required: id, name, amount, currency, token. Only schedule.interval can be updated; interval_unit and max_interval cannot be changed, and the payment method cannot be changed mid-subscription. - **midtrans_subscriptions_cancel** — Cancel a Midtrans subscription by subscription_id, stopping future charges and any pending retries from previous failed charge attempts. Returns: status_message. Required: subscription_id. - **midtrans_access_token_get_access_token** — Get a B2B access token from Midtrans using the OAuth 2.0 client_credentials grant. Returns: responseCode, responseMessage, accessToken, tokenType, expiresIn, id, name, amount, currency, created_at, schedule, status, token, payment_type, metadata, customer_details, gopay. Required: grantType. - **midtrans_account_linking_get_auth_code** — Get an auth code to initiate GoPay account linking in Midtrans, redirecting the user to the GoPay PIN/OTP page. Returns: responseCode, responseMessage, referenceNo. Required: redirectURL, scopes, state, merchantId, lang, seamlessData, seamlessSign. - **midtrans_account_linking_bind_account** — Bind a GoPay account in Midtrans using an authCode to obtain a customer access token. Returns: responseCode, responseMessage, referenceNo, accessTokenInfo. Required: merchantId, authCode, grantType. - **midtrans_account_linking_inquiry_binding** — Inquire about a GoPay account binding in Midtrans to fetch account status, balance, payment options, and the current payment option token. Returns: responseCode, responseMessage, referenceNo, additionalInfo. - **midtrans_account_linking_unbind_account** — Unbind a linked GoPay account from a merchant in Midtrans. Returns: responseCode, responseMessage, referenceNo, id, name, amount, currency, created_at, schedule, status, token, payment_type, metadata, customer_details, gopay. Required: merchantId. - **midtrans_direct_debit_direct_debit_payment** — Initiate a GoPay Tokenization direct debit payment in Midtrans. Returns: responseCode, responseMessage, referenceNo, partnerReferenceNo, paidTime, webRedirectUrl, appRedirectUrl, additionalInfo, originalReferenceNo, originalPartnerReferenceNo, captureNo, partnerCaptureNo, captureAmount, captureTime. Required: partnerReferenceNo, chargeToken, urlParams, payOptionDetails. The GoPay account must be… - **midtrans_direct_debit_auth_payment** — Reserve a customer's GoPay balance without deducting it by initiating a GoPay Tokenization Pre-Auth transaction in Midtrans. Returns: responseCode, responseMessage, referenceNo, partnerReferenceNo, paidTime, additionalInfo, originalReferenceNo, originalPartnerReferenceNo, captureNo, partnerCaptureNo, captureAmount, captureTime. Required: partnerReferenceNo, merchantId, title, and additionalInfo. - **midtrans_direct_debit_capture_payment** — Capture an authorized GoPay Tokenization transaction in Midtrans to deduct the user's previously reserved balance. Returns: responseCode, responseMessage, originalReferenceNo, originalPartnerReferenceNo, captureNo, partnerCaptureNo, captureAmount, captureTime. Required: originalPartnerReferenceNo, partnerCaptureNo, merchantId, title. Either originalReferenceNo or additionalInfo.originalExternalId… - **midtrans_direct_debit_refund** — Refund a settled Midtrans GoPay or GoPay Tokenization (non pre-auth) transaction over the BI-SNAP Direct Debit API, returning money to the customer. Supports partial refunds via refundAmount; omit it for a full refund. Returns: responseCode, responseMessage, originalReferenceNo, refundNo, partnerRefundNo, refundAmount, refundTime. Required: originalPartnerReferenceNo, partnerRefundNo, and either originalReferenceNo or originalExternalId. - **midtrans_direct_debit_get_status** — Get the transaction status of a GoPay Tokenization direct debit transaction in Midtrans. Returns: responseCode, responseMessage, partnerReferenceNo, referenceNo, additionalInfo containing payment status, transaction time, expiry time, and fraud status details. - **midtrans_virtual_account_create_va** — Create a Virtual Account in Midtrans using the SNAP-based BI-SNAP Core API. Returns the generated virtual account number, virtual account name, total amount, and expiry time. Required: partnerServiceId, customerNo, virtualAccountName, totalAmount, and partnerReferenceNo. - **midtrans_virtual_account_get_va_status** — Get the status of a Virtual Account transaction in Midtrans via the BI-SNAP Core API. Returns: masked_card, approval_code, bank, eci, channel_response_code, channel_response_message, transaction_time, gross_amount, currency, order_id, payment_type, signature_key, status_code, transaction_id, transaction_status, fraud_status, settlement_time, status_message, merchant_id, card_type,… - **midtrans_qris_create_qr** — Generate a QRIS MPM (Merchant Presented Mode) QR code in Midtrans. Returns the created QRIS transaction including transaction_id, order_id, transaction_status, gross_amount, currency, acquirer, and actions with QR code generation URLs. Required: payment_type, transaction_details. - **midtrans_qris_get_qr_status** — Get the status of a QRIS MPM (Merchant Presented Mode) transaction in Midtrans via the BI-SNAP protocol. Returns: transaction_status, transaction_id, order_id, gross_amount, status_code, status_message, payment_type, currency. - **midtrans_qris_refund_qr** — Refund a settled Midtrans QRIS MPM transaction over the BI-SNAP API, returning money to the customer. Supports partial refunds via refundAmount; omit it for a full refund. Returns: responseCode, responseMessage, referenceNo, originalPartnerReferenceNo, originalReferenceNo, partnerRefundNo, refundAmount, refundTime, additionalInfo. Required: merchantId, originalPartnerReferenceNo, partnerRefundNo. - **midtrans_qris_cancel_qr** — Cancel a pending QRIS MPM (Merchant Presented Mode) transaction in Midtrans via the BI-SNAP API. Returns: status_code, status_message, transaction_id, order_id, merchant_id, gross_amount, currency, payment_type, transaction_time, transaction_status, fraud_status, acquirer, actions, signature_key, transaction_type, settlement_time, issuer, shopeepay_reference_number, reference_id. - **midtrans_qris_generate_qr_code** — Generate a QR code image for a Midtrans QRIS transaction by transaction_id. Returns a PNG image of the QR code that customers can scan to pay from any QRIS-registered payment provider. Required: transaction_id. The QR code URL expires after 30 days. - **midtrans_transaction_history_get_transaction_history** — List Midtrans merchant transaction history with optional date-range, type, and status filters. Returns each transaction's dateTime, amount, status, type, remark, and additionalInfo (including referenceNo, partnerReferenceNo, channel, customerEmail, accountNo, and fee). Date range limited to the latest 6 months; max 50 per page. - **midtrans_gopay_account_get_pay_account** — Get a GoPay account's linked status and payment options in Midtrans. Returns: status_code, payment_type, account_id, account_status, metadata. Required: account_id. Only applicable for GoPay Tokenizations. - **midtrans_gopay_account_unbind_pay_account** — Unbind a linked GoPay customer account in Midtrans. Returns: status_code, payment_type, account_id, account_status, channel_response_code, channel_response_message. Required: account_id. - **midtrans_gopay_account_get_gopay_account_info** — Get GoPay account info for Snap tokenization in Midtrans. Returns: status_code, payment_type, account_id, account_status, metadata. Required: user_id. - **midtrans_gopay_account_unlink_gopay_account** — Unlink a GoPay account from Snap tokenization in Midtrans. Returns: status_code, payment_type, account_id, account_status, channel_response_code, channel_response_message. Required: user_id. - **midtrans_gopay_account_create_pay_account** — Link a customer's GoPay account for GoPay Tokenization in Midtrans. Returns: status_code, payment_type, account_id, account_status, actions, channel_response_code, channel_response_message, gopay_partner. Required: payment_type, gopay_partner.phone_number, gopay_partner.country_code. - **midtrans_bin_get_bin** — Get metadata for a specific BIN (Bank Identification Number) in Midtrans, such as card type, brand, issuing bank, and country. Returns: country_name, country_code, brand, bin_type, bin_class, bin, bank_code, bank. Required: bin_number. Rate-limited to 100 requests per minute; excess requests receive a 409 status code. ## How it works 1. **Link your customer's Midtrans account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Midtrans.** The Proxy API is a 1-to-1 mapping of the Midtrans API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Enable localized checkout for SEA e-commerce merchants** — Let your merchants accept payments from Indonesian buyers via QRIS, Virtual Accounts, GoPay, and other regional methods without you building integrations to each local rail. Truto handles the Midtrans connection so your platform can offer a full SEA-ready payment stack out of the box. - **Automate invoice collection in CRM and billing tools** — Generate Midtrans payment links tied to invoices and reconcile them against transaction status automatically. Perfect for B2B SaaS platforms whose users need to collect IDR payments without leaving their workflow or logging into the Midtrans dashboard. - **Power recurring billing for subscription businesses** — Offer merchants running gyms, SaaS products, or membership services the ability to charge cards or GoPay wallets on a schedule. Create, update, pause, and cancel Midtrans subscriptions natively from within your product. - **Build a native refund and fraud review console** — Give merchants the ability to refund, cancel, approve, or deny transactions directly in your dashboard. Removes the operational friction of jumping between your product and the Midtrans MAP for day-to-day payment operations. - **Enable one-click checkout via wallet linking** — Let end-buyers bind their GoPay accounts to your platform once and trigger silent direct debits for future purchases. Ideal for on-demand marketplaces, ride-hailing clones, or any product optimizing for repeat purchase conversion. ## What you can build - **Embedded SNAP checkout widget** — Use the SNAP token endpoint to render Midtrans's hosted checkout inside your app, exposing all 24+ local payment methods with zero UI work. - **Dynamic QRIS payment screens** — Generate QRIS codes on the fly for in-app scan-to-pay experiences and poll their status to confirm settlement in real time. - **Virtual Account bank transfer flows** — Provision unique VA numbers per order across supported Indonesian banks and track their payment status to reconcile bank transfers automatically. - **Recurring subscription manager** — Create, enable, disable, update, and cancel Midtrans subscription schedules from your billing UI so merchants can manage plans without leaving your product. - **Merchant refund and cancellation console** — Expose refund, direct refund, cancel, and expire actions in your merchant dashboard so support teams can resolve payment issues in a single click. - **GoPay account linking for one-click pay** — Implement the account linking and direct debit auth flow so buyers can bind GoPay once and complete future purchases via silent capture calls. ## FAQs ### How does authentication work when my users connect Midtrans? Midtrans uses Server Key and Client Key credentials issued from the merchant's Midtrans Account Portal (MAP). Truto handles collecting, storing, and injecting these keys on API calls, so your users just paste their keys once and your backend calls Truto without touching credentials directly. ### Which Midtrans APIs are supported through Truto? Truto exposes the Core API (transactions, card tokenization, VA, QRIS, direct debit, GoPay account linking, BIN lookup), the SNAP API (checkout token), Payment Links, Subscriptions, and transaction lifecycle actions like capture, approve, deny, cancel, expire, and refund. ### Can I fetch historical transactions and reconcile payment status? Yes. You can list all Midtrans transactions, fetch transaction history, and get status for specific payment types (B2B, VA, QRIS, direct debit) to build reconciliation and reporting features. ### Does Truto handle webhooks from Midtrans? Midtrans sends HTTP notifications on transaction state changes (settlement, expire, deny, refund, etc.). You should configure the notification URL in the MAP to point to your webhook receiver; Truto's tools cover the API surface for querying and mutating state, and can be paired with your webhook handler for full lifecycle coverage. ### Can I support both Sandbox and Production environments per merchant? Yes. Midtrans offers separate Sandbox and Production endpoints and key pairs. Truto lets you configure the environment per connected account so your merchants can test in Sandbox before flipping to live keys. ### Are recurring billing and one-click payments supported? Yes. You can use the subscription endpoints for scheduled recurring charges on cards or GoPay, and combine account linking with direct debit auth and capture endpoints to build one-click checkout experiences for repeat buyers. ## Related reading - [Connect Midtrans to ChatGPT: Manage Payments, Refunds & Subscriptions](https://truto.one/blog/connect-midtrans-to-chatgpt-manage-payments-refunds-subscriptions/) — Learn how to connect Midtrans to ChatGPT using an auto-generated MCP server. Generate secure endpoints to automate payments, QRIS generation, and refunds. - [Connect Midtrans to Claude: Orchestrate QRIS, VA & Transaction Status](https://truto.one/blog/connect-midtrans-to-claude-orchestrate-qris-va-transaction-status/) — Learn how to connect Midtrans to Claude using a managed MCP server. This guide covers orchestrating QRIS, Virtual Accounts, refunds, and transaction statuses. - [Connect Midtrans to AI Agents: Automate GoPay & Billing Flows](https://truto.one/blog/connect-midtrans-to-ai-agents-automate-gopay-linking-billing-flows/) — Learn how to safely connect Midtrans to AI Agents using Truto's /tools endpoint. Automate GoPay linking, QRIS generation, and fraud challenge resolutions.