Merchant sends HTTP API request with the desired transaction details to this endpoint, and will get API response mainly with the Payment Link URL. The URL then should be shared to & opened by Customer, to initiates payment.

Request

Endpoints: /v1/payment-links
HTTP Method: POST
Headers:

Accept: application/json
Content-Type: application/json
Authorization: Basic AUTH_STRING

AUTH_STRING value is result of Base64Encode("YourServerKey"+":")

Midtrans API validates HTTP request by using Basic Authentication method. The username is your Server Key while the password is empty. The authorization header value is represented by AUTH_STRING. AUTH_STRING is base-64 encoded string of your username and password separated by colon symbol (:). For more details, refer to API Authorization and Headers.

Request Body

{
  "transaction_details": {
    "order_id": "001",
    "gross_amount": 190000,
    "payment_link_id": "for-payment-123"
  },
  "customer_required": true,
  "credit_card": {
    "secure": true,
    "bank": "bca",
    "installment": {
      "required": false,
      "terms": {
        "bni": [
          3,
          6,
          12
        ],
        "mandiri": [
          3,
          6,
          12
        ],
        "cimb": [
          3
        ],
        "bca": [
          3,
          6,
          12
        ],
        "offline": [
          6,
          12
        ]
      }
    }
  },
  "usage_limit": 1,
  "expiry": {
    "start_time": "2022-04-01 18:00 +0700",
    "duration": 20,
    "unit": "days"
  },
  "enabled_payments": [
    "credit_card",
    "bca_va",
    "indomaret"
  ],
  "item_details": [
    {
      "id": "pil-001",
      "name": "Pillow",
      "price": 95000,
      "quantity": 2,
      "brand": "Midtrans",
      "category": "Furniture",
      "merchant_name": "PT. Midtrans"
    }
  ],
  "customer_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@midtrans.com",
    "phone": "+62181000000000",
    "notes": "Thank you for your purchase. Please follow the instructions to pay.",
    "customer_details_required_fields": [
      "first_name",
      "phone",
      "email"
    ]
  },
  "title": "test title",
  "payment_link_type": "DYNAMIC_AMOUNT",
  "dynamic_amount": {
    "min_amount": 5000,
    "max_amount": 5000,
    "preset_amount": 5000
  },
  "custom_field1": "custom field 1 content",
  "custom_field2": "custom field 2 content",
  "custom_field3": "custom field 3 content",
  "callbacks": {
    "finish": "https://www.google.com?merchant_order_id=test-122"
  }
}

Request JSON Body Details

