NAV
docs

Advanced

Cap Today API

This API allows you to capture a payment today.

After a customer makes a payment, it will undergo the following process:
Authorize > Capture > Bank processing > Success
The time period between a payment goes from being authorized to being captured can be modified when calling our payment APIs.
However, should you change your mind in between, you may call this API to capture that specific transaction today.

When you call Cap Today API, TapPay will send the capture 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. Please refer to Each bank capture time if you need


During peak hour, banks might take longer to process the transaction.
To ensure your information is correct, please set your timeout to 30 seconds.

Name Type(Max) Usage
partner_key String(64) Authentication key for each individual partner.
rec_trade_id String(20) Identifier for the transaction being captured.
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/transaction/cap
// Production URL: https://prod.tappaysdk.com/tpc/transaction/cap
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "partner_key": String,
  "rec_trade_id": String
}

Response

Name Type Usage
status int Response code. 0 indicates success.
msg String Error message.
cap_millis long Time when the transaction payment will be captured.
currency String(3) The letter abbreviation for currency, following ISO 4217.
Bank store currency please refer to reference

Bind Card API

Name(* = required) Type(Max) Usage
prime* String(67) The one time token returned from createToken.
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.
currency* String(3) The letter abbreviation for currency, following ISO 4217.
Bank store currency please refer to reference
three_domain_secure Boolean Whether to use three domain secure or not, default false.

Currently 3D Secure 2.0 only supports the case when the payment is made by AE card and acquired by NCCC.
Support: Taishin Bank, CTBC Bank, National Credit Card Center of R.O.C, E.SUN BANK, NewebPay, SinoPac(New), Fubon, RAZER PAY, CHANG HWA Bank, Cathay United Bank, Union Bank Of Taiwan
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, 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 APP, 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.
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: “”
NameTypeUsage
phone_number*StringCellphone number, could be starting with 09 or E. 164 format with the ’+’ sign(“+886923456789”)
name*StringName
email*StringE-mail address
zip_codeStringZip code number
addressStringBilling address
national_idStringNational 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
bank_member_idString(50)Member ID of the cardholder or the customer.
This ID can be determined by merchants or common ID between merchants and banks or e-wallet.
This column is required when binding Easy Wallet.Support : Easy Wallet
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
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/card/bind
// Production URL: https://prod.tappaysdk.com/tpc/card/bind
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "prime": String,
  "partner_key": String,
  "merchant_id": "merchantA",
  "currency": "TWD",
  "cardholder": {
    "phone_number": "+886923456789",
    "name": "Jane Doe",
    "email": "Jane@Doe.com",
    "zip_code": "12345",
    "address": "123 1st Avenue, City, Country",
    "national_id": "A123456789"
  }
}

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.
order_id String(40) Transaction identifier for the bank. Same as bank_transaction_id, but the name of the parameter in Bind Card API is order_id.
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
auth_code String(6) Bank authorization code. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay
merchant_id String(50) Involved merchant’s identifier as defined on Portal.
acquirer String Acquiring banks or payment processors.
card_secret JSONObject Contains the card key and token.
Not Support: Apple Pay, Google Pay, Samsung Pay, JKOPAY, Atome, Pi Wallet, Plus Pay
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.
NameType(Max)Content
card_tokenString(67)A permanent token that represents the customer’s card,You may use the cardtoken to pay using the Pay by Card Token API
card_keyString(64)A security key usd to encrypt the card token,You may use the cardtoken to pay using the Pay by Card Token
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)
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.
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
payment_url String Payment redirect url, send it to frontend.
Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, 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.

Remove Card API

This API will allow you to delete a card_key and card_token from our server.

During peak hour, banks might take longer to process the transaction.
To ensure your information is correct, please set your timeout to 30 seconds.

Name Type(Max) Usage
partner_key* String(64) Authentication key for each individual partner.
card_key* String(64) A security key used to encrypt the card token.
card_token* String(67) A permanent token that represents the customer’s card.
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/card/remove
// Production URL: https://prod.tappaysdk.com/tpc/card/remove
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "partner_key": String,
  "card_key": String,
  "card_token": String
}

Response

Name Type(Max) Usage
status int Response code. 0 indicates success.
msg String Error message.

Trade History 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 captured.
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/transaction/trade-history
// Production URL: https://prod.tappaysdk.com/tpc/transaction/trade-history
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "rec_trade_id": String
}

Response

