openapi: 3.0.3
info:
  title: 2C2P Payment Gateway API (PGW v4.3)
  description: >-
    Server-to-server REST interface for the 2C2P Payment Gateway. Every
    operation is an HTTPS POST under /payment/4.3/. IMPORTANT: on the wire, each
    request and response body is a single JSON Web Token (JWS) signed with the
    merchant's Secret Key using HMAC SHA-256 - the merchant is identified by the
    merchantID inside the signed payload, and there is no HTTP Authorization
    header. For readability this document models the DECODED JSON payloads
    (request `payload` and response `payload`) rather than the raw JWT string.
    The field schemas here are MODELED from the documented parameters and are a
    representative subset, not a byte-for-byte copy of 2C2P's contract; verify
    exact fields against developer.2c2p.com. Endpoint paths are confirmed from
    the 2C2P developer reference index.
  version: '4.3'
  contact:
    name: 2C2P Developer
    url: https://developer.2c2p.com
  x-transport-notes: >-
    All traffic is HTTPS request/response. Asynchronous results are delivered as
    a backend notification webhook (2C2P POSTs a signed JWT to the merchant's
    backendReturnUrl). There is no WebSocket or SSE transport.
servers:
  - url: https://pgw.2c2p.com/payment/4.3
    description: Production
  - url: https://sandbox-pgw.2c2p.com/payment/4.3
    description: Sandbox
tags:
  - name: Payment Token
    description: Initialize a payment and obtain a paymentToken.
  - name: Do Payment
    description: Execute a payment against a paymentToken.
  - name: Payment Option
    description: Retrieve available payment options and channel details.
  - name: Inquiry
    description: Query transaction result and status.
  - name: Maintenance
    description: Void / cancel, refund, and settle operations.
  - name: Tokens
    description: Card token and installment plan information.
  - name: Exchange Rate
    description: Currency exchange rates for DCC / cross-border.
paths:
  /paymentToken:
    post:
      operationId: paymentToken
      tags:
        - Payment Token
      summary: Create a payment token
      description: >-
        Initializes a payment and returns a paymentToken plus a webPaymentUrl
        for the hosted payment page. On the wire the request/response are JWTs
        (HS256, merchant secret key); the decoded payloads are modeled here.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentTokenRequest'
      responses:
        '200':
          description: Decoded payment token response payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentTokenResponse'
  /payment:
    post:
      operationId: doPayment
      tags:
        - Do Payment
      summary: Do payment
      description: >-
        Executes a payment against a paymentToken, selecting the channel via the
        payment code (card, e-wallet, QR, installment, pay-later, loyalty) and
        supplying card / customer / browser / return-URL data.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DoPaymentRequest'
      responses:
        '200':
          description: Decoded do-payment response payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DoPaymentResponse'
  /paymentOption:
    post:
      operationId: paymentOption
      tags:
        - Payment Option
      summary: Get payment options
      description: Returns the payment options / channels available for a paymentToken.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentOptionRequest'
      responses:
        '200':
          description: Decoded payment option response payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /paymentOptionDetails:
    post:
      operationId: paymentOptionDetails
      tags:
        - Payment Option
      summary: Get payment option details
      description: Returns detailed metadata for a specific payment option / channel.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentOptionRequest'
      responses:
        '200':
          description: Decoded payment option details response payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /paymentInquiry:
    post:
      operationId: paymentInquiry
      tags:
        - Inquiry
      summary: Payment inquiry
      description: >-
        Retrieves the full result of a transaction by merchantID + invoiceNo,
        returning amount, status, approval / reference codes, masked account /
        card token, installment, and FX details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInquiryRequest'
      responses:
        '200':
          description: Decoded payment inquiry response payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInquiryResponse'
  /transactionStatus:
    post:
      operationId: transactionStatus
      tags:
        - Inquiry
      summary: Transaction status
      description: Returns the current status of a transaction by paymentToken or invoiceNo.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInquiryRequest'
      responses:
        '200':
          description: Decoded transaction status response payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInquiryResponse'
  /cancelTransaction:
    post:
      operationId: cancelTransaction
      tags:
        - Maintenance
      summary: Cancel / void a transaction
      description: >-
        Voids or cancels a transaction. Refund and settle operations are covered
        by the 2C2P payment maintenance guides.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelTransactionRequest'
      responses:
        '200':
          description: Decoded cancel/void response payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /cardTokenInfo:
    post:
      operationId: cardTokenInfo
      tags:
        - Tokens
      summary: Card token info
      description: Retrieves information about a stored card token for recurring / returning-buyer use.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardTokenInfoRequest'
      responses:
        '200':
          description: Decoded card token info response payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /cardInstallmentPlanInfo:
    post:
      operationId: cardInstallmentPlanInfo
      tags:
        - Tokens
      summary: Card installment plan info
      description: Returns the available installment plans for a card / merchant.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInquiryRequest'
      responses:
        '200':
          description: Decoded installment plan info response payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /exchangeRate:
    post:
      operationId: exchangeRate
      tags:
        - Exchange Rate
      summary: Exchange rate
      description: >-
        Retrieves currency exchange rates for a transaction, supporting dynamic
        currency conversion (DCC). A JWT+JWS secured variant is also available.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeRateRequest'
      responses:
        '200':
          description: Decoded exchange rate response payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
