Creating Order / Periodic fixed-amount by Credit Card

Scenario

This payment can be used when a periodic and fixed amount of each installment needs to be collected. Customers only need to authorize their card once, and ECPay will process authorizations periodically according to the settings. The payment page will display the amount for each purchase, the number of installments (i.e. the frequency), and number of authorizations. It can be set to “once every x days” or “once every x years”, and the number of payments (authorizations) can be predetermined.

Step 1. Merchant：Set the ChoosePayment payment method to Credit.
Step 2. ECPay：accepts order from merchant and check details.

Special Note：

Merchants should apply for the installment periods with ECPay firstly before using this function. The periods that can be used are only those approved after merchants apply with ECPay.
It is not possible to set the parameters for installment payments at the same time.
Stage environment: Please use the credit card test number provided by ECPay to simulate payment.
If the deduction fails six times, the periodic fixed-amount payment will be cancelled.

Transaction Flow Chart

Flowchart of the Second Post-Fixed Term Transaction

Request Parameters Description (Common Parameters)

MerchantID String(10)
Required

Merchant ID (provided by Green World).

MerchantTradeNo String(20)
Required

Transaction ID (provided by the merchant).

Merchant Transaction IDs are unique and can not be reused.
The value of this parameter is a combination of upper and lower case alphanumeric characters.

Special Note：Please refer to the FAQ on how to avoid duplication of order numbers.

MerchantTradeDate String(20)
Required

Transaction time.

Format:yyyy/MM/dd HH:mm:ss

PaymentType String(20)
Required

Transaction type.

Please fill in aio

TotalAmount Int
Required

Transaction amount.

Only integer is allowed; decimal is not accepted.
The currency should be New Taiwan Dollars only.

TradeDesc String(200)
Required

Transaction description.

Do not use special characters.

ItemName String(400)
Required

Merchandise name.

