Server APIs

Overview

Our server adapts REST archetype, so all requests are sent using HTTP POST.

Payment Method Definitions
To help developers understand which fields apply to specific transaction types, the following defines what “Direct Pay”, “Electronic Payment (E-payment)”, and “Token Pay” refer to in TapPay APIs.

Direct Pay
Definition:
Direct Pay refers to transactions where customers enter their credit card information directly on the merchant’s frontend to make a payment through TapPay’s payment gateway.

E-Payment
Definition:
E-payment refers to transactions made through e-wallet accounts. Include: LINE Pay, JKOPay and Easy Wallet etc., please refer to the e-payments support list for all supported e-payments.

Supported fields and behaviors vary by e-payment providers.

Token Pay
Definition:
Token Pay exclusively refers to transactions made with tokenized credit cards provisioned by mobile wallets (Apple Pay, Google Pay, Samsung Pay).

Pay by Prime API

• The data flow of non-3D secure transaction
  

• The data flow of 3D secure transaction

If you would like to execute a 3D secure transaction, please fill in “true” in the value of “three_domain_secure”, and fill in corresponding value of “frontend_redirect_url” and ” backend_notify_url”.

To avoid the condition which transaction status is inconsistent with TapPay system due to unsuccessful receipt of our Backend Notify, it is recommended that after receiving the frontend redirect url from TapPay and before displaying the transaction result page to the consumer on the front end, you can call the Record API (use rec_trade_id as the search criteria) to check the latest transaction result.

• This API allows you to pay using the prime token obtained from your Frontend.
  
• The prime token may only be used once, so you need to create a new token everytime before you call this API.
  
• If the parameter “remember” is set as true, you will get the card_key and card_token in the Pay by Prime API response. You can directly use them to call Pay by Card Token API, so that you can pass the step of createToken. After saving card_key and card_token, you can call Pay by Card Token API to handle recurring transaction on every fixed date or period with fixed amount that you set in your system. This feature doesn’t support Apple Pay, Google Pay, Samsung Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay.
• To ensure your information is correct, please set your timeout to 30 seconds.
  