Name Type(Max) Usage
rec_trade_id String(20) Identifier for the transaction being captured.
bank_order_number String The order number that banks or e-wallets send back while authorization.
Support : Easy Wallet, Atome, Plus Pay
Please refer to Reference for the length limitation of all supported banks and e-wallets.
currency String(3) The letter abbreviation for currency, following ISO 4217.
Bank store currency please refer to reference
trade_history JSONArray transaction history
status int Response code. 0 indicates success.
msg String Error message.

Reconciliation API

Name(* = required) Type(length) Content
partner_key* String(64) Authentication key for each individual partner.
records_per_page int Number of records on each page, up to 200.
Default : 50
page int The returned page.
Default : 0
start_time_millis* long The real capturing and refunding start-time with bank which is measured in milliseconds.
end_time_millis* long The real capturing and refunding end-time with bank which is measured in milliseconds.
transaction_actions* StringArray Transaction Action
Capturing: CAPTURE
Refund: REFUND
merchant_ids StringArray Involved merchant’s identifier as defined on Portal.
This parameter allows multiple merchant id.
You can only choose merchant id or acquirer to put in the request body.
acquirers StringArray This parameter allows multiple acquirers.
You can only choose merchant id or acquirer to put in the request body.
For the parameter of each acquirer, please refer to reference
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/transaction/reconciliation
// Production URL: https://prod.tappaysdk.com/tpc/transaction/reconciliation
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "transaction_actions": ["CAPTURE", "REFUND"],
    "start_time_millis": long,
    "end_time_millis": long
}

Response

Name Type Content
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.
reconciliation_datas JSONArray Capturing and refunding details of each transaction.
NameTypeContent
merchant_idStringInvolved merchant’s identifier as defined on Portal.
merchant_descriptionStringTapPay merchant reference in Merchant of TapPay Portal.
acquirerStringAcquirer
payment_methodStringPayment Method
NameContent
direct_payDirect Pay
apple_payApple Pay
google_pay_tokenGoogle Pay Token Card
google_pay_fpanGoogle Pay Real PAN
samsung_paySamsung Pay
line_payLINE Pay
tsp_tokenTSP Token
jko_payJKOPAY
easy_walletEasy Wallet
atomeAtome
pi_walletPi Wallet
plus_payPlus Pay
rec_trade_idStringRecord identifier.
bank_transaction_idStringA self-defined unique identifier for the bank.
bank_order_numberStringThe 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.
bank_refund_order_numberStringThe 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.
order_numberStringA self-defined identifier for each transaction, for TapPay to identify transaction.
millislongTrigger status time
bank_transaction_millislongThe practical time that TapPay send the transaction to bank to process authorization, capturing, refund and canceling refund the payment.
transaction_actionStringTransaction Action
Capturing: CAPTURE
Refund: REFUND
transaction_resultBooleanWhether the status is successful.
trade_amountintThe amount of capturing and refunding.
auth_millislongThe time that merchant call TapPay API for authorization.
auth_amountintAmount while authorization.
currencyStringThe transaction currency.
partial_card_numberStringFirst six digits of the card and last four digits of the card
card_typeintCard type
-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
4 = Union Pay
5 = AMEX
auth_codeStringAuthorization code from the bank.
is_kyc_verifiedBooleanWhether to do KYC or not.
instalment_infoJSONObjectWhen use instalment will return.Not Support: Apple Pay, Google Pay, Samsung Pay and LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay.
NameTypeContent
number_of_instalmentsintNumber of instalments
redeem_infoJSONObjectWhen use redeem will return.
Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay.
NameTypeContent
offset_amountStringcredit
pay_infoJSONObjectWhen 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
credit_cardintThe amount of the point discount, if there is no offset, it is 0
balanceintThe amount of the coupon discount, if there is no offset, it is 0
bank_accountintUse credit card to pay the amount. If this payment method is not used, it will be displayed as 0
pointintUse the wallet stored-value account to pay the amount. If this payment method is not used, it will be displayed as 0
discountintUse the linked bank account to pay the amount. If this payment method is not used, it will be displayed as 0

Refund Cancel API

This API allows you to cancel your refund request, please use it before the bank processes it on the same day.
Currently only support Taishin Bank.

Name(* = Required) Type Usage
partner_key* String Authentication key for each individual partner.
rec_trade_id* String Identifier for the transaction being refunded.
refund_id String Refund identification code for refund action
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/transaction/refund/cancel
// Production URL: https://prod.tappaysdk.com/tpc/transaction/refund/cancel
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "rec_trade_id": String,
    "refund_id": String
}

Response