Parameter	Required	Type	Description
transaction_details	required	Object	Specific information regarding the transaction.
customer_required	optional	Boolean	If set as True, Payment Link will prompt user to fill in customer details (name, phone and email) before customer can proceed to pay - which field set as mandatory can be specified in `customer_details`. If set as false, Payment Link will still show the customer details input form but it's not mandatory (customer can continue to the next page without filling any)
customer_details	optional	Object	Specific information regarding the customer. Note: If Merchant sends customer_detail’s email on the request, Midtrans will send the created Payment Link url to the customer’s email.
item_details	optional	Object	Details of the purchased items. Will be shown to customer during payment and shown in Midtrans Dashboard.
usage_limit	optional	integer	Maximum number of allowed successful/paid transactions. Max accepted value is `1000000` (1 million usage). Note: Each successful/paid payment will consume a "usage" quota. A `pending` payment (payment attempted, but still waiting for Customer to make payment e.g. waiting Bank Transfer, Gopay, QRIS, etc.) will temporarily hold a usage quota, but if it is abandoned/left-unpaid (becomes `expire`) it will release the usage quota back.
expiry	optional	Object	Customizable transaction lifetime. Once the duration exceeded, the link will no longer be available.
enabled_payments	optional	Array	Customizable list of payment methods that will be shown during payment. If not specified, by default all active payment methods are shown. Options: credit_card, echannel, permata_va, bca_va, bni_va, bri_va, cimb_va, danamon_va, bsi_va, gopay, shopeepay, other_qris, alfamart, indomaret, akulaku, kredivo.
title	optional	String(255)	Title to show in your payment link page that will be seen by your customer. Max char supported is 40.
payment_link_type	optional	String(255)	Pass the value `DYNAMIC_AMOUNT` if you want to use dynamic amount feature. Note that item_details and gross_amount will be ignored if the type passed is `DYNAMIC_AMOUNT`. If payment_link_type is not passed, by default Payment Link will create a `FIXED_AMOUNT` payment link.
dynamic_amount	optional	Object	Optional object if you're creating a payment link with dynamic amount features. You can set max/min amount and preset amount within this object.
custom_field1	optional	String(255)	Retrievable custom text that you can pass to Midtrans on field 1. Wil be shown in Midtrans Dashboard, & sent on HTTP Notification.
custom_field2	optional	String(255)	Retrievable custom text that you can pass to Midtrans on field 2. Wil be shown in Midtrans Dashboard, & sent on HTTP Notification.
custom_field3	optional	String(255)	Retrievable custom text that you can pass to Midtrans on field 3. Wil be shown in Midtrans Dashboard, & sent on HTTP Notification.
callbacks	optional	Object	Callback finish URL where user will be redirected after finishing a transaction. Can append query param if needed.
credit_card	optional	Object	Credit card payment options.
bni_va	optional	Object	Customizable Virtual Account number & options for BNI VA.
permata_va	optional	Object	Customizable Virtual Account number & options for Permata VA.
bca_va	optional	Object	Customizable Virtual Account number & options for BCA VA.
bri_va	optional	Object	Customizable Virtual Account number & options for BRI VA.
cimb_va	optional	Object	Customizable Virtual Account number & options for CIMB VA.

transaction_details object

Parameter	Required	Type	Description
order_id	required	String(50)	Unique transaction ID. A single ID could be used only once by a Merchant. Allowed Symbols are dash(-), underscore(_), tilde (~), and dot (.).
gross_amount	required	Integer	Total payment amount Customer expected to pay. Required for FIXED_AMOUNT, do not use for DYNAMIC_AMOUNT Note: The Sum of Subtotal (item price multiplied by quantity) of all the item details needs to be exactly the same as the gross_amount inside transaction_details object.
payment_link_id	optional	String(50)	Unique Link ID that will be used as part of the resulting payment URL. A single ID could be used only once. Allowed characters are alphanumeric [a-z, 0-9] and hyphens [-]. Note: By default auto generated by midtrans. Tips for generating the payment_link_id

credit_card object

Parameter	Required	Type	Description
secure	optional	Boolean	Specify whether 3D-Secure authentication should be used for Card payment method. Note: It is recommended to specify true for most cases. Default: false.
bank	optional	String	Specify which acquiring bank is preferred for Card payment method. If not specified, Midtrans will auto determine accordingly. It is recommended to not specify it. Options: bca, bni, mandiri, cimb, bri, danamon, maybank, mega.
channel	optional	String	Specify which acquiring channel is preferred for Card payment method's acquiring bank. If not specified, Midtrans will auto determine accordingly. It is recommended to not specify it. Options: migs
type	optional	String	Card payment transaction type. It is recommended to not specify it. Options: authorize, authorize_capture Default: authorize_capture
whitelist_bins	optional	Array	Specify list of card BIN numbers that will be allowed to pay. The BIN value can be either a prefix(up to 8 digits) of card number or the name of a bank, in which case all the cards issued by that bank will be allowed.
installment.required	optional	Boolean	Specify whether Customer is required to pay with installment for card payment method, if installment feature is enabled. It is recommended to not specify it. Default: false
installment.terms	optional	Object	Specify list of allowed installment terms, if installment feature is enabled. It is recommended to not specify it.

expiry object

Parameter	Required	Type	Description
start_time	optional	String Timestamp in yyyy-MM-dd HH:mm:ss Z format	Timestamp of when the expiry period should start. If not specified, transaction time will be used as start time when payment link is created
duration	required	Integer	Expiry duration value.
unit	required	String	Expiry duration unit. Options: day, hour, minute.

