Scenario
When the shop offers consumers to transact with the barcode on the payment page.
- Step 1. Merchant:Set the ChoosePayment payment method to Barcode.
- Step 2. ECPay:accepts order from merchant and check details.
Transaction Flow Chart
Request Parameters Description (Common Parameters)
MerchantID String(10)
Required
MerchantTradeNo String(20)
Required
- 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.
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
- 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
- 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:
- BARCODE: Convenience store barcodes
CheckMacValue String
Required
Checksum.
- Please refer to the Appendix Checksum Mechanism.
EncryptType Int
Required
CheckMacValue encryption type.
Possible value:
- 1:SHA256 encryption.
Merchant store ID.
- Allows merchants to enter specific store ID.
- This parameter only allows a combination of upper and lower case alphanumeric characters.
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)
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.
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.
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.
- English: ENG
- Korean: KOR
- Japanese: JPN
- Simplified Chinese: CHI
BARCODE Parameters
Convenience store payment deadline.
- payment using BARCODE, the unit in days
If the value is not set, the default value is 7 days - Setting maximum 30 days, minimum 1 day.
Special Note:the unit in days,If you want to set more than 30 days, you can only apply for it with your business.
The server end will return payment related information.
- If this parameter is set, when an order is created (not payment completed), ECPay will return the customer’s payment information via Server Site POST (for example, reference number to be paid at convenience store and specific convenience stores).
- Please refer to [ATM, CVS, or Barcode Code Retrieval Results Notification Result].
Special Note:
- The page will stay on ECPay to display relevant payment information.
- Only 3 barcode-numbers will be returned, while the barcode image will not be returned. Merchants need to convert the barcode number into a code 39 barcode label.
The client end returns payment method related information..
- If this parameter is set, after an order is created (not payment completed), ECPay will return the customer’s payment information to the client’s end (for example, reference number to be paid at convenience store and specific convenience stores), and will direct to the merchant’s designated page.
- Please refer to [ATM, CVS, or Barcode Code Retrieval Results Notification Result].
Special Note:
- If this parameter is set, it will invalidate the hyperlink button [ClientBackURL] to return to the merchant.
- Some browsers may display a warning if the return URL is not an https address.
- Only 3 barcode-numbers will be returned, while the barcode image will not be returned. Merchants need to convert the barcode number into a code 39 barcode label.
Screen
Barcode Payment Method Screen
Barcode payment result 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: "BARCODE"
enum: ["BARCODE"]
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"]
StoreExpireDate:
type: integer
description: payment using BARCODE, the unit in days. If the value is not set, the default value is 7 days. Setting maximum 30 days, minimum 1 day.
example: 7
PaymentInfoURL:
type: string
maxLength: 200
description: The server end will return payment related information.
ClientRedirectURL:
type: string
maxLength: 200
description: The client end will return payment related information.
required:
- MerchantID
- MerchantTradeNo
- MerchantTradeDate
- PaymentType
- TotalAmount
- TradeDesc
- ItemName
- ReturnURL
- ChoosePayment
- CheckMacValue
- EncryptType