openapi: 3.0.3
info:
  title: Midtrans Payment Card Tokenization GoPay 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: GoPay Tokenization
  description: Bind and read a customer's GoPay account.
paths:
  /v2/pay/account:
    post:
      operationId: createPayAccount
      tags:
      - GoPay Tokenization
      summary: Create (link) a GoPay pay account
      description: Links a customer's GoPay account by phone number and returns activation actions plus an `account_id`. The account status progresses through PENDING, ENABLED, EXPIRED, and DISABLED.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayAccountRequest'
      responses:
        '201':
          description: The linked pay account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/pay/account/{account_id}:
    parameters:
    - name: account_id
      in: path
      required: true
      description: The linked pay account identifier.
      schema:
        type: string
    get:
      operationId: getPayAccount
      tags:
      - GoPay Tokenization
      summary: Get a GoPay pay account
      description: Retrieves a linked GoPay account's status and available payment tokens.
      responses:
        '200':
          description: The pay account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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'
  schemas:
    Action:
      type: object
      properties:
        name:
          type: string
        method:
          type: string
        url:
          type: string
          format: uri
    PayAccount:
      type: object
      properties:
        status_code:
          type: string
        payment_type:
          type: string
        account_id:
          type: string
        account_status:
          type: string
          enum:
          - PENDING
          - ENABLED
          - EXPIRED
          - DISABLED
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
        metadata:
          type: object
          additionalProperties: true
    PayAccountRequest:
      type: object
      required:
      - payment_type
      properties:
        payment_type:
          type: string
          enum:
          - gopay
        gopay_partner:
          type: object
          properties:
            phone_number:
              type: string
            country_code:
              type: string
            redirect_url:
              type: string
              format: uri
    Error:
      type: object
      properties:
        status_code:
          type: string
        status_message:
          type: string
        id:
          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.'