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

• This API allows you to immediately exchange the temporary prime token with a permanent card key and card token.
  
• This process will perform a 1 dollar pre-authorization followed by an immediate refund. However, the 1 dollar pre-authorization won’t be sent to the bank while binding Easy Wallet, the customer won’t be debited.
• Before canceling binding, one bank_member_id can only bind with one payment method of Easy Wallet or it may cause binding error.
• This API support Direct Pay, LINE Pay, Easy Wallet.
• During peak hour, banks might take longer to process the transaction. To ensure your information is correct, please set your timeout to 30 seconds.
  
• You can deal with recurring transaction with Bind Card API as well. Just save the card_key and card_token you get in the Bind Card API response and call Pay by Card Token API on every fixed date or period with fixed amount that you set in your system.

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. 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, 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.
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 Usage phone_number* String Cellphone number, could be starting with 09 or E. 164 format with the ’+’ sign(“+886923456789”) name* String Name email* String E-mail address zip_code String Zip code number address String Billing address national_id String 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 bank_member_id String(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 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

// *** 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. Name Type(Max) Content card_token String(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_key String(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 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)
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. 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.

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

• This API allows you to get the capturing and refunding result between TapPay and the banks.
• To know the latest reconciliation result, please search the information after 13:00pm.
• This API only support to get the data of transaction after 2020/10/16.
• Please notice that the number of days between start_time_millis and end_time_millis can’t be longer than 31 days.

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. Name Type Content merchant_id String Involved merchant’s identifier as defined on Portal. merchant_description String TapPay merchant reference in Merchant of TapPay Portal. acquirer String Acquirer bank’s in Chinese, eg. 玉山銀行 payment_method String Payment Method Name Content direct_pay Direct Pay apple_pay Apple Pay google_pay_token Google Pay Token Card google_pay_fpan Google Pay Real PAN samsung_pay Samsung Pay line_pay LINE Pay tsp_token TSP Token jko_pay JKOPAY easy_wallet Easy Wallet atome Atome pi_wallet Pi Wallet plus_pay Plus Pay rec_trade_id String Record identifier. bank_transaction_id String A self-defined unique identifier for the bank. 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. 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. order_number String A self-defined identifier for each transaction, for TapPay to identify transaction. millis long Trigger status time bank_transaction_millis long The practical time that TapPay send the transaction to bank to process authorization, capturing, refund and canceling refund the payment. transaction_action String Transaction Action Capturing: CAPTURE Refund: REFUND transaction_result Boolean Whether the status is successful. trade_amount int The amount of capturing and refunding. auth_millis long The time that merchant call TapPay API for authorization. auth_amount int Amount while authorization. currency String The transaction currency. partial_card_number String First six digits of the card and last four digits of the card card_type int Card type -1 = Unknown 1 = VISA 2 = MasterCard 3 = JCB 4 = Union Pay 5 = AMEX auth_code String Authorization code from the bank. is_kyc_verified Boolean Whether to do KYC or not. instalment_info JSONObject When use instalment 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 Number of instalments redeem_info JSONObject When use redeem will return. Not Support: Apple Pay, Google Pay, Samsung Pay, LINE Pay, JKOPAY, Easy Wallet, Atome, Pi Wallet, Plus Pay. Name Type Content offset_amount String credit 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 credit_card int The amount of the point discount, if there is no offset, it is 0 balance int The amount of the coupon discount, if there is no offset, it is 0 bank_account int Use credit card to pay the amount. If this payment method is not used, it will be displayed as 0 point int Use the wallet stored-value account to pay the amount. If this payment method is not used, it will be displayed as 0 discount int Use 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	Name Type Usage success boolean Refund cancel success or fail refund_id String Refund identification code for refund action amount Int Refunded amount bank_result_code String(40) Response code from the bank. bank_result_msg String(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 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 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 expiration date token_status String Token Status: NOT_SUPPORT / REQUEST_PROCESSING / ACTIVE/ SUSPENDED/ DELETED
card_art_info	JSONObject	Card face infomation Name Type Usage card_art_status String NOT_SUPPORT / REQUEST_PROCESSING / SUPPORT is_real_card_face Boolean Determine 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) image Json Name Type Usage url String Image Url, start with “https://” width Int Card face width, unit : px height Int Card face height, unit : px foreground_color String Card face text color masked_card_number String Masked Credit card last four digits (e.g. : **** **** **** **** 1234) issuer String The 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 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 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 expiration date token_status String Token Status: ACTIVE/ SUSPENDED/ DELETED
card_art_info	JSONObject	Card face infomation Name Type Usage card_art_status String NOT_SUPPORT / SUPPORT is_real_card_face Boolean Determine 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) image Json Name Type Usage url String Image Url, start with “https://” width Int Card face width, unit : px height Int Card face height, unit : px foreground_color String Card face text color masked_card_number String Masked Credit card last four digits (e.g. : **** **** **** **** 1234) issuer String The 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 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 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 expiration date token_status String SUSPENDED
card_art_info	JSONObject	Card face infomation Name Type Usage card_art_status String SUPPORT is_real_card_face Boolean Determine it is a real card face or not. image Json Name Type Usage url String Image Url, start with “https://” width Int Card face width, unit : px height Int Card face height, unit : px foreground_color String Card face text color masked_card_number String Masked Credit card last four digits (e.g. : **** **** **** **** 1234) issuer String The 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	Name Type(Max) Content card_token String(67) A permanent token that represents the customer’s card 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 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 expiry_date String Card 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 Name Type Content no_rebate_amount int The amount of non-applicable rebate (for example: cigarette)
branch_info	JSONObject	Branch Informaiton Name Type Content branch_code String(20) Branch Code branch_name String(20) Branch Name pos_id String(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 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 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 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 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 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 member_uid String(60) Member identifier. (Reply from third parties)
cardholder	JSONObject	Name Type Content 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
pay_info	JSONObject	Payment Information Support: Easy Wallet Name Type Content point int How much money was paid by point. The value will be 0 if the purchase doesn’t use this payment method. credit_card int How much money was paid by credit card. The value will be 0 if the purchase doesn’t use this payment method. balance int How much money was paid by balance. The value will be 0 if the purchase doesn’t use this payment method. bank_account int How much money was paid by bank account. The value will be 0 if the purchase doesn’t use this payment method. discount Int The amount of the point discount, if there is no offset, it is 0 masked_credit_card_number String Credit card last four digits
e_invoice_carrier	JSONObject	Information of e-invoice carrier Name Type Content type int(3) Type of e-invoice carrier 0 = Mobile Barcode 1 = MOICA Barcode -1 = Other Barcode -2 = unused number String(100) E-invoice carrier’s number donation Boolean Donation donation_id String (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 Name Type(Max) Usage name String(40) Name phone_number String(40) Cellphone number 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

Check Affiliate Code API

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

• If you want to know whether this bincode belongs to affiliate code under the affiliate code group you set, please bring us the parameter affiliate_code_group_name as well.

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.

Push Token API

• You should enable TSP service first and file application to TapPay Support to activate Token Push service.
• To onboard Token Push service, you should register for MDES Token Connect Platform and complete all test cases.
• This API is aiming at binding a card to your app by selecting a Mastercard card from the issuer app, and you will get Card Key, Card Token in the response.

Name(* = Required)	Type	Usage
partner_key*	String(64)	Authentication key for each individual partner.
tsp_push_token*	String(1000)	When opening the app, we will send the value of tspPushToken to the app.

// *** Format ***
// Production URL: https://prod.tappaysdk.com/tpc/tsp/token/push-tokenize
// Header:
//   Content-Type: application/json
//   x-api-key: axgLG8z7vVa8mgIzdU1233rjBFAEmTti19NZd1pI
{
    "partner_key": "axgLG8z7vVa8mgIzdU1233rjBFAEmTti19NZd1pI",
    "tsp_push_token": "eyJxcyI6ImFjY291bnRIb2xkZXJEYXRhU3VwcGxpZWQ9dHJ1ZSZjYWxsYmFja1VSTD1odHRwczovL3Rva2VuY29ubmVjdC5tY3NyY3Rlc3RzdG9yZS5jb20vdG9rZW5pemF0aW9uLXJlc3VsdHMmY29tcGxldGVJc3N1ZXJBcHBBY3RpdmF0aW9uPXRydWUmY29tcGxldGVXZWJzaXRlQWN0aXZhdGlvbj10cnVlJmxvY2FsZT1lbl9VUyZwdXNoQWNjb3VudFJlY2VpcHRzPU1DQy1TVEwtQjI5MDZCNzgtOThGNS00QzVCLUIyNTUtMTQxNjM3QzI0QzZGIiwiY2FyZEJyYW5kIjoiTTRNIiwiY2xpZW50SXAiOiIyMTEuNzIuMTExLjE2MCIsInR4SWQiOiJjZjhmMGFmNzQ5ZDU0MmE2YmY0YzEwMjkwYmE1MGZiOSJ9"
}

Response

Name	Type	Usage
status	Int	Response code. 0 indicates success.
msg	String(30)	Error message.
token_status	String(20)	Token Status: ACTIVE
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. Name Type(Max) Content card_token String(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_key String(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 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)
cardholder	JSONObject	Information of the cardholder, you will receive “” if no data. Name Type(Max) Usage name String(40) Name phone_number String(40) Cellphone number email String(40) E-mail address zip_code String(40) Zip code number address String(90) Billing address
card_network_status	String(100)	Error status from International Credit Card Organization.
card_network_msg	String(100)	Error message from International Credit Card Organization.
callback_url	String(400)	Back to the bank url. (optional)

// *** Format ***
// Production URL:https://prod.tappaysdk.com/tpc/tsp/token/push-tokenize
// Header:
//   Content-Type: application/json​
{
    "status": 0,
    "msg": "Success",
    "card_network_status": "",
    "card_network_msg": "",
    "token_status": "ACTIVE",
    "card_secret": {
        "card_token": "da572568e1695f1336b0d9ae889621ee4fd449ba5215a6b4540a5534e1b6540a",
        "card_key": "cb5277a884a07d7ef0fbdaef1ecc01ca4660b60ae28b3e47ac21c90fa530d91e"
    },
    "card_info": {
        "issuer": "CTBC Bank",
        "funding": 0,
        "type": 2,
        "level": "",
        "country": "UNITED STATES",
        "last_four": "4768",
        "bin_code": "520473",
        "issuer_zh_tw": "",
        "bank_id": "822",
        "country_code": "US",
        "expiry_date": "202303"
    },
    "cardholder": {
        "name": "John Doe",
        "email": "John.doe@mailinator.com",
        "address": "10 Sunflower Avenue, Apt. 4B, St. Louis, MO, 61000, USA",
        "phone_number": "+11234567890",
        "zip_code": "61000"
    },
    "callback_url": "https://tokenconnect.mcsrcteststore.com/tokenization-results?results%5BMCC-STL-B2906B78-98F5-4C5B-B255-141637C24C6F%5D=APPROVED%7CDM4MMC000014413677d8fef0baff4e83b4b48c096ab526c4"
}