Server APIs

Overview

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

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.) It will be used by calling Pay By Prime API. You can use this prime for test in sandbox environment. Payment method Test prime Direct Pay test_3a2fb2b7e892b914a03c95dd4dd5dc7970c908df67a49527c0a648b2bc9 Apple Pay Please set amount 12 ap_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk Google Pay(Tokenize) gp_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk Google Pay(Real Card) gp_test_kjo6i5uthfuehfjgit867584urjfhtyr74ytuhjyu7685jtufyejgitu LINE Pay ln_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk Samsung Pay sp_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk JKOPAY jk_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk Easy Wallet ew_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk Atome at_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk Pi Wallet pi_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk Plus Pay(PC) ps_test_pc_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk Plus Pay(mobile) ps_test_mobile_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
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	Product details.Support: JKOPAY, Easy Wallet, Pi Wallet, Plus Pay Name Type Content no_rebate_amount Int The amount of non-applicable rebate (for example: cigarette) no_bonus_amount Int The amount of non-applicable bonus (for example: cigarette)
currency	String(3)	The letter abbreviation for currency, following ISO 4217. Bank store currency please refer to reference, Default TWD. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay.
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)	Details of the transaction. You should include as much information as possible. It will help our fraud detector in distinguishing real and fake transaction. Bank store format please refer to reference If you enable TSP service, and the acquiring bank is Taishin Bank. Please ensure to fill in details; If not, TapPay will fill in bank transaction id insteaded to avoid transaction failure. Please bring in values in this parameter if your acquiring bank is NewebPay, LINE Pay, Atome or it will result in transactions failure.
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) Member ID of the cardholder or the customer determined by merchants. Used in TapPay fraud detector and member information management. Support: Direct Pay
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 Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay. Since customers cannot choose the instalment plan in Atome and Atome will automatically apply 3-month instalment plan of each transaction, this parameter doesn’t support Atome.
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	Whether to use three domain secure or not, default false. Support: Taishin Bank, CTBC Bank, National Credit Card Center of R.O.C, E.SUN BANK, NewebPay, Bank SinoPac, Taipei Fubon Bank, RAZER PAY, CHANG HWA Bank, Cathay United Bank, UNION BANK OF TAIWAN Currently 3D Secure 2.0 only supports the case when the payment is made by AE card and acquired by NCCC. Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay.
result_url	JSONObject	Required when three_domain_secure : true or LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay. Name Type Content frontend_redirect_url String The frontend website URL of the merchant where the customer will be brought to after finishing transaction process on LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay or 3D verification. This URL must start with https. backend_notify_url String The backend URL of the merchant server to receive the transaction result. Must start with https, only suport 443 port. go_back_url String 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. Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay
remember	boolean	To save the card number or not. Not Support: Apple Pay, Google Pay, Samsung Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay Use LINE Pay remember: true only support POINT or Credit Card.
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.
extra_info	JSONObject	Extra Information Support: Atome Name Type(Max) Usage shopper_info JSONObject Shopper Information

