openapi: 3.0.3
info:
  title: Midtrans Payment Card Tokenization 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: Card Tokenization
  description: Client-key card token and card registration (browser-side).
paths:
  /v2/token:
    get:
      operationId: getCardToken
      tags:
      - Card Tokenization
      summary: Get a one-time card token
      description: Exchanges raw card data (or a saved `token_id`) for a one-time `token_id` used by the Core API charge. Authenticated with the public Client Key passed as the `client_key` query parameter - this endpoint is called from the browser so raw PAN never touches the merchant server.
      security: []
      parameters:
      - name: client_key
        in: query
        required: true
        description: The merchant's public Client Key.
        schema:
          type: string
      - name: card_number
        in: query
        required: false
        schema:
          type: string
      - name: card_exp_month
        in: query
        required: false
        schema:
          type: string
      - name: card_exp_year
        in: query
        required: false
        schema:
          type: string
      - name: card_cvv
        in: query
        required: false
        schema:
          type: string
      - name: token_id
        in: query
        required: false
        description: A previously saved token to re-tokenize with a CVV.
        schema:
          type: string
      responses:
        '200':
          description: A one-time card token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardToken'
  /v2/card/register:
    get:
      operationId: registerCard
      tags:
      - Card Tokenization
      summary: Register (save) a card
      description: Registers a card for one-click / two-click and recurring use, returning a `saved_token_id`. Authenticated with the public Client Key query parameter.
      security: []
      parameters:
      - name: client_key
        in: query
        required: true
        schema:
          type: string
      - name: card_number
        in: query
        required: true
        schema:
          type: string
      - name: card_exp_month
        in: query
        required: true
        schema:
          type: string
      - name: card_exp_year
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A saved card token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardToken'
components:
  schemas:
    CardToken:
      type: object
      properties:
        status_code:
          type: string
        token_id:
          type: string
        saved_token_id:
          type: string
        hash:
          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.'