Name Type Usage
status Int Response code. 0 indicates success.
msg String Error message.
currency String The letter abbreviation for currency, following ISO 4217.
rec_trade_id String Unique identifier for this transaction generated by TapPay server.
result Array
NameTypeUsage
successbooleanRefund cancel success or fail
refund_idStringRefund identification code for refund action
amountIntRefunded amount
bank_result_codeString(40)Response code from the bank.
bank_result_msgString(300)Error message from the bank.

Cap Cancel API

This API can cancel capture request, please use it before the bank processes it.

Name(* = Required) Type Usage
partner_key* String Authentication key for each individual partner.
rec_trade_id* String Identifier for the transaction being capture.
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/transaction/cap/cancel
// Production URL: https://prod.tappaysdk.com/tpc/transaction/cap/cancel
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "rec_trade_id": String
}

Response

Name Type Usage
status Int Response code. 0 indicates success.
msg String Error message.
currency String The letter abbreviation for currency, following ISO 4217.
rec_trade_id String Unique identifier for this transaction generated by TapPay server.

Card Metadata API

After enable TSP service, you will be able to call this API to get card detailed infomation(Ex: card face, type, issuer, Cobrand etc.)

Name Type(Max) Usage
partner_key String(64) Authentication key for each individual partner.
card_key String(64) A security key usd to encrypt the card token
card_token String(67) A permanent token that represents the customer’s card
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/card/metadata
// Production URL: https://prod.tappaysdk.com/tpc/card/metadata
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
  "partner_key": String,
  "card_key": String,
  "card_token": String
}

Response

Name Type Usage
status Int(5) Response code 0 indicates success.
*It will return 2011 (Card not found. Invalid token) when the card_key or card_token does not exist or be deleted.
msg String(100) Error message
*It will return 2011 (Card not found. Invalid token) when the card_key or card_token does not exist or be deleted.
card_info JSONObject Card information. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, 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
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 expiration date
token_statusStringToken Status: NOT_SUPPORT / REQUEST_PROCESSING / ACTIVE/ SUSPENDED/ DELETED
card_art_info JSONObject Card face infomation
NameTypeUsage
card_art_statusStringNOT_SUPPORT / REQUEST_PROCESSING / SUPPORT
is_real_card_faceBooleanDetermine it is a real card face or not.
A fake card face will be returned when:
1. The card type is not supported. Such as JCB, AE, and Union Pay.
2. The card type is Visa or MasterCard, but the issuing bank does not support it.
3. The card type is Visa or MasterCard, but the issuing bank does not provide real card faces to the International Credit Card Networks. (Rarely happened)
imageJson
NameTypeUsage
urlStringImage Url, start with “https://”
widthIntCard face width, unit : px
heightIntCard face height, unit : px
foreground_colorStringCard face text color
masked_card_numberStringMasked Credit card last four digits
(e.g. : **** **** **** **** 1234)
issuerStringThe card issuing bank displayed on the card face
(If Is_real_card_face is false, you can display issuer on the card face.)

Card Notify API

After enable TSP service, you will be informed the updated card information by this API every hour, which the card type has been changed (include Visa and MasterCard) during last hour

*User provide tsp_notify_url to TapPay, set the URL for the TSP card update notification.

Request Header

Key Value
Content-Type application/json

Request Url

Type Method : POST
Sandbox https://{tsp_notify_url}
Production https://{tsp_notify_url}

Request Body

Name Type Content
status Int Response code 0 indicates success.
msg String Error message.
card_token Array All the card tokens which are saved in TapPay server and related to the same credit card. (card token could be got from Pay by Prime API, remember: true or Bind Card API.)
card_info JSONObject Card information. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, 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
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 expiration date
token_statusStringToken Status: ACTIVE/ SUSPENDED/ DELETED
card_art_info JSONObject Card face infomation
NameTypeUsage
card_art_statusStringNOT_SUPPORT / SUPPORT
is_real_card_faceBooleanDetermine it is a real card face or not.
A fake card face will be returned when:
1. The card type is not supported. Such as JCB, AE and Union Pay.
2. The card type is Visa or MasterCard, but the issuing bank does not support it.
3. The card type is Visa or MasterCard, but the issuing bank does not provide real card faces to the International Credit Card Networks. (Rarely happened)
imageJson
NameTypeUsage
urlStringImage Url, start with “https://”
widthIntCard face width, unit : px
heightIntCard face height, unit : px
foreground_colorStringCard face text color
masked_card_numberStringMasked Credit card last four digits
(e.g. : **** **** **** **** 1234)
issuerStringThe card issuing bank displayed on the card face
(If Is_real_card_face is false, you can display issuer on the card face.)
{
    // Example
    {
    "status" : Int,
    "msg" : String,
    "card_token" : [String, String],
    "card_info" : {
        "bin_code" : String, 
        "last_four" : String,
        "issuer" : String,
        "funding" : Int,
        "type" : Int,
        "level" : String,
        "country" : String,
        "country_code" : String,
        "expiry_date" : String,
        "token_status" : String,
    },
    "card_art_info": {
        "card_art_status": String,
        "is_real_card_face" : boolean,
        "image" : {
            "url" : String,
            "width" : Int,
            "height" : Int
        },
            "foreground_color" : String,
            "masked_card_number" : String,
            "issuer" : String 
        }
    }
}