Name(* = required.)	Type(Max)	Usage
prime*	String(71)	The one time token returned from getPrime. The prime will be expired after 90 seconds. If using Apple Pay Deferred Payments, please keep prime by yourself.(The duration of each prime is set up for 30 days as default.) You can use test prime for test in sandbox environment.
partner_key*	String(64)	Authentication key for each individual partner.
merchant_id*	String(50)	Involved merchant’s identifier as defined on Portal.
merchant_group_id	String(50)	The merchant management settings set on the portal, transactions will be performed according to the portal’s payment configuration during the transaction. Cannot be used with merchant_id at the same time.
amount*	int	Transaction price.  Except TWD, transaction price should times 100. For instance,  if transaction price is HKD1, please fill in 100 in this parameter. Please see the reference for each foreign currency’s transaction limit.
merchandise_details	JSONObject	The item amount or points that are excluded from redeems. Only supported by some e-payments. Please refer to the e-payments support list.
currency	String(3)	Transaction currency. Format follows the ISO 4217 alphabetic code, e.g., TWD. Refer to the reference for currencies supported by the bank.
order_number	String(50)	A self-defined identifier for each transaction, for TapPay to identify transaction. This parameter doesn’t allow null.
bank_transaction_id	String(40)	Transaction identifier for the bank. You may customize one here if you wish, but it must be unique. We strongly recommend you to define the unique bank_transaction_id by yourself to avoid error 421: gateway time out. Please refer to the reference for its format rule.
details	String(100)	Item description. Required for PCI compliance. If acquirer supports, this field will be forwarded by TapPay. This field is required by some acquirers. If omitted, the transaction may fail. Format requirements vary by acquirer, so please refer to reference for more details
cardholder*	JSONObject	Information of the cardholder (* = required). The following information will be used in the “Fraud Detector”. The quality of the fraud detector will be much better if the cardholder information is provided as detail as possible. If this transaction requires identity verification(KYC), please refer to the rule of each supported bank in the Reference of cardholder description and bring in the correct values in the corresponding parameter fields Optional parameters should have the matching key as well, with empty string as the value. e.g. zip_code: “”, address: “”, national_id: “” Name Type(Length) Usage phone_number* String(40) Cellphone number, could be starting with 09 or E. 164 format with the ’+’ sign(“+886923456789”) name* String(40) Name email* String(40) E-mail address zip_code String(40) Zip code number address String(90) Billing address national_id String(40) National ID member_id String(64) The member ID of the buyer or cardholder. Used for TapPay fraud detection and member management. Supported: Direct Pay. bank_member_id String(50) Member ID of the cardholder or consumer. This identifier is defined or exchanged between the merchant and the bank or e-wallet provider. This field is required for binding transaction on e-payments. Only supported by some e-payments. Please refer to the e-payments support list.
cardholder_verify	JSONObject	Authentication Fields. Note: If this transaction requires identity authentication (KYC), you must provide required cardholder informations in cardholder field, please refer to the Reference of cardholder description for each acquirer required. If a field is marked as “true”, the information corresponding to the cardholder field will be sent to the acquirer for identity authentication (KYC). To perform two-step identity authentication (KYC), please ensure that you enter your Merchant ID from the KYC verification merchant settings found in Merchant Management > KYC in the Portal into the kyc_verification_merchant_id field. If using an AE card for identity authentication (KYC), a charge of 1 dollar will be deducted and refunded within two weeks. If you need to test identity authentication (KYC) transaction in sandbox environment, please refer national id and phone number for testing. Supported: Direct Pay There are two usage scenarios as follows: Scenario Support Authentication Acquiring Bank Support Authorization Acquiring Bank Support Issuer Remarks Using the same merchant id to do authentication and authorization National Credit Card Center of R.O.C. National Credit Card Center of R.O.C. All issuers Phone number cannot be verified. Refer to reference Taishin Bank Taishin Bank All issuers E.SUN BANK E.SUN BANK On-us card Phone number cannot be verified. Refer to reference Two-step authentication (authentication and authorization handled by different acquirers) National Credit Card Center of R.O.C. All the banks supported by TapPay All TapPay KYC All the banks supported by TapPay Visa, MasterCard and JCB that issued in Taiwan. National ID cannot be verified. Refer to reference Verification fields Name Type Usage phone_number Boolean Whether to verify phone number national_id Boolean Whether to verify national id
kyc_verification_merchant_id	String	The merchant id can only do authentication except authorization. Support Industry : property and life insurance industry / electronic payment industry
instalment	int(2)	Number of intervals of payments for a particular transaction. Default set this value as 0. Support: Taishin Bank, National Credit Card Center of R.O.C., NewebPay, Cathay United Bank, E.SUN BANK, CTBC BANK, globalpayments, UNION BANK OF TAIWAN Only Support: Direct Pay
delay_capture_in_days	int	The number of days between the time bank authorizes the payment and the time bank actually captures the payment. Default is 0. If you wish to capture the payment yourself, use -1 as the value to disable automatic capture. Each acquiring bank has its capture deadline, please confirm with your acquiring bank before deciding your capture period. Be aware that your captures might be failed if you didn’t complete the capture by the banks capture deadline.
three_domain_secure	Boolean	Enable 3D Secure authentication. Default is false. Only applicable to Direct Pay. Refer to Reference for supported banks.
result_url	JSONObject	Transaction result notification URL. Required for e-payment and Direct Pay 3D transactions (when three_domain_secure = true) Name Type Content frontend_redirect_url String Frontend redirect URL of the merchant. Must start with https. After the transaction is completed, TapPay will redirect the customer to this URL via web redirection. Refer to Frontend Redirect for redirect parameters. Required for e-payment and Direct Pay 3D transactions. backend_notify_url String Transaction result notification URL. After the transaction is completed, TapPay will send a backend notification to this URL. Refer to the Backend Notify API for the request content. This URL must start with https and only supports port 443. Required for e-payment and Direct Pay 3D transactions. go_back_url String(500) The URL of the Go back button in the TapPay Payment Error page which will appear when the customers execute the 3D secure process unproperly.You can define this URL in this parameter or set up in the Developer > System Settings > Go back url setting in TapPay Portal。 Strongly recommended that you determine the URL in this parameter or TapPay portal in case the customer can’t go back to the store page to check the transaction result while they’ve been led to the error page.We suggest this url can be set as the home page or the chart page of your online store.
redeem	boolean	Whether to use the redeem. Support: National Credit Card Center of R.O.C. Only Support: Direct Pay
remember	boolean	Indicates whether to store this payment method. If set to true, the response will return a card_secret (card_key and card_token), which can be used for future Pay by Card Token API transactions. Supported only for Direct Pay and some e-payments with binding transaction support. Please refer to the e-payments support list.
additional_data	JSONString(3000)	Data will be encrypted and decrypted when other customization requirements.
event_code	String(50)	A code which be defined by the bank, E-Wallet and merchants. Support: Easy Wallet
product_image_url	String(500)	The picture of the store or the product on the pay page.The feature of this parameter is same as line_pay_product_image_url. However, if you set both product_image_url and line_pay_product_image_url in the request, we will use the url in product_image_url.Please refer to the reference page to see the rule of each supported partners.
jko_pay_insurance_policy	StringArray	JKOPAY insurance details of property and life insurance transaction Support: JKOPAY The parameters below are required when doing the property and life insurance transaction via JKOPAY. Name Type(Max) Content proposer String(10) National id of proposer insured StringArray National id of insured insurance_type String Insurance type. Please refer to Reference for more spec details policy_id String(60) Policy id. self-defined payment_deadline Long Payment deadline payment_frequency Int Payment frequency. Please refer to Reference for more spec details final_price Int Insurance price. The sum of all insurance price should equal to the number you set in the amount of Pay by Prime API.
store_id	String(10)	Store branch ID. If supported by the acquirer, this field will be forwarded. See reference for supported format/ acquirer.
store_name	String(50)	Store name. If supported by the acquirer, this field will be forwarded. See reference for supported format/ acquirer.

// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/payment/pay-by-prime
// Production URL: https://prod.tappaysdk.com/tpc/payment/pay-by-prime
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "prime": String,
  "partner_key": String,
  "merchant_id": "merchantA",
  "details":"TapPay Test",
  "amount": 100,
  "cardholder": {
      "phone_number": "+886923456789",
      "name": "Jane Doe",
      "email": "Jane@Doe.com",
      "zip_code": "12345",
      "address": "123 1st Avenue, City, Country",
      "national_id": "A123456789"
  },
  "remember": true
}

---

Response

Name	Type(Max)	Usage
status	int	Response code. 0 indicates success.
msg	String	Error message.
rec_trade_id	String(20)	Unique identifier for this transaction generated by our server.
bank_transaction_id	String(40)	Transaction identifier for the bank. You may customize one here if you wish, but it must be unique. We strongly recommend you to define the unique bank_transaction_id by yourself to avoid error 421: gateway time out. Please refer to the reference for its format rule.
bank_order_number	String	Acquirer’s returned order number after authorization. See reference for supported format/ acquirer.
auth_code	String(6)	Authorization code. Supported only for Direct Pay and Token Pay.
card_secret	JSONObject	Payment credential, contains the card key and token. Supported only for Direct Pay and some e-payments with binding transaction support. Please refer to the e-payments support list. Name Type Usage card_token String(67) Card token. It will be used when calling Pay by Card Token API. card_key String(64) Card authorization key. It will be used when calling Pay by Card Token API.
amount	int	Transaction price.  Except TWD, transaction price should times 100. For instance,  if transaction price is HKD1, will return 100.
currency	String(3)	Transaction currency. Format follows the ISO 4217 alphabetic code, e.g., TWD. Refer to the reference for currencies supported by the bank.
card_info	JSONObject	Card information. Supported only for Direct Pay and Token Pay. Name Type(Max) Content bin_code String(6) First six digits of the card last_four String(4) Last four digits of the card issuer String Card issuer issuer_zh_tw String Issuer chinese name bank_id String Bank identifier funding int Card usage -1 = Unknown 0 = Credit Card 1 = Debit Card 2 = Prepaid Card type int Card type -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX level String Card level country String Country of card issuer country_code String Country code of card issuer expiry_date String Card expired date. Format : YYYYMM. Only returned for Direct Pay when remember = true.
order_number	String(50)	A self-defined identifier for each transaction, for TapPay to identify transaction.
acquirer	String	Acquiring banks or payment processors.
transaction_time_millis	long	Time of transaction.
bank_transaction_time	JSONObject	Time when the bank handles the transaction.
bank_result_code	String(40)	Response code from the bank.
bank_result_msg	String(300)	Error message from the bank.
payment_url	String	Payment redirect url, send it to frontend. Not Support : Apple Pay , Google Pay, Samsung Pay.
instalment_info	JSONObject	When use instalment and non 3D transaction will return. Only Support : Direct Pay. Name Type Content number_of_instalments int Installment period first_payment int First period amount each_payment int Each period amount extra_info JSONObject Each bank return different installment parameter , please refer to extra_info
redeem_info	JSONObject	When use redeem and non 3D transaction will return. Only Support : Direct Pay. Name Type Content used_point String Points be used balance String Points balance offset_amount String credit due_amount String amount due extra_info JSONObject Each bank return different redeem parameter , please refer to extra_info
card_identifier	String	Card identifier. Each credit card corresponds to a unique identifier. Supported only for Direct Pay and Token Pay.
merchant_reference_info	JSON	Merchant reference information Name Type Content affiliate_codes Array This parameter will be returned when the merchant uses the feature of Affiliate Code in TapPay Portal and the transaction match the setting or the affiliate code that TapPay receive from E-wallet. Only Support: Direct Pay, Apple Pay, Google Pay, Samsung Pay
event_code	String(50)	A code which be defined by the bank, E-Wallet and merchants. Support: Easy Wallet
is_rba_verified	Boolean	If this transaction got the risk score from RBA or not.RBA is able to evaluate the risk of each transaction to recognize and prevent the fraud. This product will be launched soon. Please refer to TapPay official website to know more about RBA.
transaction_method_details	JSONObject	Transaction method details. RBA is able to evaluate the risk of each transaction to recognize and prevent the fraud. This product will be launched soon. Please refer to TapPay official website to know more about RBA. Name Type Content transaction_method String THREE_DOMAIN_SECURE: Means the transaction was sent to the bank with 3D secure. FRICTIONLESS: Means the transaction was sent to the bank with frictionless. transaction_method_reference String RBA: Means the transaction method was decided by RBA rule setting. REQUEST: Means the transaction method was decided by the request specification that the merchant set in the payment request.

