Scenario
Server Site Post (PaymentInfoURL)
After an order with payment methods ATM / CVS / BARCODE has been created to the user, the merchant will receive the order result from ECPay and response the parameter details.
- Step1. ECPay : The code (virtual account number) retrieval results message will be transmitted via ServerPost to the merchant’s server URL [PaymentInfoURL]
- Step2. Merchant: Upon receiving the code retrieval message from ECPay , check and verify whether the checksum value is correct.
- Step3. Merchant: If the checksum value is correct, respond 1|OK on the webpage end.
Client Site Post (ClientRedirectURL)
After an order has been created to the user, ECPay will return the code (virtual account number) retrieval results message one-time and redirect to the merchant’s designated page.
- Step1. ECPay : The code (virtual account number) retrieval results message will be transmitted to the merchant and redirect the page to the merchant’s designated page.
- Step2. Merchant: Upon receiving the code retrieval message from ECPay , check and verify whether the checksum value is correct.
HTTPS Transfer Protocol
- Accept ：text/html
- Content Type ：application/x-www-form-urlencoded
- HTTP Method ：POST
Return Parameters Description
MerchantID String(10)
MerchantTradeNo String(20)
Merchant transaction ID.
- Merchant Transaction ID transmitted to ecpay when order was created.
Merchant store ID.
- The parameter allows merchants to enter specific store ID.
- This parameter only allows a combination of upper and lower case alphanumeric characters.
RtnCode Int
- When the ATM return value is 2, this means the transaction status is success. The rest indicate failure.
- When the CVS / BARCODE return value is 10100073 this means the transaction status is success. The rest indicate failure.
RtnMsg String(200)
TradeNo String(20)
transaction ID.
- Please save the link between the ECPay transaction ID and the merchant transaction ID [MerchantTradeNo].
TradeAmt Int
PaymentType String(20)
TradeDate String(20)
Transaction time.
- The format is yyyy/MM/dd HH:mm:ss
CheckMacValue String
Checksum.
- The merchant must check the checksum [CheckMacValue] to verify.
BankCode String(3)
Payment bank code
vAccount String(16)
ExpireDate String(100)
Payment deadline.
- The format is yyyy/MM/dd
Special Note：When ATM is selected for transaction, if the payment amount is incorrect, overdue, or repetitive, it is the bank which validates the information related to the payment and the account, rather than the ECPay .
PaymentNo String(14)
Payment code.
- Return when payment method is CVS, return blank if payment method is BARCODE.
ExpireDate String(20)
Payment deadline.
- The format is yyyy/MM/dd HH:mm:ss
Barcode1 String(20)
First barcode strip number.
Barcode2 String(20)
Second barcode strip number.
Barcode3 String(20)
Third barcode strip number.
Merchant parameter transmission details:
The value returned is a text string and does not have parameter names
- If the first digit returned is 1, it is success.
- If the first digit returned is 0, it is failure. 0|ErrorMessage refers (error code – error message).
- The value only means whether the merchant receives the return message from ECPay and parameters are correct.The value does not affect the status of order.
Special Note：
When receiving code retrieval results notifications, please confirm the following details in order to receive the code retrieved notification sent by ECPay .
- (1) Please make sure that parameter for the return URL [PaymentInfoURL] used to confirm the order creation parameter has been developed and completed.
- (2) Please confirm that the return URL [PaymentInfoURL] for payment is available externally.
Barcode1=&Barcode2=&Barcode3=&ExpireDate=2017/12/28 00:39:03&MerchantID=2000132&MerchantTradeNo=Test1513787899&PaymentNo=LLL17355880822&PaymentType=CVS_CVS&RtnCode=10100073&RtnMsg=Get CVS Code Succeeded.&TradeAmt=2000&TradeDate=2017/12/21 00:39:03&TradeNo=17122100383415923452&StoreID=&CustomField1=&CustomField2=&CustomField3=&CustomField4=&CheckMacValue=C25373CE6379BB6116FAE8398F4A8E60B71B289D955F6B8A9D9F53FDCC97F571
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 ATM/CVS/BARCODE Number Acquisition Result Notification API
version: 1.0.0
servers:
- url: PaymentInfoURL
description: Production Environment
- url: PaymentInfoURL
description: Testing Environment
paths:
/payment/number/notification:
post:
summary: ATM/CVS/BARCODE Number Acquisition Result Notification
description: Notify the merchant of the number acquisition result for ATM, CVS, or BARCODE payments.
requestBody:
required: true
content:
html/text:
schema:
type: object
required:
- MerchantID
- MerchantTradeNo
- RtnCode
properties:
MerchantID:
type: string
maxLength: 10
description: Merchant ID
MerchantTradeNo:
type: string
description: Merchant's trade number
StoreID:
type: string
description: Store identifier
RtnCode:
type: integer
description: Return code
RtnMsg:
type: string
description: Return message
TradeNo:
type: string
description: ECPay trade number
TradeAmt:
type: integer
description: Trade amount
PaymentType:
type: string
description: Payment type
TradeDate:
type: string
format: date-time
description: Trade date
CustomField1:
type: string
description: Custom field 1
CustomField2:
type: string
description: Custom field 2
CustomField3:
type: string
description: Custom field 3
CustomField4:
type: string
description: Custom field 4
CheckMacValue:
type: string
description: Check MAC value
BankCode:
type: string
description: Bank code (for ATM payments)
vAccount:
type: string
description: Virtual account number (for ATM payments)
ExpireDate:
type: string
format: date-time
description: Expiry date for payment
PaymentNo:
type: string
description: Payment number (for CVS payments)
Barcode1:
type: string
description: Barcode part 1 (for BARCODE payments)
Barcode2:
type: string
description: Barcode part 2 (for BARCODE payments)
Barcode3:
type: string
description: Barcode part 3 (for BARCODE payments)
responses:
'200':
description: Success
content:
text/plain:
schema:
type: string
example: 1|OK
'400':
description: Invalid request
'500':
description: Server error