// *** 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	The order number that banks or e-wallets send back while authorization. Support : Easy Wallet Please refer to Reference for the length limitation of all supported banks and e-wallets.
auth_code	String(6)	Bank authorization code. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay.
card_secret	JSONObject	Contains the card key and token. Only returned if the “remember” parameter in payByPrime API is set to true. The card key and card token you got by LINE Pay transactions will be expired if this card key and card token haven’t has any successful transaction within 180 days, which will result in transactions failure. Not Support : Apple Pay , Google Pay, Samsung Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay. 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)	The letter abbreviation for currency, following ISO 4217. Bank store currency please refer to reference Not Support : LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay.
card_info	JSONObject	Card information. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus 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, When remember : true will return. (Apple Pay / Google Pay / LINE Pay / Samsung Pay / Atome / Pi Wallet / Plus Pay will not return this parameter)
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. Not Support : Apple Pay , Google Pay, Samsung Pay and LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus 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. Not Support : Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus 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 will only have one card identifier. Not Support : Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus 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. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus 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)	The letter abbreviation for currency, following ISO 4217. Bank store currency please refer to reference
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)	Details of the transaction. You should include as much information as possible. It will help our fraud detector in distinguishing real and fake transaction. Bank store format please refer to reference If you enable TSP service, and the acquiring bank is Taishin Bank. Please ensure to fill in details; If not, TapPay will fill in bank transaction id insteaded to avoid transaction failure. Please bring in values in this parameter if your acquiring bank is NewebPay or LINE Pay, or it will result in transactions failure.
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 Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Plus 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	Whether to use three domain secure or not, default false. Support: Taishin Bank, CTBC Bank, National Credit Card Center of R.O.C, E.SUN BANK, NewebPay, Bank SinoPac, Taipei Fubon Bank, RAZER PAY, CHANG HWA Bank, Cathay United Bank, UNION BANK OF TAIWAN Currently 3D Secure 2.0 only supports the case when the payment is made by AE card and acquired by NCCC. Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Plus Pay
result_url	JSONObject	Required when three_domain_secure : true. Not Support: Apple Pay, Google Pay, LINE Pay, Samsung Pay, Atome, Plus Pay Name Type Content frontend_redirect_url String The frontend website URL of the merchant where the customer will be brought to after finishing transaction process on LINE Pay, JKOPAY APP, Easy Wallet, Atome, Plus Pay or 3D verification. This URL must start with https. backend_notify_url String The backend URL of the merchant server to receive the transaction result. Must start with https, only suport 443 port. go_back_url String 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 with ccv_prime at the same time. Required when there are the following situations 1. Didn’t get ccv_prime from get-ccv-prime but you need the bank to verify the security code. 2. Didn’t get ccv_prime from get-ccv-prime but use the AE card for 3DS2.0 verification transactions. Not support : LINE Pay, JKOPAY, Easy Wallet, Atome, Plus Pay
redeem	boolean	Whether to use the redeem. Support: National Credit Card Center of R.O.C. Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Plus 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.“

// *** 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	The order number that banks or e-wallets send back while authorization. Support : Easy Wallet Please refer to Reference for the length limitation of all supported banks and e-wallets.
amount	int	Transaction price.  Except TWD, transaction price should times 100. For instance,  if transaction price is HKD1, will return 100.
currency*	String(3)	The letter abbreviation for currency, following ISO 4217. Bank store currency please refer to reference
auth_code	String(6)	Bank authorization code. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet,Plus Pay
card_info	JSONObject	Card information. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus 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 (Apple Pay / Google Pay / LINE Pay / Samsung Pay / Atome / Pi Wallet / Plus Pay will not return this parameter)
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, LINE Pay, JKOPAY, Easy Wallet, Atome, Plus Pay
instalment_info	JSONObject	When use instalment and non 3D transaction will return. Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Plus 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. Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Plus 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 will only have one card identifier. Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Plus 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. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Plus 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 LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay or three domain secure transaction, TapPay will redirect to frontend_redirect_url , TapPay will query extra four parameter.

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 LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay or three domain secure transaction , TapPay will POST to backend_notify_url to notify.
2. If you didn’t receive our Backend Notify successfully, 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	Bank authorization code. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus 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	The order number that banks or e-wallets send back while authorization. Support : Easy Wallet Please refer to Reference for the length limitation of all supported banks and e-wallets.
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.
pay_info	JSONObject	When use LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay will return.Only bank account and Debit card can be added to Atome, so the price value will only be showed in pay_info. Name Type Content method String Paymeny Type，Only support LINE Pay 1. CREDIT_CARD(credit card) 2. BALANCE(iPASS) 3. POINT (LINE Point Fully offset) 4. DISCOUNT masked_credit_card_number String Credit card last four digits Will return only when using LINE Pay, Plus Pay. Please contact Plus Pay if you need this information. 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.
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 will only have one card identifier. Not Support : Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus 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. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet
instalment_info	JSONObject	When use instalment will return, Not Support Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus 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. Not Support : Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus 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	Product details.Support: JKOPAY, Easy Wallet, Atome, Plus Pay Name Type Content no_rebate_amount Int The amount of non-applicable rebate (for example: cigarette) no_bonus_amount Int The amount of non-applicable bonus (for example: cigarette)

{
    // 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) Must be unique. Support: E.SUN BANK, Atome
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	Product details.Support: Easy Wallet Name Type Content no_rebate_amount int The amount of non-applicable rebate (for example: cigarette)

// *** 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 When use plus pay will return. This field displays returned reward amount and cash information from wallet after the refund. It will be determined according to the rules of each wallet whether the points or amounts will be returned first after the refund. 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. Support: Easy Wallet, Atome, Pi Wallet, Plus Pay Please refer to Reference for the length limitation of all supported banks and e-wallets.
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)	The letter abbreviation for currency, following ISO 4217. Bank store currency please refer to reference

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.