Pay by Card Token API

• The data flow of non-3D secure transaction
  

• The data flow of 3D secure transaction

If you would like to execute a 3D secure transaction, please fill in “true” in the value of “three_domain_secure”, and fill in corresponding value of “frontend_redirect_url” and ” backend_notify_url”.

This API allows you to pay using a permanent card key and token, thus allowing you to skip the createToken and the payByPrime API.

To avoid the condition which transaction status is inconsistent with TapPay system due to unsuccessful receipt of our Backend Notify, it is recommended that after receiving the frontend redirect url from TapPay and before displaying the transaction result page to the consumer on the front end, you can call the Record API (use rec_trade_id as the search criteria) to check the latest transaction result.

• During peak hour, banks might take longer to process the transaction. To ensure your information is correct, please set your timeout to 30 seconds.
  
• If the parameter “remember” is set as true, you will get the card_key and card_token in the Pay by Prime API response. You can directly use them to call Pay by Card Token API, so that you can pass the step of createToken. After saving card_key and card_token, you can call Pay by Card Token API to handle recurring transaction on every fixed date or period with fixed amount that you set in your system.

Name (* = required.)	Type(Max)	Usage
card_key*	String(64)	Card authorization key.
card_token*	String(67)	Card token.
partner_key*	String(64)	Authentication key for each individual partner.
merchant_id*	String(50)	Involved merchant’s identifier as defined on Portal.
merchant_group_id	String(50)	The merchant management settings set on the portal, transactions will be performed according to the portal’s payment configuration during the transaction. Cannot be used with merchant_id at the same time.
amount*	int	Transaction price.  Except TWD, transaction price should times 100. For instance,  if transaction price is HKD1, please fill in 100 in this parameter. Please see the reference for each foreign currency’s transaction limit.
currency*	String(3)	Transaction currency. Format follows the ISO 4217 alphabetic code, e.g., TWD. Refer to the reference for currencies supported by the bank.
order_number	String(50)	A self-defined identifier for each transaction, for TapPay to identify transaction. This parameter doesn’t allow null.
bank_transaction_id	String(40)	Transaction identifier for the bank. You may customize one here if you wish, but it must be unique. We strongly recommend you to define the unique bank_transaction_id by yourself to avoid error 421: gateway time out. Please refer to the reference for its format rule.
details	String(100)	Item description. Required for PCI compliance. If acquirer supports, this field will be forwarded by TapPay. This field is required by some acquirers. If omitted, the transaction may fail. Format requirements vary by acquirer, so please refer to reference for more details
cardholder_verify	JSONObject	Authentication Fields. Note: If this transaction requires identity authentication (KYC), you must provide required cardholder informations in cardholder field, please refer to the Reference of cardholder description for each acquirer required. If a field is marked as “true”, the information corresponding to the cardholder field will be sent to the acquirer for identity authentication (KYC). To perform two-step identity authentication (KYC), please ensure that you enter your Merchant ID from the KYC verification merchant settings found in Merchant Management > KYC in the Portal into the kyc_verification_merchant_id field. If using an AE card for identity authentication (KYC), a charge of 1 dollar will be deducted and refunded within two weeks. If you need to test identity authentication (KYC) transaction in sandbox environment, please refer national id and phone number for testing. Supported: Direct Pay There are two usage scenarios as follows: Scenario Support Authentication Acquiring Bank Support Authorization Acquiring Bank Support Issuer Remarks Using the same merchant id to do authentication and authorization National Credit Card Center of R.O.C. National Credit Card Center of R.O.C. All issuers Phone number cannot be verified. Refer to reference Taishin Bank Taishin Bank All issuers E.SUN BANK E.SUN BANK On-us card Phone number cannot be verified. Refer to reference Two-step authentication (authentication and authorization handled by different acquirers) National Credit Card Center of R.O.C. All the banks supported by TapPay All TapPay KYC All the banks supported by TapPay Visa, MasterCard and JCB that issued in Taiwan. National ID cannot be verified. Refer to reference Verification fields Name Type Usage phone_number Boolean Whether to verify phone number national_id Boolean Whether to verify national id
kyc_verification_merchant_id	String	The merchant id can only do authentication except authorization. Support Industry : property and life insurance industry / electronic payment industry
instalment	int(2)	Number of intervals of payments for a particular transaction. Default set this value as 0. Support: Taishin Bank, National Credit Card Center of R.O.C., NewebPay, Cathay United Bank, E.SUN BANK, CTBC BANK, globalpayments, UNION BANK OF TAIWAN Only Support: Direct Pay
delay_capture_in_days	int	The number of days between the time bank authorizes the payment and the time bank actually captures the payment. Default is 0. If you wish to capture the payment yourself, use -1 as the value to disable automatic capture. Each acquiring bank has its capture deadline, please confirm with your acquiring bank before deciding your capture period. Be aware that your captures might be failed if you didn’t complete the capture by the banks capture deadline.
three_domain_secure	Boolean	Enable 3D Secure authentication. Default is false. Only applicable to Direct Pay. Refer to Reference for supported banks.
result_url	JSONObject	Transaction result notification URL. Required for e-payment and Direct Pay 3D transactions (when three_domain_secure = true) Name Type Content frontend_redirect_url String Frontend redirect URL of the merchant. Must start with https. After the transaction is completed, TapPay will redirect the customer to this URL via web redirection. Refer to Frontend Redirect for redirect parameters. Required for e-payment and Direct Pay 3D transactions. backend_notify_url String Transaction result notification URL. After the transaction is completed, TapPay will send a backend notification to this URL. Refer to the Backend Notify API for the request content. This URL must start with https and only supports port 443. Required for e-payment and Direct Pay 3D transactions. go_back_url String(500) The URL of the Go back button in the TapPay Payment Error page which will appear when the customers execute the 3D secure process unproperly.You can define this URL in this parameter or set up in the Developer > System Settings > Go back url setting in TapPay Portal。 Strongly recommended that you determine the URL in this parameter or TapPay portal in case the customer can’t go back to the store page to check the transaction result while they’ve been led to the error page.We suggest this url can be set as the home page or the chart page of your online store.
card_ccv	String	Security code. Cannot be used together with ccv_prime. Supported only for Direct Pay. Use this parameter in the following situations: 1. You did not obtain ccv_prime via get-ccv-prime but still want the bank to verify the security code. 2. You did not obtain ccv_prime and are performing a 3DS 2.0 authentication with an AMEX card.
redeem	boolean	Whether to use the redeem. Support: National Credit Card Center of R.O.C. Only Support: Direct Pay
additional_data	JSONString(3000)	Data will be encrypted and decrypted when other customization requirements.
ccv_prime	String	The one time token of security code returned from get-ccv-prime. Cannot be used with card_ccv at the same time. It will be expired after 90 seconds. Support : Direct Pay You can use this ccv_prime for test in sandbox environment ccv_prime(3 digits):test_65b1ca2d5d0dc8ff5b62296ea8547bab08401f8a57015fb818c5bcd10433fa11 ccv_prime(4 digits):test_cd1e737890874cdadf39caaf56c5b183c36a4117ca89cb24fd674c0892e0fa92
device_id	String(64)	ID of each device. This parameter must be put into the request body when you use the transaction risk analysis sytem of TapPay RBA. To get device ID, please call “Get Device ID ” of TapPay SDK and put it into the Pay by Card Token request body if you use the transaction risk analysis sytem of TapPay RBA.“
is_merchant_initiated_transaction	Boolean	Indicates whether the transaction is a Merchant-Initiated Transaction (MIT) or a Customer-Initiated Transaction (CIT). Default value is false. MIT scenarios: recurring, subscription transactions etc., true = MIT false = CIT

// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/payment/pay-by-token
// Production URL: https://prod.tappaysdk.com/tpc/payment/pay-by-token
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "card_key": String,
  "card_token": String,
  "partner_key": String,
  "currency": "TWD",
  "merchant_id": "merchantA",
  "details":"TapPay Test",
  "amount": 100
}

---

Response

Name	Type(Max)	Usage
status	int	Response code. 0 indicates success.
msg	String	Error message.
rec_trade_id	String(20)	Unique identifier for this transaction
bank_transaction_id	String(40)	Transaction identifier for the bank. You may customize one here if you wish, but it must be unique. Please refer to the reference for its format rule.
bank_order_number	String	Acquirer’s returned order number after authorization. See reference for supported format/ acquirer.
amount	int	Transaction price.  Except TWD, transaction price should times 100. For instance,  if transaction price is HKD1, will return 100.
currency*	String(3)	Transaction currency. Format follows the ISO 4217 alphabetic code, e.g., TWD. Refer to the reference for currencies supported by the bank.
auth_code	String(6)	Authorization code. Supported only for Direct Pay and Token Pay.
card_info	JSONObject	Card information. Supported only for Direct Pay and Token Pay. Name Type(Max) Content bin_code String(6) First six digits of the card last_four String(4) Last four digits of the card issuer String Card issuer issuer_zh_tw String Issuer chinese name bank_id String Bank identifier funding int Card usage -1 = Unknown 0 = Credit Card 1 = Debit Card 2 = Prepaid Card type int Card type -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX level String Card level country String Country of card issuer country_code String Country code of card issuer expiry_date String Card expired date. Format : YYYYMM. Only returned for Direct Pay when remember = true.)
order_number	String(50)	A self-defined identifier for each transaction, for TapPay to identify transaction.
acquirer	String	Acquiring banks or payment processors.
transaction_time_millis	long	Time of transaction.
bank_transaction_time	JSONObject	Time when the bank handles the transaction. Please refer to the reference for its format rule.
bank_result_code	String(40)	Response code from the bank.
bank_result_msg	String(300)	Error message from the bank.
payment_url	String	Payment redirect url, send it to frontend. Not Support: Apple Pay, Google Pay, Samsung Pay
instalment_info	JSONObject	When use instalment and non 3D transaction will return. Only Support: Direct Pay Name Type Content number_of_instalments int Installment period first_payment int First period amount each_payment int Each period amount extra_info JSONObject Each bank return different installment parameter , please refer to extra_info
redeem_info	JSONObject	When use redeem and non 3D transaction will return. Only Support: Direct Pay Name Type Content used_point String Points be used balance String Points balance offset_amount String credit due_amount String amount due extra_info JSONObject Each bank return different redeem parameter , please refer to extra_info
card_identifier	String	Card identifier. Each credit card corresponds to a unique identifier. Supported only for Direct Pay and Token Pay.
merchant_reference_info	JSON	Merchant reference information Name Type Content affiliate_codes Array This parameter will be returned when the merchant uses the feature of Affiliate Code in TapPay Portal and the transaction match the setting or the affiliate code that TapPay receive from E-wallet. Only Support: Direct Pay, Apple Pay, Google Pay, Samsung Pay
is_rba_verified	Boolean	If this transaction got the risk score from RBA or not.RBA is able to evaluate the risk of each transaction to recognize and prevent the fraud. This product will be launched soon. Please refer to TapPay official website to know more about RBA.
transaction_method_details	JSONObject	Transaction method details. RBA is able to evaluate the risk of each transaction to recognize and prevent the fraud. This product will be launched soon. Please refer to TapPay official website to know more about RBA. Name Type Content transaction_method String THREE_DOMAIN_SECURE: Means the transaction was sent to the bank with 3D secure. FRICTIONLESS: Means the transaction was sent to the bank with frictionless. transaction_method_reference String RBA: Means the transaction method was decided by RBA rule setting. REQUEST: Means the transaction method was decided by the request specification that the merchant set in the payment request.