Card Notify API Sandbox

After enable TSP service, you will be informed by Card Notify API through tsp_notify_url you set.(Please refer to Card Notify API for conditions)

The purpose of this API is to make sure you can get the notification correctly.

Merchant provide tsp_notify_url to TapPay, set the URL for the TSP card update notification.

Request Header

Name(* = required) Type(Max) Usage
partner_key* String(67) Authentication key for each individual partner.
card_key* String(64) Card authorization key.
This column is gotten from Pay by Prime
Please test card : 4242424181784242
card_token* String(67) Card token.
This column is gotten from Pay by Prime
Please test card : 4242424181784242
tsp_notify_url* String(500) Request to url when card status change.
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/sandbox/card/metadata/notify
// Header:
//   Content-Type: application/json​
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "card_key": String,
    "card_token": String,
    "tsp_notify_url": String
}

Request body to tsp_notify_url

Name Type Content
status Int Response code 0 indicates success.
msg String Error message.
card_token Array All the card tokens which are saved in TapPay server and related to the same credit card. (card token could be got from Pay by Prime API, remember: true or Bind Card API.)
card_info JSONObject Card information. Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, 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
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 expiration date
token_statusStringSUSPENDED
card_art_info JSONObject Card face infomation
NameTypeUsage
card_art_statusStringSUPPORT
is_real_card_faceBooleanDetermine it is a real card face or not.
imageJson
NameTypeUsage
urlStringImage Url, start with “https://”
widthIntCard face width, unit : px
heightIntCard face height, unit : px
foreground_colorStringCard face text color
masked_card_numberStringMasked Credit card last four digits
(e.g. : **** **** **** **** 1234)
issuerStringThe card issuing bank displayed on the card face
(If Is_real_card_face is false, you can display issuer on the card face.)

Get Member Card API

This API will return Member identifier.

Name(* = required) Type(Max) Usage
partner_key* String(67) Authentication key for each individual partner.
member_id* String(64) Member identifier when use bind card. Support: Direct Pay
// *** 格式 ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/direct-pay/get-member-card
// Production URL: https://prod.tappaysdk.com/tpc/direct-pay/get-member-card
// Header:
//   Content-Type: application/json​
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "member_id": String
}

Response

Name Type(Max) Usage
status int Response code. 0 indicates success.
msg String Error message.
member_id String(64) Member identifier when use bind card. Support: Direct Pay
cards JSONArray
NameType(Max)Content
card_tokenString(67)A permanent token that represents the customer’s card
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
card_identifierStringCard 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
expiry_dateStringCard expired date, Format : YYYYMM, (Apple Pay / Google Pay / LINE Pay / Samsung Pay will not return this parameter)

Get Barcode API

This API is responsible for helping merchants generate barcode data.

Name Type(Max) Usage
partner_key* String(67) Authentication key for each individual partner.
card_key* String(64) Card authorization key.
card_token* String(67) Card token.
barcode_length Int bar code length(Recommend 5-60 character)(Default : 15)
barcode_update_secs Int Update barcode seconds
(Default : 90s)(Upper limit : 86400s)
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/direct-pay/get-barcode
// Production URL: https://prod.tappaysdk.com/tpc/direct-pay/get-barcode
// Header:
//   Content-Type: application/json​
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "card_key": String,
    "card_token": String,
    "barcode_length": Int,
    "barcode_update_secs": Int
}

Response

Name Type(Max) Usage
status int Response code. 0 indicates success.
msg String Error message.
barcode String(5-60) Barcode composed of uppercase and lowercase English numbers.
barcode_update_secs Int Update barcode seconds.

Pay by Barcode API

This API allows merchants to pay by barcodes.

