Capture and Refund

Capture Process Description

If the payment is successful, request Searching single order of credit card transaction API will respond [authorized]; next merchants can request this API (Action = C) to capture this order.
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.
If requesting fund process is completed, at this moment requesting Searching single order of credit card transaction API the [Status] will be [Captured].
The account will be capture as soon as the UnionPay card authorization is completed.

Capture Flowchart

Refund Process Description

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].

Full refund flowchart (Authorized)

Full refund flowchart (To be captured)

Full refund flowchart（Captured）

Partial refund flowchart

Scenario

When the payment is authorized, merchants can call Searching single order of credit card transaction API to check [Status] followed by requesting this API to do the following jobs.

Special note：If the “Daily automatic capture” function (on Merchant’s Admin Website) is enabled, please do not call this API between 20:15-20:30.

Capture

If the payment is successful, request Searching single order of credit card transaction API will respond [authorized]; next merchants can request this API (Action = C) to capture this order.
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.
If requesting fund process is completed, at this moment requesting Searching single order of credit card transaction API the [Status] will be [Captured].
The account will be capture as soon as the UnionPay card authorization is completed.

Refund

Call Searching single order of credit card transaction API to check [Status].
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

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：

If the “Daily automatic capture” function (on Merchant’s Admin Website) is enabled, ECPay will automatic request fund/refund according to the amount captured.
If the “Daily automatic capture” function is enabled, orders still have to be captured within 21 days.
- (1) If orders are not captured within 21 days, merchant cannot call API to capture the order. An error message—error_overDAY— will be responded if calling API to capture; merchants should contact ECPay ‘s customer service to manually capture the order for un-captured orders over 21 days.
- (2) If orders are sill not captured on the 80th day, ECPay will send a notification to inform merchants.
- (3) If orders are not captured over 90 days, ECPay will automatically abandon that order and will not request fund to the bank.

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 installment 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.
Merchant cannot do refund if merchant’s balance is less than the amount to be refunded. Therefore it is suggested that merchant leave enough amount in merchant’s account in ECPay ‘s system or pre-pay an amount into merchant’s balance for refund. If merchants cannot do refund, please check the FAQ: https://www.ecpay.com.tw/CascadeFAQ/CascadeFAQ_Qa?nID=3582 (in Chinese only).

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 rollback to uncaptured.

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 periodic fixed-amount payment. To disable this type of authorization, please go to the Merchant’s Admin Website to adjust settings.
This API (Action=N)does not support partial refund, but will refund the full amount of the order.
The path is: Merchant’s Admin Website → Credit card receipt → Regular quota inquiry → Detail/Edit.

API URLS

Stage: This API can not be used because no real authorizations can be provided.
Production: https://payment.ecpay.com.tw/CreditDetail/DoAction

HTTPS Transfer Protocol

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

Request Parameters Description

MerchantID String(10)
Required

MerchantTradeNo String(20)
Required

Merchant Transaction ID transmitted to ECPay when order was created.

TradeNo String(20)
Required

Please save the link between the ECPay transaction ID and the merchant transaction ID [MerchantTradeNo].

Action String(1)
Required

This API can use 4 actions mentioned above (capture/refund/cancelling capture/abandoning Transaction). Possible values: C, R, E, N

C: capture
R: refund
E: Cancelling capture
N: abandoning transaction

TotalAmount Int
Required

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.

Return Parameter Details

MerchantID String(10)

MerchantTradeNo String(20)

Merchant Transaction ID transmitted to ECPay when order was created.

TradeNo String(20)

ECPay transaction ID.

RtnCode Int

Return value: 1: success, rest: fail

RtnMsg String(200)

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 Refund API
  version: 1.0.0
servers:
  - url: https://payment.ecpay.com.tw
    description: Production Environment
paths:
  /CreditDetail/DoAction:
    post:
      summary: Perform actions on a credit card transaction
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                MerchantID:
                  type: string
                  description: Merchant ID provided by ECPay
                MerchantTradeNo:
                  type: string
                  description: Merchant trade number
                TradeNo:
                  type: string
                  description: ECPay trade number
                Action:
                  type: string
                  description: Action to be performed (C for Close, R for Refund, E for Cancel, N for Abandon)
                TotalAmount:
                  type: integer
                  description: Amount
                CheckMacValue:
                  type: string
                  description: CheckMac value for verification
                PlatformID:
                  type: string
                  description: Partner platform ID
              required:
                - MerchantID
                - MerchantTradeNo
                - TradeNo
                - Action
                - TotalAmount
                - CheckMacValue
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  MerchantID:
                    type: string
                    description: Merchant ID
                  MerchantTradeNo:
                    type: string
                    description: Merchant trade number
                  TradeNo:
                    type: string
                    description: ECPay trade number
                  RtnCode:
                    type: integer
                    description: Transaction status code (1 for success, others for failure)
                  RtnMsg:
                    type: string
                    description: Transaction message

Green World