Frontend Redirect

After an e-payment or Direct Pay 3D transaction is completed, TapPay will redirect the user to the URL specified in frontend_redirect_url in the request. TapPay will include four parameters related to the transaction result.

Request Header

Key	Value
Content-Type	html/text

Request Url

https://your.domain.com/transaction_is_done?
rec_trade_id=LN20171109WsvKhn&
order_number=CF46019917&
status=0&
bank_transaction_id=TP20171109WsvKhn

Request Query String

Name	Type	Usage
rec_trade_id	String	Unique identifier for this transaction generated by our server.
order_number	String	A self-defined identifier for each transaction. This parameter doesn’t allow null.
bank_transaction_id	String	Transaction identifier for the bank. You may customize one here if you wish, but it must be unique. We strongly recommend you to define the unique bank_transaction_id by yourself to avoid error 421: gateway time out. Please refer to the reference for its format rule.
status	Int	Response code. 0 indicates success.

Frontend redirect could be faked , we suggest you to implement backend notify , If backend notify fail , please use Record API for verifying.

Backend Notify

1. After an e-payment or Direct Pay 3D transaction is completed, TapPay will automatically send a backend notification to the URL specified in backend_notify_url in the request.
2. If you didn’t receive our Backend Notify successfully (not response HTTP 200), TapPay would resend it again every 1, 2, 4, 8, 16 minutes. It will be resent five times at most, if all fails, a notification letter will be sent to Contact person’s and techical Email mailbox. Please follow the instructions to check the latest status of the order to avoid inconsistent transaction status.