item_details object

The value of these parameters will be specified by Merchant.

Parameter	Required	Type	Description
item_id	optional	String	Item ID.
price	required	Integer	Price of the item. NOTE: Don’t add decimal.
quantity	required	Integer	Quantity of the item. NOTE: Must be greater than or equal 1.
name	required	String(50)	Name of the item.
brand	optional	String(50)	Brand of the item.
category	optional	String(50)	Category of the item.
merchant_name	optional	String(50)	Merchant selling the item. Useful if you have multiple sub-merchants within your commerce platform.

📘
Implementing Discounts
You can actually input negative amount as part of the item details in the case there's a need to show Discounts as part of the checkout item details. Make sure however the final gross amount sent is the correct sum of all item details, otherwise charge will fail.

customer_details object

The value of these parameters will be specified by Merchant. If Merchant provide customer_details object in the request, merchant should provide minimum one of three required field as shown below.

Parameter	Required	Type	Description
first_name	required*	String(50)	Customer's first name.
last_name	optional	String(50)	Customer's last name.
email	required*	String(50)	Customer's email address.
phone	required*	String(20)	Customer's phone number.
notes	optional	String(255)	Customizable email instructions.
customer_details_required_fields	optional	Array of String(255)	When `customer_required` is `true`, merchant could specify which fields are required between `"first_name"`, `"phone"` and `"email"` to be filled by customer

Virtual Account Object

Parameter	Required	Type	Description
va_number	optional	String(11)	Custom Virtual Account Number.

dynamic_amount object

Parameter	Required	Type	Description
min_amount	optional	Integer	Min amount that customer can input in payment link page.
max_amount	optional	Integer	Max amount that customer can input in payment link page.
preset_amount	optional	Integer	Prefilled amount - customer will see this amount upon opening payment link page, but they can still edit it.

Request Sample

See sample request on the right -- try it yourself!

Response

For successful response you will receive HTTP status code 2xx as a response. For failure response you may receive HTTP status code 4xx or 5xx.

Sample Success Response

{
   "order_id": "concert-ticket-05",
   "payment_url": "https://app.sandbox.midtrans.com/payment-links/amazing-ticket-payment-123"
}

Sample Failure Response

{
   "error_messages": [
       "The Order ID 'order-123' has been taken"
   ]
}

{
   "error_messages": "Access denied due to unauthorized request"
}

{
   "error_messages": [
       "Invalid JSON data provided.",
       "This Payment Link ID 'payment-112' has been taken",
       "payment_link_id must only contain alphanumeric characters [a-z, 0-9] and hyphens [-]"
   ]
}

Response JSON Body Details

Response properties are conditional, depending on whether the API response is success or failure. E.g. error_messages may only exists on failure response.

HTTP Status Code

Status Code	Descriptions
200	Request is successful
409	Duplicate order ID. Order ID has already been utilized previously
401	Access denied due to unauthorized request
400	Validation Error / Invalid JSON
500	Internal Server Error

Security Tips for Customizable URL

🚧
It's mandatory to ensure the link is not guessable in order to protect you and your customer.
For example, having an enumerated number in the custom url can impose a risk that anyone can guess the next number: /merchant-payment-order-001
Each payment link is recommended to have the following properties:

Non-guessability: Links should be unpredictable to prevent unauthorized access or brute-force attacks.

Usability: Links should be reasonably short and manageable for sharing (e.g., via email, SMS, or QR code).

Uniqueness: Each payment link must be unique to prevent collisions.

Scalability: The algorithm should handle high volumes of link generation without performance issues.

In order to do achieve these goals, here are some sample algorithm you can try.

UUID / UUIDv4: This has a negligible chance of collision (2^128 possibilities)

Cryptographically Secure Random Token: Enhance non-guessability by generating a random token using a cryptographically secure random number generator.

Hash order information: Use a cryptographic hash function like SHA-256 to create a fixed-length, non-reversible token. For usability, truncate the hash to a reasonable length (e.g., 16–20 bytes) to keep the link manageable