NAV
docs

Server APIs

Overview

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

Pay by Prime API

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.

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 methodTest prime
Direct Paytest_3a2fb2b7e892b914a03c95dd4dd5dc7970c908df67a49527c0a648b2bc9
Apple Pay Please set amount 12
ap_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
Google Pay(Tokenize)gp_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
Google Pay(Real Card) gp_test_kjo6i5uthfuehfjgit867584urjfhtyr74ytuhjyu7685jtufyejgitu
LINE Payln_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
Samsung Pay sp_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
JKOPAYjk_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
Easy Walletew_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
Atomeat_test_utigjeyfutj5867uyjhuty47rythfjru485768tigjfheufhtu5i6ojk
Pi Walletpi_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
NameTypeContent
no_rebate_amountIntThe amount of non-applicable rebate (for example: cigarette)
no_bonus_amountIntThe 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: “”
NameType(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_codeString(40)Zip code number
addressString(90)Billing address
national_idString(40)National ID
member_idString(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 field. If this transaction requires identity verification(KYC), please refer to the rule of each supported bank in the Reference of cardholder description. If the field is “true”, the corresponding value in cardholder will be sent to the corresponding acquiring bank for identity verification(KYC) depends on the different scenario.
You can use testing national id and phone number in sandbox environment.
Support: Direct Pay
ScenarioSupport Authentication Acquiring BankSupport Authorization Acquiring BankSupport IssuerRemarks
Using the same merchant id to do authentication and authorizationNational Credit Card Center of R.O.C.National Credit Card Center of R.O.C.All issuersPhone number cannot be verified. Refer to reference
Taishin BankTaishin BankAll issuers
E.SUN BANKE.SUN BANKOn-us cardPhone number cannot be verified. Refer to reference
Authentication:National Credit Card Center of R.O.C.
Authorization:All the banks supported by TapPay
National Credit Card Center of R.O.C.All the banks supported by TapPayAllkyc_verification_merchant_id is required. You can find it from portal (Merchant > KYC Verification Merchant Setting)
Verification fields
NameTypeUsage
phone_numberBooleanWhether to verify phone number
national_idBooleanWhether to verify national id
kyc_verification_merchant_id String The merchant id can only do authentication except authorization.
Support : National Credit Card Center of R.O.C.
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
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.
NameTypeContent
frontend_redirect_urlStringThe 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_urlStringThe backend URL of the merchant server to receive the transaction result. Must start with https, only suport 443 port.
go_back_urlStringThe 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
proposerString(10)National id of proposer
insuredStringArrayNational id of insured
insurance_type StringInsurance type. Please refer to Reference for more spec details
policy_idString(60)Policy id. self-defined
payment_deadline LongPayment deadline
payment_frequency Int Payment frequency. Please refer to Reference for more spec details
final_priceInt 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
NameType(Max)Usage
shopper_infoJSONObjectShopper 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.
NameTypeUsage
card_tokenString(67)Card token. It will be used when calling Pay by Card Token API.
card_keyString(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
NameType(Max)Content
bin_codeString(6)First six digits of the card
last_fourString(4)Last four digits of the card
issuerStringCard issuer
issuer_zh_twStringIssuer chinese name
bank_idStringBank identifier
fundingintCard usage
-1 = Unknown
0 = Credit Card
1 = Debit Card
2 = Prepaid Card
typeintCard type
-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
4 = Union Pay
5 = AMEX
levelStringCard level
countryStringCountry of card issuer
country_codeStringCountry code of card issuer
expiry_dateStringCard 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.
NameTypeContent
number_of_instalmentsintInstallment period
first_paymentintFirst period amount
each_paymentintEach period amount
extra_infoJSONObjectEach 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.
NameTypeContent
used_pointStringPoints be used
balanceStringPoints balance
offset_amountStringcredit
due_amountStringamount due
extra_infoJSONObjectEach 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
NameTypeContent
affiliate_codesArrayThis 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.
NameTypeContent
transaction_methodStringTHREE_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_referenceStringRBA: 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

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.

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 field. If this transaction requires identity verification(KYC), please refer to the rule of each supported bank in the Reference of cardholder description. If the field is “true”, the corresponding value in cardholder will be sent to the corresponding acquiring bank for identity verification(KYC) depends on the different scenario.
You can use testing national id and phone number in sandbox environment.
Support: Direct Pay
ScenarioSupport Authentication Acquiring BankSupport Authorization Acquiring BankSupport IssuerRemarks
Using the same merchant id to do authentication and authorizationNational Credit Card Center of R.O.C.National Credit Card Center of R.O.C.All issuersPhone number cannot be verified. Refer to reference
Taishin BankTaishin BankAll issuers
E.SUN BANKE.SUN BANKOn-us cardPhone number cannot be verified. Refer to reference
Authentication:National Credit Card Center of R.O.C.
Authorization:All the banks supported by TapPay
National Credit Card Center of R.O.C.All the banks supported by TapPayAllkyc_verification_merchant_id is required. You can find it from portal (Merchant > KYC Verification Merchant Setting)
Verification fields
NameTypeUsage
phone_numberBooleanWhether to verify phone number
national_idBooleanWhether to verify national id
kyc_verification_merchant_id String The merchant id can only do authentication except authorization.
Support : National Credit Card Center of R.O.C.
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
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
NameTypeContent
frontend_redirect_urlStringThe 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_urlStringThe backend URL of the merchant server to receive the transaction result. Must start with https, only suport 443 port.
go_back_urlStringThe 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
NameType(Max)Content
bin_codeString(6)First six digits of the card
last_fourString(4)Last four digits of the card
issuerStringCard issuer
issuer_zh_twStringIssuer chinese name
bank_idStringBank identifier
fundingintCard usage
-1 = Unknown
0 = Credit Card
1 = Debit Card
2 = Prepaid Card
typeintCard type
-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
4 = Union Pay
5 = AMEX
levelStringCard level
countryStringCountry of card issuer
country_codeStringCountry code of card issuer
expiry_dateStringCard 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
NameTypeContent
number_of_instalmentsStringInstallment period
first_paymentStringFirst period amount
each_paymentStringEach period amount
extra_infoJSONObjectEach 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
NameTypeContent
used_pointStringPoints be used
balanceStringPoints balance
offset_amountStringcredit
due_amountStringamount due
extra_infoJSONObjectEach 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
NameTypeContent
affiliate_codesArrayThis 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.
NameTypeContent
transaction_methodStringTHREE_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_referenceStringRBA: 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.
NameTypeContent
methodStringPaymeny Type,Only support LINE Pay
1. CREDIT_CARD(credit card)
2. BALANCE(iPASS)
3. POINT (LINE Point Fully offset)
4. DISCOUNT
masked_credit_card_numberStringCredit card last four digits
pointIntThe amount of the point discount, if there is no offset, it is 0
discountIntThe amount of the coupon discount, if there is no offset, it is 0
credit_cardIntUse credit card to pay the amount. If this payment method is not used, it will be displayed as 0
balanceIntUse the wallet stored-value account to pay the amount. If this payment method is not used, it will be displayed as 0
bank_accountIntUse the linked bank account to pay the amount. If this payment method is not used, it will be displayed as 0
acquirer String Acquiring banks or payment processors.
e_invoice_carrier JSONObject Electronic invoice carrier information
Support : JKOPAY, Plus Pay
NameTypeContent
typeInt(3)0:Mobile phone barcode(Return by JKOPAY)
1:Natural person certificate barcode
2:Other carrier barcodes
numberString(100)Electronic invoice carrier number
donationBooleanDonation
donation_idString(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
NameTypeContent
affiliate_codesArrayThis 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
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.
NameTypeContent
number_of_instalmentsintInstallment period
first_paymentintFirst period amount
each_paymentintEach period amount
extra_infoJSONObjectEach 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.
NameTypeContent
used_pointStringPoints be used
balanceStringPoints balance
offset_amountStringcredit
due_amountStringamount due
extra_infoJSONObjectEach 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
NameTypeContent
no_rebate_amountIntThe amount of non-applicable rebate (for example: cigarette)
no_bonus_amountIntThe 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

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.
// *** 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_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.