Request Header

Key	Value
Content-Type	application/json

Request Url

POST	Url
Sandbox	https://{backend_notify_url}
Production	https://{backend_notify_url}

Request Body

Name	Type	Usage
rec_trade_id	String	Unique identifier for this transaction generated by our server.
auth_code	String	Authorization code. Supported only for Direct Pay and Token Pay.
bank_transaction_id	String	Transaction identifier for the bank. We strongly recommend you to define the unique bank_transaction_id by yourself to avoid error 421: gateway time out.
bank_order_number	String	Acquirer’s returned order number after authorization. See reference for supported format/ acquirer.
order_number	String	A self-defined identifier for each transaction. This parameter doesn’t allow null.
amount	Int	Transaction price.
status	Int	Response code. 0 indicates success.
msg	String	Error message.
transaction_time_millis	Long	Time when the bank handles the transaction.
transaction_complete_millis	long	Time when transaction completed (support E.SUN, Cathay Bank)
pay_info	JSONObject	E-payment related information object. Only returned for e-payments transactions. This object is returned by the e-payments provider. If the provider does not return corresponding information, the parameters within this object may be empty strings or zero. Name Type Content method String The method used by the consumer to complete the e-payment. 1. CREDIT_CARD(credit card) 2. BALANCE(Electronic Payment Account) 3. POINT (Point Redeem) 4. DISCOUNT 5. ACCOUNT_LINK (Bank Account) masked_credit_card_number String Masked card number. Only supported by some e-payments. Please refer to the e-payments support list. point Int The amount of the point discount, if there is no offset, it is 0 discount Int The amount of the coupon discount, if there is no offset, it is 0 credit_card Int Use credit card to pay the amount. If this payment method is not used, it will be displayed as 0 balance Int Use the wallet stored-value account to pay the amount. If this payment method is not used, it will be displayed as 0 bank_account Int Use the linked bank account to pay the amount. If this payment method is not used, it will be displayed as 0 bin_code String First six~eight digits of the card. Will return only when using Plus Pay. Please contact Plus Pay if you need this information. identity String Pay tool identity. Provide by electronic payment service, might be partial account number or credit card number tool_name String Name of the e-payment method. If the payment method is AccountLink or credit card, this field returns the bank name. If it is an e-payment account, it returns the name of the e-payment provider.
acquirer	String	Acquiring banks or payment processors.
e_invoice_carrier	JSONObject	Electronic invoice carrier information Support : JKOPAY, Plus Pay Name Type Content type Int(3) 0:Mobile phone barcode(Return by JKOPAY) 1:Natural person certificate barcode 2:Other carrier barcodes number String(100) Electronic invoice carrier number donation Boolean Donation donation_id String(50) Donation ID
card_identifier	String	Card identifier. Each credit card corresponds to a unique identifier. Supported only for Direct Pay and Token Pay.
bank_result_code	String(40)	Response code from the bank.
bank_result_msg	String(300)	Error message from the bank.
merchant_reference_info	JSON	Merchant reference information Name Type Content affiliate_codes Array This parameter will be returned when the merchant uses the feature of Affiliate Code in TapPay Portal and the transaction match the setting or the affiliate code that TapPay receive from E-wallet. Only Support: Direct Pay, Apple Pay, Google Pay, Samsung Pay
instalment_info	JSONObject	When use instalment will return, Only Support: Direct Pay. Name Type Content number_of_instalments int Installment period first_payment int First period amount each_payment int Each period amount extra_info JSONObject Each bank return different installment parameter , please refer to extra_info
redeem_info	JSONObject	When use redeem and non 3D transaction will return. Only Support : Direct Pay. Name Type Content used_point String Points be used balance String Points balance offset_amount String credit due_amount String amount due extra_info JSONObject Each bank return different redeem parameter , please refer to extra_info
event_code	String(50)	A code which be defined by the bank, E-Wallet and merchants.Support: Easy Wallet
merchandise_details	JSONObject	The item amount or points that are excluded from redeems. Only supported by some e-payments. Please refer to the e-payments support list.

{
    // Example
    "amount": 1,
    "order_number": "KK44845743",
    "status": 0,
    "bank_transaction_id": "TP201711088cHQHr",
    "transaction_time_millis": 1510136365539,
    "acquirer": "TW_LINE_PAY",
    "msg": "Success",
    "rec_trade_id": "LN201711088cHQHr",
    "pay_info": {
        "point": 0,
        "masked_credit_card_number": "************2178",
        "method": "CREDIT_CARD"
    }
}

