Notifications / PeriodReturnURL

Scenario

For orders of recurring (repeated) payments, ECPay will send notification to PeriodReturnURL (merchants’ server side) after every successful authorization.

Step1. ECPay’s server: send the the notifications to PeriodReturnURL since the second authorization, which is scheduled and will be processed automatically.
Step2. Merchant’s server: respond a string 1|OK.

Special note:

The first notification is sent to ReturnURL, while the rest recurring payments is sent to PeriodReturnURL.

Message format

Accept ：text/html
Content Type：application/json
HTTP Method：POST

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)

Platform ID

MerchantID String(10)

OrderInfo Object

Order information

MerchantTradeNo String(20)

Merchant’s order ID

TradeNo String(20)

ECPay’s order ID. Please save this parameter in merchant’s system in order to keep the relation between ECPay’s order ID merchants’ order ID MerchantTradeNo.

TradeAmt Int

Transaction amount

TradeDate String(20)

Time at which the order was created. Format: yyyy/MM/dd HH:mm:ss

PaymentType String(20)

Payment method

PaymentDate String(20)

Date of payment. Format: yyyy/MM/dd HH:mm:ss

ChargeFee Number

ECPay’s service charge

TradeStatus String(8)

Status of transaction

CardInfo Object

Credit card information. If using credit card or Union Pay, the CardInfo will be returned.

AuthCode String(6)

Authorization code. Not returned if using Union Pay card.

Gwsr Int

ID of authorization

ProcessDate String(20)

Date of processing authorization. Format: yyyy/MM/dd HH:mm:ss

Amount Int

Transaction/authorization amount

Stage Int

Number of installments

Stast Int

Amount of down payment

Staed Int

Amount of each period (except for down payment)

Eci Int

Return value of 3D (VBV). This is a value returned from the Directory Server (Visa, MasterCard, and JCB) to indicate the authentication results of cardholder’s credit card payment on 3D Secure.

Possible values:

5, 6, 2, 1: The value returned (ECI) means that transaction was a 3D secure authentication.

Card6No String(6)

First 6 digits of credit card

Card4No String(4)

Last 4 digits of credit card

PeriodType String(1)

Type of subscription.

Frequency Int

Execution frequency.

ExecTimes Int

Number of authorizing recurring payments

PeriodAmount Int

Amount to be authorized of each period.

TotalSuccessTimes Int

Number of total successful authorizations.

TotalSuccessAmount Int

Total amount of all successful authorizations.

IssuingBank String(30)

Bank name

IssuingBankCode String(10)

Bank code

CustomField String(200)

A parameter for merchant to place customized value.

Data Example(Json format):

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success",
    "MerchantID": "3002607",
    "OrderInfo": {
        "MerchantTradeNo": "20180914001",
        "TradeNo": "1809261503338172",
        "TradeDate" :"2018/09/26 14:59:54"
    },
    "CardInfo": {
        "Gwsr": 10735183,
        "ProcessDate": "2018/09/26 14:59:54",
        "AuthCode": "777777",
        "Amount": 100,
        "Eci": 2,
        "Card4No": "2222",
        "Card6No": "491122",
        "Frequency": 5,
        "ExecTimes": 5,
        "PeriodAmount": 500,
        "TotalSuccessTimes": 2,
        "TotalSuccessAmount":1000,
        "IssuingBank":"玉山",
        "IssuingBankCode":"808"
    }
}

Special note:

PeriodReturnURL will receive notification only once (no retry function, which is different from ReturnURL). If your server did not receive it, please send API request to check the authorization state (Search an order of a recurring payment (server)).
If consumers already paid but merchants did not receive the notifications, please check check if the server is in normal service. Common errors can be referred to: FAQ.
If RthCode is not 1, please do not ship the product to consumers. Instead, please record the RtnMsg and check the root cause.

Green World