Scenario
When the payment is authorized, merchants can call Searching single order of credit card transaction API to check [Status]. After checking the status merchants can request this API to do the following functions.
Capture
1. If the payment is successful, when calling Searching single order of credit card transaction API, the order status would be [authorized]. Next step, merchants can request this API (Action = C) to capture this order.
2. When capturing this order, merchants can request Searching single order of credit card transaction API to check the [Status]. If it is [To be captured], it indicates this order will be requesting fund to the bank.
3. If requesting fund process is completed, at this moment requesting Searching single order of credit card transaction API the [Status] will be [Captured].
Refund
1. Call Searching single order of credit card transaction API to check [Status].
2. Call this API, and if:
- [Status]= [Authorized]: merchants request (Action=N) (Abandoning Transaction.)
- [Status]= [To be captured]:
i. To fully refund this payment: firstly request (Action=E) [Canceling capture] followed by (Action=N) [Abandoning or cancel transaction].
ii. To partially refund: request (Action=R) [refund payment].
- [Status]= [Captured]: request (Action=R) [refund payment].
[Action] instructions: capture
Action=C: indicating “capture”, i.e. to capture this order. It is suggested to capture the order as soon as the payment is authorized
Special note:
- Orders must be captured within 21 days even if the merchant turned off the automatic capture function on merchant’s admin portal (please see preliminary preparation).
- If orders are not captured within 21 days, an error message-error_overDAY will be showed, and merchants can only contact ECPay’s customer services to manually capture this order.
- If orders are not captured on the 80th day since authorized date, a notification will be sent to the merchant; uncaptured orders over 90 days will be cancelled /abandoned.
[Action] instructions: refund
Action=R: indicating “refund”, i.e. merchants can release the credit line captured (held) in the cardholder’s credit card account (either in whole or in partial), by revising the amount. The amount to be refunded (released) should not exceed the order amount.
Special note:
- Authorization of installments can only be refunded in whole, not in partial. Partial refunds are only applicable to regular authorization.
- Authorization with bank bonus should be refunded in whole not in partial.
- Merchants cannot do refund if merchant’s balance in ECPay system is less than the amount to be refunded. In this case, it is advised that merchant deposit or pre-pay enough amount in merchant’s account in ECPays’ system.
[Action] instructions: cancelling capture
Action=E: indicating “cancelling capture”, i.e. merchants can cancel capture and to reverse the order status to previous statue (e.g. if [Status] = captured, when requesting Action=E, the status will roll back to uncaptured
[Action] instructions: abandoning transaction
Action=N: indicating “abandoning transaction”, i.e. merchants abandon (cancel) the transaction/order before the order to be captured. If the order is abandoned, the order will not be processed to the bank for fund.
Special note:
- This API does not support the “disable payment” function for authorization of recurring payment. To disable recurring payment, please go to the ECPay’s dashboard to adjust settings.
- The path is: Merchant’s dashboard > Credit card receipt > Regular quota inquiry > Detail/Edit.
API URLs
- Stage: not available on Stage since Stage cannot perform real authorization.
- Production: https://ecpayment.ecpay.com.tw/1.0.0/Credit/DoAction
Message format
- Content Type：application/json
- HTTP Method：POST
Request (Json format)
MerchantID String(10)
Required
For platform merchants, the value please populate with the Platform merchant’s MerchantID.
RqHeader Object
Required
Request header
Timestamp Number
Required
Unix timestamp
Special note:
- ECPay will verify the timestamp.If ECPay receives the request is more 10 minutes late than the timestamp, the transaction will be failed.
- Merchants are suggested to synchronize the time of a computer on client- or server-side to another server or nearest reference time source.
- For more details can be seen here; another online tool can be found here.
Data String
Required
Payload of JSON that has been encrypted.
Request Example (Json format)
{
"MerchantID": "3002607",
"RqHeader": {
"Timestamp": 1234567890
},
"Data": "enter your data"
}
Message payload of Data (Json format)
Special note: please urlencode the JSON string firstly and then do AES encryption.
PlatformID String(10)
Platform merchant’s MerchantID.
MerchantID String(10)
Required
MerchantTradeNo String(20)
Required
Merchant’s order ID
TradeNo String(20)
Required
ECPay’s order ID
Action String(1)
Required
The action to the order. Perform actions to order (details as the above [Action] instructions.)
- C: capture order
- R: refund order
- E: cancelling captured
- N: abandon transaction
TotalAmount Int
Required
Total amount of order.
Data Example:(Json format)
{
"MerchantID": "3002607",
"MerchantTradeNo": "20180914001",
"TradeNo": "1809261503338172",
"Action": "C",
"TotalAmount": 100
}
Response (Json format)
MerchantID String(10)
Merchant ID
RpHeader Object
Timestamp Number
Unix timestamp
TransCode Int
Response codes to indicate whether the payload is successfully accepted.
- 1: Payload (i.e. MerchantID, RqHeader, and Data) is successfully accepted by ECPay.
- Others: failed.
TransMsg String(200)
Response message to indicate whether the payload is successfully accepted.
Data String
Payload of JSON that has been encrypted.
Response Example (Json format)
{
"MerchantID": "3002607",
"RpHeader": {
"Timestamp": 1234564848
},
"TransCode": 1,
"TransMsg": "Success",
"Data": "…"
}
Message payload of Data (Json format)
RtnCode Int
Response codes to indicate whether the API is successfully executed or not.
- 1: API is successfully executed.
- Others: failed.
- For more details please see error codes.
RtnMsg String(200)
Response messages.
PlatformID String(10)
MerchantID String(10)
MerchantTradeNo String(20)
Merchant’s order ID. Merchant’s order ID (a unique identifier).
TradeNo String(20)
ECPay’s order ID
Data Example(Json format)
{
"RtnCode": 1,
"RtnMsg": "Success",
"MerchantID": "3002607",
"MerchantTradeNo": "20180914001",
"TradeNo": "1809261503338172",
}