1. If this field will include more than 1 product and on the webpage each product is expected to be displayed line by line, each product’s name should be separated by hash (#).
2. Maximum length: 400 characters(Chinese and English). ECPay will automatically cut the length exceeding this maximum. Please refer to the FAQ.

ReturnURL String(200)
Required

A return URL for payment notification.

When the consumer completes payment, ECPay will respond payment completed notification (callback) to this parameter (using server Site POST). For more detail about the data of the callback please see Payment result notification (callback).

Special note：

This is a server-side URL. Please do not set this URL the same as [OrderResultURL], which is the URL of the client-side, in order to avoid errors.
Upon receiving the callback from ECPay, please respond a string “1|OK“.
The string “1|OK” is merely a response, which is to tell ECPay’s server that this callback is successfully received by merchant’s server. This response “1|OK” will not change the payment status.

ChoosePayment String(20)
Required

Choose default payment method.
ECPay provides the following payment methods which are transmitted at the time the order is created:

Credit: Credit card

CheckMacValue String
Required

Checksum.

Please refer to the Appendix Checksum Mechanism.

EncryptType Int
Required

CheckMacValue encryption type.
Possible value:

1:SHA256 encryption.

StoreID String(10)

Merchant store ID.

Allows merchants to enter specific store ID.
This parameter only allows a combination of upper and lower case alphanumeric characters.

ClientBackURL String(200)

Button to return to merchant on client’s end.

The page will be directed to the URL when the customer clicks on this button

Special Note：

The URL only redirects the page to the URL set on client’s end without payment result.
If this parameter is set, ECPay will display the “Back to store” button on the payment complete page or the ATM virtual number retrieval page.
If this parameter is set, the page will display the “Back to store” button when OTP authentication fails.
If this parameter is not set, then ECPay will not display the “Back to store” button on the payment complete page or the ATM virtual number retrieval page.
Some browsers may display a warning if the return URL is not an https address.

ItemURL String(200)

Merchandise URL.

Remark String(100)

Additional notes.

OrderResultURL String(200)

The client end returns the payment result URL.

If merchants set a URL in this parameter, when a payment is completed, ECPay will return the payment result to the URL set using client site post.

Special Note：

If this parameter is set with [ClientBackURL], ECPay will accept this parameter but ignore [ClientBackURL].
This parameter does not support UnionPay cards or non-real-time transactions (ATM, CVS, BARCODE).
OrderResultURL can easily be affected by user mishandling or temporary network issues, resulting in not receiving log.It is recommended to rely on the return log from the ReturnURL.

NeedExtraPaidInfo String(1)

Do you require additional payment information
Additional payment information:

Please return N for parameter value if you do not need to return additional payment information.
Please return Y for parameter value if you need to return additional payment information. After payment is completed, ECPay will return the additional payment information via Server Site POST.

Special Note：Please refer to the additional returns parameter page for information on returning additional payment information parameters.

PlatformID String(10)

Platform merchant ID (Provided by Green World).

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.

CustomField1 String(50)

Merchant notes field

Special Note：Special symbols only supports ,.#()$[];%{}:/?&@<>!

CustomField2 String(50)

Merchant notes field

Special Note：Special symbols only supports ,.#()$[];%{}:/?&@<>!

CustomField3 String(50)

Merchant notes field

Special Note：Special symbols only supports ,.#()$[];%{}:/?&@<>!

CustomField4 String(50)

Merchant notes field

Special Note：Special symbols only supports ,.#()$[];%{}:/?&@<>!

Language String(3)

Language settings. The default language is Chinese. To change the language, please set the following value:

English: ENG
Korean: KOR
Japanese: JPN
Simplified Chinese: CHI

Credit Card Fixed Term Parameters

PeriodAmount Int
Required

The amount of per authorization.

Special Note：

The subsequent fixed-authorized amount will be based on the first authorized amount [PeriodAmount].
The transaction amount [TotalAmount] must be identical to the authorized amount [PeriodAmount].
Only integer is allowed. Decimals are not accepted. New Taiwan Dollars only.

PeriodType String (1)
Required

Types of periods. This parameter allows the following values：

D：Days as unit of frequency
M：Months as unit of frequency
Y：Years as unit of frequency

Frequency Int
Required

Execution frequency.

This parameter is used to define how often the action is executed.

Special Note：

If [PeriodType] = D, [Frequency] = 1 to 365 (max).
If [PeriodType] = M, [Frequency] = 1 to 12 (max).
If [PeriodType] = Y, [Frequency] = 1.

ExecTimes Int
Required

Number of executions.

Number of executions in total.

Special Note：

The value must be greater than 1.
When the value of [PeriodType] is set to D, it can be set up to 999 times.
When the value of [PeriodType] is set to M, it can be set up to 99 times.
When the value of [PeriodType] is set to Y, it can be set up to 9 times.

PeriodReturnURL String (200)

Periodic fixed-amount execution results response URL.

If the transaction is a periodic fixed-amount purchase, authorization results will be returned to this URL after each authorization.

Special Note：

This cannot be used with the installment payment parameter.
The amount of per authorization is identical.
If the first authorization fails, the subsequent authorizations will not be scheduled. Please re-create an order.
If the parameter [PeriodReturnURL] is not set, the merchant should only ship the merchandise after confirming that the authorization state is successful via admin website for merchants.
For detailed examples please refer to the Periodic Fixed-Amount Purchases Examples.
To disable the function of periodic fixed-amount purchases, please log in to the admin website for merchants. The operation to disable it can be found under Credit card acquiring > Periodic fixed-amount purchases inquiry > Details/Edit.
UniPay does not support the function of Periodic fixed-amount payment.
Foreign card support the function of Periodic fixed-amount payment if the merchant apply with ECPay.
Periodic fixed-amount payment supports only VISA/MasterCard/JCB.

Screen

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 All-in-One Payment API
  description: API for creating orders and redirecting to ECPay's payment page, allowing various payment methods.
  version: 1.0.0
servers:
  - url: https://payment-stage.ecpay.com.tw
    description: Test Environment
  - url: https://payment.ecpay.com.tw
    description: Production Environment
paths:
  /Cashier/AioCheckOut/V5:
    post:
      summary: Create an order and redirect to ECPay's payment page
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                MerchantID:
                  type: string
                  maxLength: 10
                  description: Merchant ID
                  example: "2000132"
                MerchantTradeNo:
                  type: string
                  maxLength: 20
                  description: Unique merchant trade number
                  example: "1234567890"
                MerchantTradeDate:
                  type: string
                  format: date-time
                  description: Merchant trade date and time
                  example: "2024/05/27 12:34:56"
                PaymentType:
                  type: string
                  description: Payment type (fixed as aio)
                  example: "aio"
                  enum: ["aio"]
                TotalAmount:
                  type: integer
                  description: Total transaction amount (in TWD)
                  example: 1000
                TradeDesc:
                  type: string
                  maxLength: 200
                  description: Transaction description
                  example: "Test transaction"
                ItemName:
                  type: string
                  maxLength: 400
                  description: Names of the items
                  example: "Item1#Item2"
                ReturnURL:
                  type: string
                  maxLength: 200
                  description: URL for payment completion notification
                  example: "https://www.yourdomain.com/receive"
                ChoosePayment:
                  type: string
                  maxLength: 20
                  description: Default payment method
                  example: "Credit"
                  enum: ["Credit"]
                CheckMacValue:
                  type: string
                  description: Check Mac value for security
                  example: "6A7A8F08F6BCB08C3B0E60C90B7A8F14"
                EncryptType:
                  type: integer
                  description: Encryption type (fixed as 1)
                  example: 1
                  enum: [1]
                ClientBackURL:
                  type: string
                  maxLength: 200
                  description: URL to redirect client back to the merchant's site
                  example: "https://www.yourdomain.com"
                ItemURL:
                  type: string
                  maxLength: 200
                  description: URL of the item being sold
                  example: "https://www.yourdomain.com/item"
                Remark:
                  type: string
                  maxLength: 100
                  description: Remark field
                  example: "Additional notes"
                OrderResultURL:
                  type: string
                  maxLength: 200
                  description: URL to send payment result to client
                  example: "https://www.yourdomain.com/result"
                NeedExtraPaidInfo:
                  type: string
                  maxLength: 1
                  description: Whether extra payment info is needed (Y/N)
                  example: "Y"
                  enum: ["Y","N"]
                IgnorePayment:
                  type: string
                  maxLength: 100
                  description: Payment methods to hide
                  example: "ATM#CVS"
                PlatformID:
                  type: string
                  maxLength: 10
                  description: Platform ID for partnership
                  example: ""
                CustomField1:
                  type: string
                  maxLength: 50
                  description: Custom field 1
                  example: "Custom value 1"
                CustomField2:
                  type: string
                  maxLength: 50
                  description: Custom field 2
                  example: "Custom value 2"
                CustomField3:
                  type: string
                  maxLength: 50
                  description: Custom field 3
                  example: "Custom value 3"
                CustomField4:
                  type: string
                  maxLength: 50
                  description: Custom field 4
                  example: "Custom value 4"
                Language:
                  type: string
                  maxLength: 3
                  description: Language setting (default is CHI)
                  example: "ENG"
                  enum: ["ENG","KOR","JPN","CHI"]
                PeriodAmount:
                  type: integer
                  description: Period amount
                PeriodType:
                  type: string
                  maxLength: 1
                  description: Period type (D, M, Y)
                Frequency:
                  type: integer
                  description: Frequency
                ExecTimes:
                  type: integer
                  description: Execution times
                PeriodReturnURL:
                  type: string
                  maxLength: 200
                  description: Period return URL
              required:
                  - MerchantID
                  - MerchantTradeNo
                  - MerchantTradeDate
                  - PaymentType
                  - TotalAmount
                  - TradeDesc
                  - ItemName
                  - ReturnURL
                  - ChoosePayment
                  - CheckMacValue
                  - EncryptType

Green World