Payment Link API Docs

Payment Link - API Reference

📘

Payment Link API is still in BETA phase. But is currently usable on Midtrans Production & Sandbox environment. Feel free to contact our Support Team (or your Midtrans' Sales Account Manager) to share your feedback or question.

You can visit general overview of Payment Link API, in case you haven't.

Integration Overview

Pre-requisite:

Steps:

  1. Merchant's backend sends request to Create Payment Link API, in order to retrieve payment URL.
  2. Share the payment URL to Customer (e.g. via system, messaging app, or Midtrans automated email), and then wait for them to proceed to payment.
  3. Merchant gets notified of payment status changes & handles accordingly.

📘

Note

Merchant can also use other API endpoints to manage Payment Link. For example to read/delete Payment Link as needed.

API Reference

The followings reference will explain the Payment Link API.

API Host URL

EnvironmentAPI Host Base URL
Sandboxhttps://api.sandbox.midtrans.com
Productionhttps://api.midtrans.com

*Learn more about what is Sandbox Environment.

Create Payment Link API

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": "[email protected]",
    "phone": "+62181000000000",
    "notes": "Thank you for your purchase. Please follow the instructions to pay."
  },
"custom_field1": "custom field 1 content", 
"custom_field2": "custom field 2 content", 
"custom_field3": "custom field 3 content"
}

Request JSON Body Details

ParameterRequiredTypeDescription
transaction_detailsrequiredObjectSpecific information regarding the transaction.
customer_requiredoptionalBooleanIf set as True, Payment Link will prompt user to fill in customer details (name, phone and email) before customer can proceed to pay
customer_detailsoptionalObjectSpecific 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_detailsoptionalObjectDetails of the purchased items. Will be shown to customer during payment and shown in Midtrans Dashboard.
usage_limitoptionalintegerMaximum number of allowed successful/paid transactions.
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.
expiryoptionalObjectCustomizable transaction lifetime. Once the duration exceeded, the link will no longer be available.
enabled_paymentsoptionalArrayCustomizable list of payment methods that will be shown during payment. If not specified, by default all active payment methods are shown.
Options:
credit_card, gopay, cimb_clicks, bca_klikbca, bca_klikpay, bri_epay, telkomsel_cash, echannel, permata_va, other_va, bca_va, bni_va, bri_va, indomaret, danamon_online, akulaku, shopeepay.
custom_field1optionalString(255)Retrievable custom text that you can pass to Midtrans on field 1. Wil be shown in Midtrans Dashboard, & sent on HTTP Notification.
custom_field2optionalString(255)Retrievable custom text that you can pass to Midtrans on field 2. Wil be shown in Midtrans Dashboard, & sent on HTTP Notification.
custom_field3optionalString(255)Retrievable custom text that you can pass to Midtrans on field 3. Wil be shown in Midtrans Dashboard, & sent on HTTP Notification.
credit_cardoptionalObjectCredit card payment options.
bni_vaoptionalObjectCustomizable Virtual Account number & options for BNI VA.
permata_vaoptionalObjectCustomizable Virtual Account number & options for Permata VA.
bca_vaoptionalObjectCustomizable Virtual Account number & options for BCA VA.
bri_vaoptionalObjectCustomizable Virtual Account number & options for BRI 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.
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.
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 (not Midtrans).

Parameter Required Type Description
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.
customer_details object

The value of these parameters will be specified by Merchant (not Midtrans).

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.
bca_va object

BCA Virtual Account Object

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

BNI Virtual Account Object

Parameter Required Type Description
va_number optional String(8) Custom Virtual Account Number.
permata_va object

Permata Virtual Account Object

Parameter Required Type Description
va_number optional String(10) Custom Virtual Account Number.
bri_va object

BRI Virtual Account Object

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

Request Sample

Sample Request including Headers & Body.

CURL

curl --location --request POST 'https://api.sandbox.midtrans.com/v1/payment-links' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic U0ItTWlkLXNlcnZlci1UT3ExYTJBVnVpeWhoT2p2ZnMzVV7LZU87' \
--data-raw '{
 "transaction_details": {
   "order_id": "concert-ticket-05",
   "gross_amount": 190000,
   "payment_link_id": "amazing-ticket-payment-123"
 },
 "credit_card": {
   "secure": true
 },
 "usage_limit":  5,
 "expiry": {
   "duration": 30,
   "unit": "days"
 },
 "item_details": [
   {
     "id": "tix-001",
     "name": "Exclusive Tour Concert Day 1",
     "price": 95000,
     "quantity": 2
   }
 ],
 "customer_details": {
   "first_name": "John",
   "last_name": "Doe",
   "email": "[email protected]",
   "phone": "+62181000000000",
   "notes": "Thank you for your order. Please follow the instructions to complete payment."
 }
}
'

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

HTTP Status Code: 200

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

Sample Failure Response

HTTP Status Code: 409

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

HTTP Status Code: 401

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

HTTP Status Code: 400

{
   "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

Property Descriptions
order_id Merchant’s Order ID
payment_url The resulting payment url to share with Customer.
error_messages The message describing the error, if any error encountered.

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