components:
  schemas:
    PaymentTokenRequest:
      type: object
      required:
        - merchantID
        - invoiceNo
        - description
        - amount
        - currencyCode
      properties:
        merchantID:
          type: string
          description: Merchant identifier issued by 2C2P.
        invoiceNo:
          type: string
          description: Unique merchant invoice / order number for this transaction.
        description:
          type: string
        amount:
          type: number
          description: Transaction amount.
        currencyCode:
          type: string
          description: ISO 4217 currency code (e.g. SGD, THB, USD).
        paymentChannel:
          type: array
          items:
            type: string
          description: Optional list of allowed payment channels.
        tokenize:
          type: boolean
          description: Request card tokenization for future / recurring use.
        cardTokens:
          type: array
          items:
            type: string
        recurring:
          type: boolean
        invoicePrefix:
          type: string
        frontendReturnUrl:
          type: string
          format: uri
          description: Browser redirect URL after payment.
        backendReturnUrl:
          type: string
          format: uri
          description: Server-to-server notification (webhook) URL.
        locale:
          type: string
    PaymentTokenResponse:
      type: object
      properties:
        webPaymentUrl:
          type: string
          format: uri
          description: Hosted payment page URL to redirect the customer to.
        paymentToken:
          type: string
        respCode:
          type: string
          description: Response code, e.g. "0000" for success.
        respDesc:
          type: string
    DoPaymentRequest:
      type: object
      required:
        - paymentToken
      properties:
        paymentToken:
          type: string
        payment:
          type: object
          description: The selected payment channel and its data.
          properties:
            code:
              type: object
              description: Channel / agent routing codes (channelCode, agentCode, etc.).
              additionalProperties: true
            data:
              type: object
              description: >-
                Channel-specific data - for cards, an encryptedCardInfo /
                securePayToken from Secure Fields plus cardholder details; for
                other methods, the corresponding fields.
              additionalProperties: true
        clientIP:
          type: string
        clientID:
          type: string
        locale:
          type: string
        responseReturnUrl:
          type: string
          format: uri
        browserDetails:
          type: object
          additionalProperties: true
    DoPaymentResponse:
      type: object
      properties:
        respCode:
          type: string
        respDesc:
          type: string
        data:
          type: string
          description: Redirect / 3DS / channel action data where applicable.
        channelCode:
          type: string
        invoiceNo:
          type: string
    PaymentOptionRequest:
      type: object
      required:
        - paymentToken
      properties:
        paymentToken:
          type: string
        locale:
          type: string
    PaymentInquiryRequest:
      type: object
      required:
        - merchantID
      properties:
        merchantID:
          type: string
        invoiceNo:
          type: string
        paymentToken:
          type: string
        locale:
          type: string
    PaymentInquiryResponse:
      type: object
      properties:
        merchantID:
          type: string
        invoiceNo:
          type: string
        amount:
          type: number
        currencyCode:
          type: string
        transactionDateTime:
          type: string
        agentCode:
          type: string
        channelCode:
          type: string
        approvalCode:
          type: string
        referenceNo:
          type: string
        accountNo:
          type: string
          description: Masked account / card number.
        cardToken:
          type: string
        installmentPeriod:
          type: integer
        interestRate:
          type: number
        fxAmount:
          type: number
        fxRate:
          type: number
        fxCurrencyCode:
          type: string
        transactionStatus:
          type: string
        respCode:
          type: string
        respDesc:
          type: string
    CancelTransactionRequest:
      type: object
      required:
        - merchantID
        - invoiceNo
      properties:
        merchantID:
          type: string
        invoiceNo:
          type: string
    CardTokenInfoRequest:
      type: object
      required:
        - merchantID
        - cardToken
      properties:
        merchantID:
          type: string
        cardToken:
          type: string
        locale:
          type: string
    ExchangeRateRequest:
      type: object
      required:
        - merchantID
        - invoiceNo
      properties:
        merchantID:
          type: string
        invoiceNo:
          type: string
        amount:
          type: number
        currencyCode:
          type: string
    GenericResponse:
      type: object
      properties:
        respCode:
          type: string
        respDesc:
          type: string
      additionalProperties: true