Refund API

• This API allows you to refund your transaction, reversing both the capture action as well as the authorization action.
  If partial refund is required, then this API is also needed.
  
• During peak hour, banks might take longer to process the transaction.
  To ensure your information is correct, please set your timeout to 30 seconds.
  
• When you call Refund API, TapPay will send the refund request to the banks on the same day.
  To confirm whether the captured is succeed, we suggest you check the transaction status on TapPay Portal or call Record API to double confirm the transaction status on the next day.
• To make sure the consistence of the transaction result between acquiring banks and TapPay. It’s not allowed to call Refund API during capping time of acquiring banks.
  You could call Refund API until TapPay get confirmative transaction results from the acquiring banks. Please wait patiently and refer to the Each bank capture time）to know when could TapPay receives confirmative transaction results from each acquiring banks.

Name(* = Required)	Type(Max)	Usage
partner_key*	String(64)	Authentication key for each individual partner.
rec_trade_id*	String(20)	Identifier for the transaction being refunded.
bank_refund_id	String(20)	Self-defined refund record identifier. (Format : Half-shaped English number and must be unique). If supported by the acquirer, this field will be forwarded. See reference for supported format/ acquirer.
amount	int	Only required for partial refund. The amount must include two decimal places(except “TWD”). For example, “100” represents “$1.00”
additional_data	JSONString(3000)	Data will be encrypted and decrypted when other customization requirements.
merchandise_details	JSONObject	The item amount or points that are excluded from redeems. Only supported by some e-payments. Please refer to the e-payments support list.

// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/transaction/refund
// Production URL: https://prod.tappaysdk.com/tpc/transaction/refund
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "partner_key": String,
  "rec_trade_id": String,
  "amount": int // Optional
}

Response

Name	Type(Max)	Usage
status	int	Response code. 0 indicates success.
msg	String	Error message.
refund_amount	int	Amount being refunded. Except TWD, transaction price should times 100. For instance,  if transaction price is HKD1, will return 100.
refund_info	JSONObject	Refund information Points and refund amount information returned by the e-payment. This object is only returned for e-payment transactions, and only certain e-payment providers include this information. Please refer to the e-payments support list. Name Type Usage returned_reward_amount Int returned reward amount. returned_real_amount Int returned cash. If there’s no returned cash, it displays 0.
refund_id	String	Identifier for the action refunded.
bank_refund_order_number	String	The refund order number that banks or e-wallets send back while refund. See Reference for supported format/ acquirer.
is_captured	boolean	Whether the transaction has been captured or not.
bank_result_code	String(40)	Response code from the bank.
bank_result_msg	String(300)	Error message from the bank.
currency	String(3)	Transaction currency. Format follows the ISO 4217 alphabetic code, e.g., TWD. Refer to the reference for currencies supported by the bank.

Record API

This API allows you to get the trade records.

Name(* = required)	Type(Max)	Default	Usage
partner_key*	String(64)		Authentication key for each individual partner.
records_per_page	int	50	Number of records on each page, up to 200.
page	int	0	The returned page.
filters	JSONObject	None	Restrictions on the trade records. The following filters are possible: time* Time frame should be 90 days or less. amount cardholder merchant_id record_status rec_trade_id order_number bank_transaction_id auth_code currency tsp card_identifier
order_by	JSONObject	attribute = time is_descending = true	Criteria for ordering

// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/transaction/query
// Production URL: https://prod.tappaysdk.com/tpc/transaction/query
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "partner_key": String,
  "records_per_page": int,
  "page": int,
  "filters": {
    "time": {
      "start_time": long,
      "end_time": long
    },
    "amount": {
      "upper_limit": int,
      "lower_limit": int
    },
    "cardholder": {
     "phone_number": String,
     "name": String,
     "email": String
   },
    "merchant_id": [String],
    "record_status": int,
    "rec_trade_id": String,
    "order_number": String,
    "bank_transaction_id": String,
    "currency": String
  },
  "order_by": {
    "attribute": String, // "time"(Order by time) or "amount"(Order by amount)
    "is_descending": boolean
  }
}

Response

Name	Type(Max)	Usage
status	int	Response code. 2 indicates end of list, meaning there are no more records to be shown under the given filter.
msg	String	Error message.
records_per_page	int	Number of records on each page, up to 200.
page	int	The returned page.
total_page_count	int	Total number of pages.
number_of_transactions	long	Total number of transactions.
trade_records	JSONArray	Trade records.