Name(* = required) Type(Max) Usage
barcode* String(5-60) Each transaction barcode.
partner_key* String(67) 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.
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
Please bring in values in this parameter if your acquiring bank is NewebPay or LINE Pay, or it will result in transactions failure.
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.
retry_mode String New transaction = 1, retry = 2,
Default New transaction = 1
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 String(3000) Please follow format, JSON String, Data will be encrypted and decrypted when other customization requirements.
merchantdise_details JSONObject Merchandise Details
NameTypeContent
no_rebate_amountintThe amount which could not used for rebate. (ex. cigarette)
branch_info JSONObject Branch Informaiton
NameTypeContent
branch_codeString(20)Branch Code
branch_nameString(20)Branch Name
pos_idString(8) Id number of branch’s POS
payment_method int(2) Payment Method:
0=Credit Card
5=Easy Wallet
Default:0
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/payment/pay-by-barcode
// Production URL: https://prod.tappaysdk.com/tpc/payment/pay-by-barcode
// Header:
//   Content-Type: application/json​
//   x-api-key: YourPartnerKey
{
    "barcode": String,
    "partner_key": String,
    "merchant_id": "merchantA",
    "amount": 100,
    "details":"TapPay Test",
    "currency": "TWD",
    "order_number": String,
    "bank_transaction_id": String,
    "delay_capture_in_days": Int
}

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.
merchant_id String(50) Involved merchant’s identifier as defined on Portal.
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, Plus Pay
auth_code String(6) Bank authorization code.
Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, Plus Pay
card_info JSONObject Card information.
Not Support: LINE Pay, JKOPAY, Easy Wallet, Atome, 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 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.
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 only matchs an unique 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
member_uidString(60)Member identifier. (Reply from third parties)
cardholder JSONObject
NameTypeContent
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
pay_info JSONObject Payment Information
Support: Easy Wallet
NameTypeContent
pointintHow much money was paid by point. The value will be 0 if the purchase doesn’t use this payment method.
credit_cardintHow much money was paid by credit card. The value will be 0 if the purchase doesn’t use this payment method.
balanceintHow much money was paid by balance. The value will be 0 if the purchase doesn’t use this payment method.
bank_accountintHow much money was paid by bank account. The value will be 0 if the purchase doesn’t use this payment method.
discountIntThe amount of the point discount, if there is no offset, it is 0
masked_credit_card_numberStringCredit card last four digits
e_invoice_carrier JSONObject Information of e-invoice carrier
NameTypeContent
typeint(3)Type of e-invoice carrier
0 = Mobile Barcode
1 = MOICA Barcode
-1 = Other Barcode
-2 = unused
numberString(100)E-invoice carrier’s number
donationBooleanDonation
donation_idString (50)Donation ID

Update Cardholder API

This API allows you to modify the cardholder information.
Once you update the cardholder information, TapPay will only keep the latest information.

Name Type(Max) Usage
partner_key* String(64) Authentication key for each individual partner.
card_token* String(67) Card token.
name String(40) Name
phone_number String(40) Cellphone number, could be starting with 09 or E. 164 format with the ’+’ sign(“+886923456789”)
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
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/card/update-cardholder
// Production URL: https://prod.tappaysdk.com/tpc/card/update-cardholder
// Header:
//   Content-Type: application/json​
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "card_key": String,
    "name": String,
    "phone_number": String,
    "email": String,
    "zip_code": String,
    "address": String,
    "national_id": String,
    "member_id": String,
}

Response

Name Type(Max) Usage
status int Response code. 0 indicates success.
msg String Error message.
card_token String(67) Card token.
update_millis Long Update time
cardholder JSONObject Latest information of the cardholder
NameType(Max)Usage
nameString(40)Name
phone_numberString(40)Cellphone number
emailString(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

Check Affiliate Code API

You can make sure if this card belongs to the affiliate code you set.

Name(* = required.) Type(Max) Usage
partner_key* String(64) Authentication key for each individual partner
affiliate_code_group_name String(50) Affiliate code group
affiliate_code_name* String(20) Affiliate code
card_token String(67) Card token
Must be used with card_key, but cannot be used with prime at the same time
card_key String(64) Card key
Must be used with card_token, but cannot be used with prime at the same time
prime String(67) The one time token returned from getPrime
Cannot be used with card_token /card_key at the same time
// *** Format ***
// Sandbox URL: https://sandbox.tappaysdk.com/tpc/affiliate-code/check
// Production URL: https://prod.tappaysdk.com/tpc/affiliate-code/check
// Header:
//   Content-Type: application/json
//   x-api-key: YourPartnerKey
{
    "partner_key": String,
    "affiliate_code_group_name": String,
    "affiliate_code_name": String,

    // First choice
    "card_token": String,
    "card_key": String,

    // Second choice
    "prime": String,
}

Response

Names Type(Max) Usage
status Int Response code. 0 indicates success.
msg String Error message.
result_code String Whether it meets the query conditions
0 indicates success. 1 indicates fail.