openapi: 3.0.3
info:
  title: Midtrans Payment Card Tokenization Payment Link API
  description: 'A representative OpenAPI description of the Midtrans payment platform, an Indonesian payment gateway (part of the GoTo Group). It covers Snap (hosted checkout), the Core API (charge and transaction lifecycle), card and GoPay tokenization, Payment Link, recurring Subscriptions, and Iris disbursement / payouts.


    Hosts vary by product. The default servers below are the Core API / Payment Link / Subscription hosts (api.midtrans.com and api.sandbox.midtrans.com). Snap runs on app.midtrans.com and Iris runs on app.midtrans.com/iris; those paths declare their own path-level `servers` override so the full URL is always unambiguous.


    Authentication is HTTP Basic: your Server Key is the username and the password is empty (`Authorization: Basic base64(SERVER_KEY:)`). The two card tokenization endpoints instead use the public Client Key passed as a query parameter, and Iris uses its own creator / approver API key over HTTP Basic.


    This document was authored by API Evangelist from Midtrans'' public documentation and official Postman collection; request / response bodies are modeled representatively rather than exhaustively.'
  version: '1.0'
  contact:
    name: Midtrans
    url: https://midtrans.com
  license:
    name: Proprietary
    url: https://midtrans.com
servers:
- url: https://api.midtrans.com
  description: Core API / Payment Link / Subscription - Production
- url: https://api.sandbox.midtrans.com
  description: Core API / Payment Link / Subscription - Sandbox
security:
- serverKeyAuth: []
tags:
- name: Payment Link
  description: Create, read, and delete shareable payment links.
paths:
  /v1/payment-links:
    post:
      operationId: createPaymentLink
      tags:
      - Payment Link
      summary: Create a payment link
      description: Creates a shareable hosted payment page for an order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentLinkRequest'
      responses:
        '201':
          description: The created payment link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/payment-links/{order_id}:
    parameters:
    - $ref: '#/components/parameters/OrderId'
    get:
      operationId: getPaymentLink
      tags:
      - Payment Link
      summary: Get payment link details
      description: Retrieves the details and payment status of a payment link.
      responses:
        '200':
          description: The payment link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deletePaymentLink
      tags:
      - Payment Link
      summary: Delete a payment link
      description: Deletes a payment link so it can no longer be paid.
      responses:
        '200':
          description: Deletion confirmation.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PaymentLinkRequest:
      type: object
      required:
      - transaction_details
      properties:
        transaction_details:
          $ref: '#/components/schemas/TransactionDetails'
        item_details:
          type: array
          items:
            $ref: '#/components/schemas/ItemDetail'
        customer_details:
          $ref: '#/components/schemas/CustomerDetails'
        usage_limit:
          type: integer
        expiry:
          type: object
          additionalProperties: true
        enabled_payments:
          type: array
          items:
            type: string
    PaymentLink:
      type: object
      properties:
        order_id:
          type: string
        payment_url:
          type: string
          format: uri
    TransactionDetails:
      type: object
      required:
      - order_id
      - gross_amount
      properties:
        order_id:
          type: string
        gross_amount:
          type: integer
          description: Total amount in the smallest currency unit (IDR has no decimals).
    CustomerDetails:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        phone:
          type: string
    ItemDetail:
      type: object
      properties:
        id:
          type: string
        price:
          type: integer
        quantity:
          type: integer
        name:
          type: string
    Error:
      type: object
      properties:
        status_code:
          type: string
        status_message:
          type: string
        id:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    OrderId:
      name: order_id
      in: path
      required: true
      description: The merchant order_id (or Midtrans transaction_id) of the transaction.
      schema:
        type: string
  securitySchemes:
    serverKeyAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic authentication. Your Server Key is the username and the password is empty, so the header is `Authorization: Basic base64(SERVER_KEY:)`. Iris disbursement uses the same HTTP Basic scheme but with its own creator / approver API key.'