Credit Card for Periodic Fixed-Amount Purchases Operation

Scenario

The Special Shop carries out regular fixed-amount credit card order transactions.

ReAuth：When the latest periodic fixed-amount purchases authorization fails, you can reauthorize.
Cancel：Cancel periodic fixed-amount purchases.

API URLS

Stage：https://payment-stage.ecpay.com.tw/Cashier/CreditCardPeriodAction
Production：https://payment.ecpay.com.tw/Cashier/CreditCardPeriodAction

HTTPS Transfer Protocol

Content Type：application/x-www-form-urlencoded
HTTP Method：POST

Merchant return parameter details

MerchantID String(10)
Required

MerchantTradeNo String(20)
Required

Merchant Transaction ID transmitted to ECPay when order was created.

Action String(20)
Required

ReAuth：Re authorize
Cancel：Cancel periodic fixed-amount purchases

TimeStamp Int
Required

Convert current time to UnixTimeStamp (see example) to verify the time interval of this interfacing.

ECPay verification time interval is currently set to be under 3 minutes and interfacing will expire if time is exceeded.
Reference: http://www.epochconverter.com/。

CheckMacValue String
Required

Please refer to the Appendix Checksum Mechanism.

PlatformID String(10)

Used by contracted platform merchants.

For general merchants or platform merchant interfacing, please leave empty.
For use by platform merchants, please set [MerchantID] as the parameter.

Special Note：

The credit card is only available when the latest authorization for a transaction has failed, e.g. if the second authorization fails but the third one is successful, the second failed transaction cannot be re-authorised at that time.
Once a deactivated transaction has been successfully completed, it cannot be re-activated and can only be done by re-initiating a new fixed term order.

Merchant return parameter description

RtnCode Int

A return value of 1 indicates successful authorization, while any other value indicates failure. For more information on error codes, please refer to the list of transaction status codes.

Special Note：A retroactive license transaction is scheduled to be sent to [PeriodReturnURL] by the system to send a notification of the result of the retroactive license.

RtnMsg String(200)

MerchantID String(10)

MerchantTradeNo String(20)

Merchant Transaction ID transmitted to ECPay when order was created.

CheckMacValue String

Please refer to the Appendix Checksum Mechanism.

Special Note：The shop must determine whether the check code [CheckMacValue] is correct and whether the payment notification for the order has been processed accordingly to avoid loss of synchronisation of the transaction status.

YAML

The provided YAML file is used to define information such as the configuration, structure, operations, and infrastructure management of the API, making it easier for developers to understand and use the API.

				
					openapi: 3.1.0
info:
  title: ECPay Credit Card Recurring Order API
  version: 1.0.0
  description: API for managing ECPay credit card recurring orders, including reauthorization and cancellation.

servers:
  - url: https://payment-stage.ecpay.com.tw
    description: Test Environment
  - url: https://payment.ecpay.com.tw
    description: Production Environment

paths:
  /Cashier/CreditCardPeriodAction:
    post:
      summary: Manage recurring credit card orders
      description: API to reauthorize or cancel recurring credit card orders.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                MerchantID:
                  type: string
                  maxLength: 10
                MerchantTradeNo:
                  type: string
                  maxLength: 20
                Action:
                  type: string
                  enum: [ReAuth, Cancel]
                TimeStamp:
                  type: integer
                CheckMacValue:
                  type: string
                PlatformID:
                  type: string
                  maxLength: 10
              required:
                - MerchantID
                - MerchantTradeNo
                - Action
                - TimeStamp
                - CheckMacValue
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  RtnCode:
                    type: integer
                    description: Transaction status (1 for success, others for failure)
                  RtnMsg:
                    type: string
                    maxLength: 200
                    description: Transaction message
                  MerchantID:
                    type: string
                    maxLength: 10
                    description: Merchant ID
                  MerchantTradeNo:
                    type: string
                    maxLength: 20
                    description: Merchant trade number
                  CheckMacValue:
                    type: string
                    description: Check code

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    RequestData:
      type: object
      properties:
        MerchantID:
          type: string
          maxLength: 10
        MerchantTradeNo:
          type: string
          maxLength: 20
        Action:
          type: string
          enum: [ReAuth, Cancel]
        TimeStamp:
          type: integer
        CheckMacValue:
          type: string
        PlatformID:
          type: string
          maxLength: 10
      required:
        - MerchantID
        - MerchantTradeNo
        - Action
        - TimeStamp
        - CheckMacValue
    ResponseData:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Transaction status (1 for success, others for failure)
        RtnMsg:
          type: string
          maxLength: 200
          description: Transaction message
        MerchantID:
          type: string
          maxLength: 10
          description: Merchant ID
        MerchantTradeNo:
          type: string
          maxLength: 20
          description: Merchant trade number
        CheckMacValue:
          type: string
          description: Check code

Green World