Integration Guide

Revision History
Version

Date

Content

1.0.0

2023.01.10

First Draft

1.0.1

2023.05.12

Add Error Code describe

1.0.2

2023.06.12

Change payment API additional cardholder
parameter logic

2

Table of Contents
Introduction

4

Process diagram

5

Direct Pay

5Apple Pay

5

Google Pay

6APIs Overview

7

APIs Speci cation

11

Pay by Prime API

11

Pay by Card Token API

18

Bind Card API

24

Frontend Redirect

28

Backend Notify

29

Refund API

31

Record API

32

Cap Today API

37

Cap Cancel API

38

Remove Card API

39

Trade History API

40

Card Metadata API

42

Card Notify API

45

Card Notify API Sandbox

47

Get Member Card API

48

Update Cardholder API

50

Check A liate Code API

52

Push Token API

53

Reconciliation API

55

Create A liate Code API

58

Delete A liate Code API

59

Create A liate Code Group API

60

Delete A liate Code Group API

61

Backend API Error Code

62

fi

ffi

ffi

ffi

ffi

ffi

3

Introduction
Welcome to TapPay!
TapPay support payment methods including Direct Pay (credit card), Apple
Pay, Google Pay. If you have any question or suggestion during thedevelopment process, please email to Info.jp@cherricorp.com. Wish you
have great development journey.
Note.
Before testing, you can integrate TapPay with a few easy steps:
1. Register an account and log in TapPay Portal.
2. Go to "Developer" which is on the top bar.
1. Select "Application". You may view your app ID, app key, and bundle
name here.
2. Select "System settings". Please bind your server’s IP address to ourserver.
3. Select "Frontend SDK" to check which type of SDK you want tointegrate in your frontend which will be used for "Get Prime".

4

Process diagram
Direct Pay

Apple Pay

5

Google Pay

6

APIs Overview
This document is intended for server/web developers with thoroughunderstanding of HTTP communications and RESTful API.
API

Description

Pay by Prime API• This API allows you to pay using the prime token obtained from yourFrontend.

• The prime may only be used once, so you need to create a new token(Get Prime) everytime before you call this API.（Time limit of prime is
90 seconds.）• If the parameter "remember" is set as true, you will get the card_key
and card_token in the Pay by Prime API response. You can directly
use them to call Pay by Card Token API, so that you can pass the stepof "Get Prime". After saving card_key and card_token, you can call
Pay by Card Token API to handle recurring transaction on every xed
date or period with xed amount that you set in your system. Thisfeature doesn’t support Apple Pay and Google Pay.
• Since the acquirer bank may take time during peak hours, please set
the timeout to 30 seconds in your server to avoid out-of-synctransaction information.

• This API allows you to pay using a permanent card key and card

Pay by Card Token API

token, thus allowing you to skip create a new token (Get Prime) andPay by Prime API.
• If the parameter “remember” is set as true, you will get the card_key
and card_token in Pay by Prime API or Bind Card API response. You
can directly use them to call Pay by Card Token API, so that you canpass the step of "Get Prime". After saving card_key and card_token,
you can call Pay by Card Token API to handle recurring transaction on
every xed date or period with xed amount that you set in yoursystem. This feature doesn’t support Apple Pay and Google Pay.
• Since the acquirer bank may take time during peak hours, please set
the timeout to 30 seconds in your server to avoid out-of-synctransaction information.

• This API allows you to pay using the prime token obtained from yourBind Card API

Frontend.

• The prime may only be used once, so you need to create a new token(Get Prime) every time before you call this API.（Time limit of prime is
90 seconds.）• This process will perform a 1 dollar pre-authorization followed by an
immediate refund.
• You will get the card_key and card_token in Bind Card API response.
You can directly use them to call Pay by Card Token API, so that you
can pass the step of "Get Prime". After saving card_key andcard_token, you can call Pay by Card Token API to handle recurringtransaction on every xed date or period with xed amount that you
set in your system. This feature doesn’t support Apple Pay and
Google Pay.
• Since the acquirer bank may take time during peak hours, please set
the timeout to 30 seconds in your server to avoid out-of-synctransaction information.

fi

fi

fi

fi

fi

fi

7

API

Description

Frontend Redirect API• After 3DS transaction completed, TapPay will redirect to the locationof the request parameter result_url > frontend_redirect_url you set in
the Pay by Prime/Pay by Card Token/Bind Card API request, andappend query string.

Backend Notify API• After 3DS transaction completed, TapPay will POST to the location of

the request parameter result_url > backend_notify_url you set in the
Pay by Prime/Pay by Card Token/Bind Card API with transaction
result.
• When you receive the POST request from TapPay successfully, please
return TapPay HttpStatusCode 2xx; otherwise, TapPay would resend it
again every 1, 2, 4, 8,16 minutes. It will be resent ve times at most,and if all fails, a noti cation letter will be sent to the contact person’s
and technical email mailbox. Please follow the instructions to checkthe latest status of the order to avoid inconsistent transaction status.

• This API allows you to refund your transaction, reversing both the

Refund API

capture action as well as the authorization action. If partial refund isrequired, then this API is also needed.
• During peak hour, banks might take longer to process the transaction.
To ensure your information is correct, please set your timeout to 30
seconds.
• When you call Refund API, TapPay will send the refund request to thebanks on the same day. To con rm whether the captured is succeed,
we suggest you check the transaction status on TapPay Portal or call
Record API to double con rm the transaction status on the next day.
• To make sure the consistence of the transaction result between
acquiring banks and TapPay. It’s not allowed to call Refund API duringcapping time of acquiring banks.

• This API allows you to get the trade records.

Record API• This API allows you to put the payment into the capture schedule

Cap Today API

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 modi ed when calling our payment APIs. However,should you change your mind in between, you may call this API to put
the payment into the capture schedule today.
• When you call Cap Today API, TapPay will send the capture request to
the banks on the same day. To con rm whether the captured is
succeed, we suggest you check the transaction status on TapPay
Portal or call Record API to double con rm the transaction status on
the next day.
• During peak hour, banks might take longer to process the transaction.
To ensure your information is correct, please set your timeout to 30
seconds.

• This API can remove the speci c payment be remove out in the

Cap Cancel API

capture schedule today, please use it before the bank processes it.

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

Remove Card API

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.

• This API allows you to get the speci c payment trade history.

Trade History API

fi

fi

fi

fi

fi

fi

fi

fi

fi

8

API

Description

Card Metadata API• After enable TSP service, you will be able to call this API to get card
detailed infomation(e.x. card face, type, issuer, Cobrand etc.)* To enable TSP service, please contact TapPay sales.

• After enable TSP service, you will be informed the updated card

Card Notify API

information by this API every hour, which the card type has beenchanged (include Visa and MasterCard) during last hour.
• User provide tsp_notify_url to TapPay, set the URL for the TSP card
update noti cation.
* To enable TSP service, please contact TapPay sales.
* Only available in Prod environment.
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 noti cation
correctly. Merchant provide tsp_notify_url to TapPay, set the URL for
the TSP card update noti cation.
* Only available in Sandbox environment.
Get Member Card API• For returning the cards info which had bound under each member 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.

Check A liate Code API• You can make sure if this card belongs to the a liate code you set.
• If you want to know whether this bincode belongs to a liate code
under the a liate code group you set, please bring the parametera liate_code_group_name as well.

• You should enable TSP service rst and le application to TapPay

Push Token API

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.
* This service has regional restrictions, please contact TapPay
sales.

• This API allows you to get the capturing and refunding result between

Reconciliation API

TapPay and the banks.

• To know the latest reconciliation result, please search the information
after 14: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.

Create A liate Code API

You can do the following things via this API• Create a new a liate code, and add fpan_bincodes or
token_bincodes to it.
• Add the fpan_bincodes or token_bincodes you need to the speci ca liate code.
• Need at least one bincode (fpan_bincodes or token_bincodes) whenusing this API.
• If you want to modify the fpan_bincode or token_bincode undera liate code, please add the needed one via Create A liate CodeAPI, then use Delete A liate Code API to remove the one you don’t
need.

fi

fi

ffi

ffi

ffi

fi

fi

fi

ffi

ffi

fi

ffi

ffi

ffi

ffi

ffi

ffi

9

API

Description

Delete A liate Code API

You can do the following things via this API• Delete fpan_bincodes or token_bincodes under the speci c a liate
code.
• Delete a liate code.

Create A liate Code GroupAPI

You can do the following things via this API• Create a new a liate code group, and add a liate codes to it.
• Add the fpan_bincodes / token_bincodes you need to the speci ca liate code.
• If you want to modify a liate codes under a liate code group, please
add the needed one via Create A liate Code Group API, then use
Delete A liate Code Group API to remove the one you don’t need.

Delete A liate Code GroupAPI

You can do the following things via this API• Delete a liate codes under the speci c a liate code group.
• Delete a liate code group.

fi

ffi

fi

ffi

ffi

ffi

fi

ffi

ffi

ffi

ffi

ffi

ffi

ffi

ffi

ffi

ffi

ffi

10

APIs Speci cation
The detailed speci cation of TapPay backend API is as follows:

Pay by Prime API

fi

fi

11

Pay by prime - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/payment/pay-by-prime
Production：https://prod.tappaysdk.com/tpc/payment/pay-by-prime
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

prime

Y

String(67)One time token returned from getPrime by
TapPay SDK.
The prime will be expired after 90 seconds.
If using Apple Pay Deferred Payments, pleasekeep prime by yourself.(The duration of eachprime is set up for 30 days as default.)
It will be used by calling Pay By Prime API or
Bind Card API.
You can use these prime for test in Sandbox
environment.
Direct Pay =test_3a2fb2b7e892b914a03c95dd4dd5dc797
0c908df67a49527c0a648b2bc9
Apple Pay(amount should be set to 12) =ap_test_utigjeyfutj5867uyjhuty47rythfjru48576
8tigjfheufhtu5i6ojk
Google Pay(Tokenize) =gp_test_utigjeyfutj5867uyjhuty47rythfjru48576
8tigjfheufhtu5i6ojk
Google Pay(Real Card) =gp_test_kjo6i5uthfuehfjgit867584urjfhtyr74ytu
hjyu7685jtufyejgitu

partner_key

YString(64)Authentication key for each individual partner.

merchant_id

YString(50)Involved merchant’s identi er as de ned on
Portal.

merchant_group_id

N

String(50)The merchant management settings set on
the portal, transactions will be performed
according to the portal’s payment
con guration during the transaction.
* Cannot be used with merchant_id at thesame time.

fi

fi

fi

12

Item

RequiredType

Description

amountY

int

Transaction price.
TapPay currently only supports Taiwan Dollar,
Japanese Yen, Hong Kong Dollar, Malaysian
Ringgit, and US Dollar.
Except for TWD and JPY, transaction priceshould times 100. For instance, if transaction
price is HKD1, please ll in 100 in thisparameter.
TWD：Lower limit of each transaction is NTD
1, upper limit of each transaction is NTD
20,000,000.
Please ll in 1 when the transaction is TWD 1.
JPY：Lower limit of each transaction is JPY
1, upper limit of each transaction is JPY
1,300,000.
Please ll in 1 when the transaction is JPY 1.
HKD：Lower limit of each transaction is HKD
0.01, upper limit of each transaction is HKD
252,500. Please ll in 101 when thetransaction is HKD 1.01
MYR：Lower limit of each transaction is MYR
0.01, upper limit of each transaction is MYR
135,000. Please ll in 101 when thetransaction is MYR 1.01
USD: Lower limit of each transaction is USD
0.01, upper limit of each transaction is USD
33,169. Please ll in 101 when the transaction
is USD 1.01

currency

N

String(3)The letter abbreviation for currency, following
ISO 4217.
* Default value is TWD

order_number

N

String(50)A merchant self-de ned identi er for eachtransaction in TapPay. This parameter is
optional, but once use this parameter, thevalue can not be empty.

bank_transaction_id

NString(40)Transaction identi er for the bank.
You may customize one here if you wish, but
it must be unique, if not, then TapPay will
generate a random one.
* We strongly recommend you to de ne
the unique bank_transaction_id by yourself
to prevent when a 421 error occurs, thetransaction cannot be checked back.

detailsY

String(100)Details of the transaction. You should include
as much information as possible. It will help
our fraud detector in distinguishing real andfake transaction.

cardholder

Y

JSONObject

The card owner information

fi

fi

fi

fi

fi

fi

fi

fi

fi

fi

13

RequiredType

cardholder.phone_number

Y

String(40)Cellphone number* It is recommended to ll in the same
number that the cardholder apply thecredit card in the issuing bank.

cardholder.name

Y

String(40)Namecardholder.email

Y

String(140)E-mail address

cardholder.zip_code

N

String(40)Zip code number

cardholder.address

N

String(90)Billing address

cardholder.national_id

N

String(40)National ID

cardholder.member_id

NString(64)Member ID customized by merchant* Only available in Direct Pay

cardholder.city

N

String(500)City

cardholder.country_code

N

String(2)Country Code (ISO 3166-1 AlphabeticalCode)delay_capture_in_daysNint

The number of days between the time bankauthorizes the payment and the time bankactually 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 con rm with your acquiring bankbefore 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

N

BooleanWhether to use this parameter or not, default
value is false.

result_url

N

JSONObject

Required when three_domain_secure = true

result_url.frontend_redirec
t_url

N

String(500)The frontend website URL of the merchantwhere the customer will be brought to afternishing transaction process on 3Dveri cation. This URL must start with https.

result_url.backend_notify_urlNString(500)

The backend URL of the merchant server toreceive the transaction result. Must start withhttps, only suport 443 port.

rememberN

BooleanTo save the card number or not.
* Only available in Direct Pay

additional_data

N

String(3000)

fi

fi

14

fi

fi

Item

Description

Data will be encrypted and decrypted whenother customization requirements.

Pay by prime - Response
Item

Type

Description

statusint

msg

Stringrec_trade_id

String(20)Unique identi er for this transaction generated
by TapPay.

bank_transaction_id

String(40)Transaction identi er for the bank.
You may customize one here if you wish, but it
must be unique, if not, then TapPay will
generate a random one.
* We strongly recommend you to de ne theunique bank_transaction_id by yourself toprevent when a 421 error occurs, thetransaction cannot be checked back.

auth_code

String(6)Bank authorization code.

card_secret

JSONObject

Contains the card key and token.
* Only available in Direct Pay

card_secret.card_token

String(67)Card token. It will be used when calling Pay by
Card Token API.

card_secret.card_key

String(64)Card authorization key. It will be used whencalling Pay by Card Token API.It will be used
when calling Pay by Card Token API.

amountint

currency

String(3)card_info

JSONObject

Credit card information

card_info.bin_code

String(6)First six digits of the card

card_info.last_four

String(4)Last four digits of the card

card_info.issuer

StringCard issuer

card_info.issuer_zh_tw

StringIssuer chinese name* If the issuing bank is not in Taiwan, thisvalue will be an empty

card_info.bank_id

StringBank identi er* If the issuing bank is not in Taiwan, thisvalue will be an empty

card_info.funding

int

Result identi er. 0 indicates success.
Result message.

Transaction price.
The letter abbreviation for currency, following
ISO 4217.

Card usage-1 = Unknown
0 = Credit Card
1 = Debit Card
2 = Prepaid Card

fi

fi

fi

fi

fi

15

Item

Type

Description

card_info.type

int

card_info.level

StringCard level

card_info.country

StringCountry of card issuer

card_info.country_code

StringCountry code of card issuer

card_info.expiry_date

StringCard expired date, Format : YYYYMM
When request param of remember equals true
will return.
* Only available in Direct Payorder_number

String(50)A merchant self-de ned identi er for eachtransaction in TapPay.

merchant_id

String(50)Involved merchant’s identi er as de ned on
Portal.

acquirer

StringAcquiring banks or payment processors.

transaction_time_millis

longTime of transaction.

bank_transaction_time

JSONObject

bank_transaction_time.start_time_millisStringStart time.

bank_transaction_time.end_time_millisString

End time.

bank_result_code

String(40)Response code from the bank.

bank_result_msg

String(300)

Response message from the bank.

payment_url

StringPayment redirect url, please send it tofrontend.

card_identi er

StringCard identi er.
Each credit card will only have one card
identi er.

merchant_reference_info

JSONObject

merchant_reference_info.a liate_codesArray

Card type-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
5 = AMEX

fi

ffi

fi

fi

ffi

fi

fi

fi

Merchant reference information
This parameter will be returned when themerchant uses the feature of A liate Code in
TapPay Portal and the transaction match thesetting.

16

fiTime when the bank handles the transaction.

Item

Type

Description

is_rba_veri ed

Boolean

It is used to judge whether the transaction has
passed the Cherri X transaction risk
assessment.
* Cherri X transaction risk assessment canevaluate the risk for each transaction to
identify and prevent counterfeit transaction.
For more information, please contact oursales.

transaction_method_details

JSONObject

Transaction method details.

transaction_method_details.tran
saction_method

String

THREE_DOMAIN_SECURE: Means thetransaction was sent to the bank with 3D
secure.
FRICTIONLESS: Means the transaction was
sent to the bank with frictionless.

transaction_method_details.tran
saction_method_reference

String

RBA: Means the transaction method was
decided by RBA rule setting.
REQUEST: Means the transaction method was
decided by the request speci cation that themerchant set in the payment request.
* Cherri X transaction risk assessment canevaluate the risk for each transaction to
identify and prevent counterfeit transaction.
For more information, please contact oursales.

fi

fi

17

Pay by Card Token API

Pay by card token - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/payment/pay-by-token
Production：https://prod.tappaysdk.com/tpc/payment/pay-by-token
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

card_key

Y

String(64)Card key from Pay by Prime API or Bind Card
API response when remember equals true

card_token

Y

String(67)Card token from Pay by Prime API or Bind Card
API response when remember equals true

partner_key

YString(64)Authentication key for each individual partner.

merchant_id

YString(50)Involved merchant’s identi er as de ned on
Portal.

merchant_group_id

N

String(50)The merchant management settings set on the
portal, transactions will be performed according
to the portal’s payment con guration during thetransaction.
* Cannot be used with merchant_id at thesame time.

fi

fi

fi

18

Item

RequiredType

Description

amountY

int

Transaction price.
TapPay currently only supports Taiwan Dollar,
Japanese Yen, Hong Kong Dollar, Malaysian
Ringgit, and US Dollar.
Except TWD and JPY, transaction price should
times 100. For instance, if transaction price is
HKD1, please ll in 100 in this parameter.
TWD：Lower limit of each transaction is NTD 1,
upper limit of each transaction is NTD
20,000,000.
Please ll in 1 when the transaction is TWD 1.
JPY：Lower limit of each transaction is JPY 1,
upper limit of each transaction is JPY 1,300,000.
Please ll in 1 when the transaction is JPY 1.
HKD：Lower limit of each transaction is HKD
0.01, upper limit of each transaction is HKD
252,500. Please ll in 101 when the transaction is
HKD 1.01
MYR：Lower limit of each transaction is MYR
0.01, upper limit of each transaction is MYR
135,000. Please ll in 101 when the transaction is
MYR 1.01
USD: Lower limit of each transaction is USD
0.01, upper limit of each transaction is USD
33,169. Please ll in 101 when the transaction is
USD 1.01

currency

N

String(3)The letter abbreviation for currency, following ISO
4217.
* Default value is TWD

order_number

N

String(50)A merchant self-de ned identi er for eachtransaction in TapPay. This parameter is optional,
but once use this parameter, the value can not be
empty.

bank_transaction_id

NString(40)Transaction identi er for the bank.
You may customize one here if you wish, but it
must be unique, if not, then TapPay will generate
a random one.
* We strongly recommend you to de ne theunique bank_transaction_id by yourself toprevent when a 421 error occurs, thetransaction cannot be checked back.

detailsY

String(100)Details of the transaction. You should include as
much information as possible. It will help our
fraud detector in distinguishing real and faketransaction.

fi

fi

fi

fi

fi

fi

fi

fi

fi

fi

19

Item

RequiredType

Description

delay_capture_in_daysNint

The number of days between the time bankauthorizes the payment and the time bankactually 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 con rm with your acquiring bank before
deciding your capture period. Be aware that yourcaptures might be failed if you didn’t complete
the capture by the banks capture deadline.

three_domain_secure

N

Booleanresult_url

N

JSONObject Required when three_domain_secure = true

result_url.frontend_redirect_
urlN

String(500)The frontend website URL of the merchant where
the customer will be brought to after nishingtransaction process on 3D veri cation. This URL
must start with https.

result_url.backend_notify_u
rl

NString(500)

The backend URL of the merchant server toreceive the transaction result. Must start withhttps, only suport 443 port.

card_ccv

N

String(4)Security code.
Cannot be used with ccv_prime at the sametime. 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. 2. Didn’t get ccv_prime from get-ccv-prime
but use the AE card for 3DS2.0 veri cationtransactions.
* Only available in Direct Pay

additional_data

Nccv_prime

N

StringThe 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.
You can use these ccv_prime for test in sandbox
environment
ccv_prime(3 digits):
test_65b1ca2d5d0dc8 5b62296ea8547bab0840
1f8a57015fb818c5bcd10433fa11
ccv_prime(4 digits):
test_cd1e737890874cdadf39caaf56c5b183c36a
4117ca89cb24fd674c0892e0fa92

device_id

N

String(64)ID of each device.
This parameter must be put into the request
body when you use the Cherri X transaction risk
assessment.
* The way to obtain device id is to use “Get
Device Id” function of TapPay SDK.

String(3000) Data will be encrypted and decrypted when othercustomization requirements.

fi

fi

fi

ff

20

fi

Whether to use this parameter or not, default
value is false.

Pay by card token - Response
Item

Type

Description

statusint

msg

Stringrec_trade_id

String(20)Unique identi er for this transaction generated
by TapPay.

bank_transaction_id

String(40)Transaction identi er for the bank.
You may customize one here if you wish, but it
must be unique, if not, then TapPay will generate
a random one.
* We strongly recommend you to de ne theunique bank_transaction_id by yourself toprevent when a 421 error occurs, thetransaction cannot be checked back.

auth_code

String(6)Bank authorization code.

amountint

currency

String(3)card_info

JSONObject

Credit card information

card_info.bin_code

String(6)First six digits of the card

card_info.last_four

String(4)Last four digits of the card

card_info.issuer

StringCard issuer

card_info.issuer_zh_tw

StringIssuer Chinese name* If the issuing bank is not in Taiwan, thisvalue will be an empty

card_info.bank_id

StringBank identi er* If the issuing bank is not in Taiwan, thisvalue will be an empty

card_info.funding

int

Card usage-1 = Unknown
0 = Credit Card
1 = Debit Card
2 = Prepaid Card

card_info.type

int

Card type-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
5 = AMEX

card_info.level

StringCard level

card_info.country

StringCountry of card issuer

card_info.country_code

StringCountry code of card issuer

Result identi er. 0 indicates success.
Result message.

Transaction price.
The letter abbreviation for currency, following
ISO 4217.

fi

fi

fi

fi

fi

21

Item

Type

Description

card_info.expiry_date

Stringorder_number

String(50)A merchant self-de ned identi er for eachtransaction in TapPay.

merchant_id

String(50)Involved merchant’s identi er as de ned on
Portal.

acquirer

StringAcquiring banks or payment processors.

transaction_time_millis

longTime of transaction.

bank_transaction_time

JSONObject

bank_transaction_time.start_time_millisStringStart time.

bank_transaction_time.end_time_millisString

End time.

bank_result_code

String(40)Response code from the bank.

bank_result_msg

String(300)

Response message from the bank.

payment_url

StringPayment redirect url, please send it to frontend.

card_identi er

StringCard identi er.
Each credit card will only have one card
identi er.

merchant_reference_info

JSONObject

merchant_reference_info.a liate_codesArray

This parameter will be returned when themerchant uses the feature of A liate Code in
TapPay Portal and the transaction match thesetting.

is_rba_veri ed

Boolean

It is used to judge whether the transaction has
passed the Cherri X transaction risk assessment.

Card expired date, Format : YYYYMM
When request param of remember equals true
will return.
* Only available in Direct Pay

Time when the bank handles the transaction.

Merchant reference information* Cherri X transaction risk assessment canevaluate the risk for each transaction to
identify and prevent counterfeit transaction.
For more information, please contact oursales.
transaction_method_details

JSONObject

transaction_method_details.tran
saction_method

StringTransaction method details.
THREE_DOMAIN_SECURE: Means thetransaction was sent to the bank with 3D secure.
FRICTIONLESS: Means the transaction was sent
to the bank with frictionless.

fi

ffi

fi

fi

ffi

fi

fi

fi

fi

fi

22

Item

Type

Description

transaction_method_details.tran
saction_method_reference

String

RBA: Means the transaction method was
decided by RBA rule setting.
REQUEST: Means the transaction method was
decided by the request speci cation that themerchant set in the payment request.
* Cherri X transaction risk assessment canevaluate the risk for each transaction to
identify and prevent counterfeit transaction.
For more information, please contact oursales.

fi23

Bind Card API
Bind Card - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/card/bind
Production：https://prod.tappaysdk.com/tpc/card/bind
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

prime

Y

String(67)One time token returned from getPrime by
TapPay SDK.
The prime will be expired after 90 seconds.
It will be used by calling Pay By Prime API or
Bind Card API.
You can use this prime for test in Sandbox
environment.
Direct Pay =test_3a2fb2b7e892b914a03c95dd4dd5dc7970c9
08df67a49527c0a648b2bc9

partner_key

YString(64)Authentication key for each individual partner.

merchant_id

YString(50)Involved merchant’s identi er as de ned on
Portal.

merchant_group_id

N

String(50)The merchant management settings set on the
portal, transactions will be performed according
to the portal’s payment con guration during thetransaction.
* Cannot be used with merchant_id at thesame time.

currency

N

String(3)The letter abbreviation for currency, following ISO
4217.
* Default value is TWD

cardholder

Y

JSONObject The card owner information

cardholder.phone_number

Y

String(40)Cellphone number* It is recommended to ll in the same
number that the cardholder apply the credit
card in the issuing bank.

cardholder.name

Y

String(40)Namecardholder.email

Y

String(140)E-mail address

cardholder.zip_code

N

String(40)Zip code number

cardholder.address

N

String(90)Billing address

fi

fi

fi

fi

24

Item

RequiredType

Description

cardholder.national_id

N

String(40)National ID

cardholder.member_id

NString(64)Member ID customized by merchant* Only available in Direct Pay

cardholder.city

N

String(500)City

cardholder.country_code

N

String(2)Country Code (ISO 3166-1 Alphabetical Code)three_domain_secure

N

BooleanWhether to use this parameter or not, default
value is false.

result_url

N

JSONObject Required when three_domain_secure = true

result_url.frontend_redirect_
urlN

String(500)The frontend website URL of the merchant where
the customer will be brought to after nishingtransaction process on 3D veri cation. This URL
must start with https.

result_url.backend_notify_u
rl

NString(500)

The backend URL of the merchant server toreceive the transaction result. Must start withhttps, only suport 443 port.

Bind Card - Response
Item

Type

Description

statusint

msg

Stringrec_trade_id

String(20)Unique identi er for this transaction generated
by TapPay.

order_id

String(40)Transaction identi er for the bank. Same asbank_transaction_id, but the name of theparameter in Bind Card API is order_id.

auth_code

String(6)Bank authorization code.

card_secret

JSONObject

Contains the card key and token.
* Only available in Direct Pay

card_secret.card_token

String(67)Card token. It will be used when calling Pay by
Card Token API.

card_secret.card_key

String(64)Card authorization key. It will be used whencalling Pay by Card Token API.It will be used
when calling Pay by Card Token API.

currency

String(3)The letter abbreviation for currency, following
ISO 4217.

card_info

JSONObject

Credit card information

card_info.bin_code

String(6)First six digits of the card

card_info.last_four

String(4)Last four digits of the card

Result identi er. 0 indicates success.
Result message.

fi

fi

fi

fi

fi

25

Item

Type

Description

card_info.issuer

StringCard issuer

card_info.issuer_zh_tw

StringIssuer chinese name* If the issuing bank is not in Taiwan, thisvalue will be an empty

card_info.bank_id

StringBank identi er* If the issuing bank is not in Taiwan, thisvalue will be an empty

card_info.funding

int

Card usage-1 = Unknown
0 = Credit Card
1 = Debit Card
2 = Prepaid Card

card_info.type

int

Card type-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
5 = AMEX

card_info.level

StringCard level

card_info.country

StringCountry of card issuer

card_info.country_code

StringCountry code of card issuer

card_info.expiry_date

StringCard expired date, Format : YYYYMM
When request param of remember equals true
will return.
* Only available in Direct Payorder_number

String(50)A merchant self-de ned identi er for eachtransaction in TapPay.

merchant_id

String(50)Involved merchant’s identi er as de ned on
Portal.

acquirer

StringAcquiring banks or payment processors.

millislong

Time of transaction.

bank_transaction_time

JSONObject

bank_transaction_time.start_tim
e_millis

StringStart time.

bank_transaction_time.end_time_millisString

End time.

bank_result_code

String(40)Response code from the bank.

bank_result_msg

String(300)

Response message from the bank.

payment_url

StringPayment redirect url, please send it to frontend.

card_identi er

StringCard identi er.
Each credit card will only have one card
identi er.

Time when the bank handles the transaction.

fi

fi

fi

fi

fi

fi

fi

fi

26

Item

Type

Description

is_rba_veri ed

Boolean

It is used to judge whether the transaction has
passed the Cherri X transaction risk assessment.
* Cherri X transaction risk assessment canevaluate the risk for each transaction to
identify and prevent counterfeit transaction.
For more information, please contact oursales.

transaction_method_details

JSONObject

Transaction method details.

transaction_method_details.tran
saction_method

String

THREE_DOMAIN_SECURE: Means thetransaction was sent to the bank with 3D secure.
FRICTIONLESS: Means the transaction was sent
to the bank with frictionless.

transaction_method_details.tran
saction_method_reference

String

RBA: Means the transaction method was
decided by RBA rule setting.
REQUEST: Means the transaction method was
decided by the request speci cation that themerchant set in the payment request.
* Cherri X transaction risk assessment canevaluate the risk for each transaction to
identify and prevent counterfeit transaction.
For more information, please contact oursales.

fi

fi

27

Frontend Redirect
Frontend Redirect - Request
Request Header
Key: Content-Type
Value: html/text
Request Url
https://{your.domain.com/transaction_is_done}?
rec_trade_id=D20230109WsvKhn&order_number=CF46019917&status=0&b
ank_transaction_id=TP20230109WsvKhn

Request Query String
Item

Type

Description

rec_trade_id

String(20)Unique identi er for this transaction generated
by TapPay.

order_number

String(50)A merchant self-de ned identi er for eachtransaction in TapPay.

bank_transaction_id

String(40)Transaction identi er for the bank.
You may customize one here if you wish, but it
must be unique, if not, then TapPay will generate
a random one.
* We strongly recommend you to de ne theunique bank_transaction_id by yourself toprevent when a 421 error occurs, thetransaction cannot be checked back.

statusint

Result identi er. 0 indicates success.

fi

fi

fi

fi

fi

fi

28

Backend Notify
Backend Notify - Request
Request Header
Key: Content-Type
Value: application/json
Request Url
Post
https://{your_backend_notify_url}
Item

Type

Description

rec_trade_id

String(20)Unique identi er for this transaction generated
by TapPay.

auth_code

String(6)Bank authorization code.

order_number

String(50)A merchant self-de ned identi er for eachtransaction in TapPay.

bank_transaction_id

String(40)Transaction identi er for the bank.
You may customize one here if you wish, but it
must be unique, if not, then TapPay will generate
a random one.
* We strongly recommend you to de ne theunique bank_transaction_id by yourself toprevent when a 421 error occurs, thetransaction cannot be checked back.

fi

fi

fi

fi

fi

29

Item

Type

Description

amountint

Transaction price.
TapPay currently only supports Taiwan Dollar,
Japanese Yen, Hong Kong Dollar, Malaysian
Ringgit, and US Dollar.
Except TWD and JPY, transaction price should
times 100. For instance, if transaction price is
HKD1, please ll in 100 in this parameter.
TWD：Lower limit of each transaction is NTD 1,
upper limit of each transaction is NTD
20,000,000.
Please ll in 1 when the transaction is TWD 1.
JPY：Lower limit of each transaction is JPY 1,
upper limit of each transaction is JPY 1,300,000.
Please ll in 1 when the transaction is JPY 1.
HKD：Lower limit of each transaction is HKD
0.01, upper limit of each transaction is HKD
252,500. Please ll in 101 when the transaction
is HKD 1.01
MYR：Lower limit of each transaction is MYR
0.01, upper limit of each transaction is MYR
135,000. Please ll in 101 when the transaction
is MYR 1.01
USD: Lower limit of each transaction is USD
0.01, upper limit of each transaction is USD
33,169. Please ll in 101 when the transaction is
USD 1.01

statusint

Result identi er. 0 indicates success.

msg

StringResult message.

transaction_time_millis

longTime when the bank handles the transaction.

acquirer

StringAcquiring banks or payment processors.

card_identi er

StringCard identi er.
Each credit card will only have one card
identi er.

bank_result_code

String(40)Response code from the bank.

bank_result_msg

String(300)

Response message from the bank.

merchant_reference_info

JSONObject

Merchant reference information

merchant_reference_info.a liate_codesArray

This parameter will be returned when themerchant uses the feature of A liate Code in
TapPay Portal and the transaction match thesetting.

ffi

ffi

fi

fi

fi

fi

fi

fi

fi

fi

fi

fi

30

Refund API
Refund - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/transaction/refund
Production：https://prod.tappaysdk.com/tpc/transaction/refund
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

rec_trade_id

YString(20)Identi er for the transaction being refunded.
Unique identi er for a transaction generated by
TapPay.

bank_refund_id

NString(20)Self-de ned refund record identi er.
(Format : Half-shaped English number)Must be unique.

amountN

int

Only required for partial refund.
The amount must include two decimal
places(except “TWD” & “JPY”).
For example, “100” represents “$1.00”

additional_data

N

String(3000) Data will be encrypted and decrypted when othercustomization requirements.

Refund - Response
參數名

型態

說明

statusint

msg

StringResult message.

refund_id

StringRefund action identi er generated by TapPay.

refund_amontint

is_captured

BooleanWhether the transaction has been captured or not.

bank_result_code

String(40)Response code from the bank.

bank_result_msg

String(300)

Response message from the bank.

currency

String(3)The letter abbreviation for currency, following ISO 4217.

Result identi er. 0 indicates success.

Amount being refunded.
Except TWD & JPY, transaction price should times 100.
For instance, if transaction price is HKD1, will return
100.

fi

fi

fi

fi

fi

fi

31

Record- Request
Post
Production：https://sandbox.tappaysdk.com/tpc/transaction/query
Sandbox：https://prod.tappaysdk.com/tpc/transaction/query
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

records_per_page

N

int

Number of records on each page, up to 200.
Default value is 50.

page

N

int

The returned page.
Default value is 0.

lters

Y

JSONObject Restrictions on the trade records. The followinglters are possible:

lters.time

N

JSONObject Time frame should be 90 days or less.
* If rec_trade_id has been put in lter, time is
optionaltime.start_time

Y

long

Start time measured in milliseconds

time.end_time

Y

long

End time measured in milliseconds

lters.amountN

amount.upper_limitY

int

Upper bound for the priceamount.lower_limitY

int

Lower bound for the pricelters.cardholderN

cardholder.name

N

StringNamecardholder.phone_number

N

StringCellphone number

cardholder.email

N

StringE-mail addresslters.merchant_id

N

Array

A lter that allows you to obtain trade records
with speci c merchant ID. You may search withmultiple merchant IDs at once by putting them inan array.

JSONObject A lter that allows you to obtain trade records
within a speci c price range.
Foreign currency amount include two decimal
places (e.g 100 representative 1.00). There are
two parameters:

JSONObject A lter that allows you to obtain trade records
within a speci c card holder. There are threeparameters:

fi

fi

fi

fi

fi

fi

32

fi

fi

fi

fi

fi

fi

fi

Record API

RequiredType

Descriptionlters.record_status

N

String

-1
0
1
2
3
4
5

lters.rec_trade_id

N

StringA unique identi er for each transaction generated
by TapPay server.
You would need this identi er when you attempt
to refund a particular transaction. It is returned
by our server after calling a successful payment
API.
* If rec_trade_id has been put in lter, time is
optional

lters.order_number

N

StringA merchant self-de ned identi er for eachtransaction in TapPay.

lters.bank_transaction_id

NStringTransaction identi er for the bank.

lters.auth_code

N

StringBank authorization code.

lters.currency

N

String

The letter abbreviation for currency, following ISO
4217.

lters.tsp

N

BooleanOnly search for transaction which method is TSP.
Default is false.

lters.card_identi er

NStringCard identi er.
Each credit card will only have one card identi er.

order_byN

order_by.attributeN

Stringtime: Sort by the transaction
amount : Sort by the transaction

order_by.is_descending

N

BooleanIs descending sort needed
Default value is true.

ERROR
AUTH
OK
PARTIALREFUNDEDREFUNDED
PENDINGCANCEL

JSONObject Criteria for ordering

Record- Response
Item

Type

Description

statusint

API response code.
2 indicates end of the list, meaning there are no morerecords to be shown under the given lter.

msg

Stringrecords_per_page

int

Number of records on each page, up to 200.

page

int

The returned page.

total_page_countint

Total number of pages.

number_of_transactions

long

Total number of transactions.

API response message.

fi

fi

fi

fi

fi

fi

fi

fi

fi

33

fi

fi

fi

fi

fi

fi

fi

fi

fi

Item

Item

Type

Description

trade_records

JSONArray

Trade records.
Each transaction record is a JSONObject.

trade_records.rec_trade_id

String(20)Unique identi er for this transaction generated by
TapPay.

trade_records.auth_code

String(6)Bank authorization code.

trade_records.merchant_id

String(50)Involved merchant’s identi er as de ned on Portal.

trade_records.merchant_name

String(50)Name of the merchant. Default value is empty.

trade_records.app_name

StringName of the website / application

trade_records.time

longTime of the record in milliseconds.

trade_records.amountint

Price of the record. It will change if the transaction was
refunded.

trade_records.refunded_amountint

Refunded price of the record.

trade_records.record_status

int

-1
0
1
2
3
4
5

trade_records.bank_transaction_id

String(40)Transaction identi er for the bank.
You may customize one here if you wish, but it must be
unique, if not, then TapPay will generate a random one.
* We strongly recommend you to de ne the uniquebank_transaction_id by yourself to prevent when a
421 error occurs, the transaction cannot bechecked back.

trade_records.cap_millis

longTime when the transaction payment will be captured.

trade_records.original_amountint

Original price of the record.

trade_records.bank_transaction_
start_millis

longTime when the bank begins processing the transaction.

trade_records.bank_transaction_
end_millis

longTime when the bank nishes processing thetransaction.

trade_records.is_captured

BooleanWhether this record is captured or not.

trade_records.bank_result_code

String(40)Response code from the bank.

trade_records.bank_result_msg

String(300)

Response message from the bank.

trade_records.partial_card_numberStringFirst six digits of the card and last four digits of the
card.

fi

fi

fi

fi

fi

34

fi

ERROR
AUTH
OK
PARTIALREFUNDEDREFUNDED
PENDINGCANCEL

Item

Type

trade_records.payment_method

StringDescription
Payment Method
direct_pay
apple_pay
google_pay_token
google_pay_fpan
tsp_token

trade_records.details

StringList of product/service purchased in the transaction.

trade_records.cardholder

JSONObject

The card owner information

cardholder.name

String(40)Namecardholder.phone_number

String(40)Cellphone number* It is recommended to ll in the same number thatthe cardholder apply the credit card in the issuingbank.

cardholder.email

String(40)E-mail address

cardholder.zip_code

String(40)Zip code number* Mandatory when acquirer equals JP_TAPPAY

cardholder.address

String(90)Billing address* Mandatory when acquirer equals JP_TAPPAY

cardholder.national_id

String(40)National ID* Mandatory when acquirer equals JP_TAPPAY

cardholder.member_id

String(64)Member ID customized by merchant* Only available in Direct Pay

merchant_reference_info

JSONObject

Merchant reference information

merchant_reference_info.a liate_codesArray

This parameter will be returned when the merchantuses the feature of A liate Code in TapPay Portal andthe transaction match the setting.

three_domain_secure

BooleanIs it a 3D secure transaction

pay_by_instalment

BooleanIs it an instalment transaction

order_number

StringA merchant self-de ned identi er for each transactionin TapPay.

pay_by_redeem

BooleanIs it a redeem transaction

card_identi er

StringCard identi er.
Each credit card will only have one card identi er.

card_info

JSONObject

Credit card information

card_info.bin_code

String(6)First six digits of the card

card_info.last_four

String(4)Last four digits of the card

card_info.issuer

StringCard issuer

card_info.issuer_zh_tw

StringIssuer Chinese name* If the issuing bank is not in Taiwan, this value will
be an empty

fi

fi

ffi

fi

ffi

fi

fi

35

fi

Direct Pay
Apple Pay
Google Pay Token Card
Google Pay Real PAN
TSP Token

Item

Type

Description

card_info.bank_id

StringBank identi er* If the issuing bank is not in Taiwan, this value will
be an empty

card_info.funding

int

Card usage-1 = Unknown
0 = Credit Card
1 = Debit Card
2 = Prepaid Card

card_info.type

int

Card type-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
5 = AMEX

card_info.level

StringCard level

card_info.country

StringCountry of card issuer

card_info.country_code

StringCountry code of card issuer

card_info.expiry_date

StringCard expired date, Format : YYYYMM
When request param of remember equals true will
return.
* Only available in Direct Pay

is_rba_veri ed

Boolean

It is used to judge whether the transaction has passed
the Cherri X transaction risk assessment.
* Cherri X transaction risk assessment can evaluate
the risk for each transaction to identify and prevent
counterfeit transaction. For more information,please contact our sales.

transaction_method_details

JSONObject

Transaction method details.

transaction_method_details.tran
saction_method

String

THREE_DOMAIN_SECURE: Means the transaction was
sent to the bank with 3D secure.
FRICTIONLESS: Means the transaction was sent to thebank with frictionless.

transaction_method_details.tran
saction_method_reference

String

RBA: Means the transaction method was decided by
RBA rule setting.
REQUEST: Means the transaction method was decided
by the request speci cation that the merchant set in thepayment request.
* Cherri X transaction risk assessment can evaluate
the risk for each transaction to identify and prevent
counterfeit transaction. For more information,please contact our sales.

fi

fi

fi

36

Cap Today API
Cap Today - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/transaction/cap
Production：https://prod.tappaysdk.com/tpc/transaction/cap
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

rec_trade_id

YString(20)Unique identi er for this transaction generated by
TapPay.

Cap Today - Response
Item

Type

Description

statusint

msg

StringResult message.

cap_millis

longTime when the transaction payment will be captured.

currency

String(3)The letter abbreviation for currency, following ISO 4217.

Result identi er. 0 indicates success.

fi

fi

37

Cap Cancel API
Cap Cancel - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/transaction/cap/cancel
Production：https://prod.tappaysdk.com/tpc/transaction/cap/cancel
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

rec_trade_id

YString(20)Unique identi er for this transaction generated by
TapPay.

Cap Cancel - Response
Item

Type

Description

statusint

msg

StringResult message.

currency

String(3)The letter abbreviation for currency, following ISO 4217.

rec_trade_id

String(20)Unique identi er for this transaction generated by
TapPay.

Result identi er. 0 indicates success.

fi

fi

fi

38

Remove Card API
Remove Card - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/card/remove
Production：https://prod.tappaysdk.com/tpc/card/remove
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

card_key

Y

String(64)A security key used to encrypt the card token.

card_token

Y

String(67)A permanent token that represents thecustomer’s card.

Remove Card - Response
Item

Type

statusint

msg

StringDescription
Result identi er. 0 indicates success.
Result message.

fi

39

Trade History API
Trade History - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/transaction/trade-history
Production：https://prod.tappaysdk.com/tpc/transaction/trade-history
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

rec_trade_id

YString(20)Unique identi er for this transaction generated by
TapPay.

Trade History - Response
Item

Type

Description

statusint

msg

Stringrec_trade_id

String(20)Unique identi er for this transaction generated by
TapPay.

currency

String(3)The letter abbreviation for currency, following ISO 4217.

trade_history

JSONArray

Transaction history.
Each action history would be a JSONObject.

trade_history.amountint

Transaction price.

trade_history.action

int

Transaction status.
0 Authorize
1 Capture
3 Refund
4 Pending
5 Cancel
6 Refund Cancel

trade_history.millis

long

Trigger action timetrade_history.success

Booleantrade_history.bank_transaction_
millislong

The practical time that TapPay send the transaction tobank to process authorization, capturing, refund andcanceling refund the payment.

trade_history.can_refund_cancel_millislong

Return this parameter when action equals 3 to indicate
when can cancel the refund

Result identi er. 0 indicates success.
Result message.

Whether the action status is successful

fi

fi

fi

40

Item

Type

Description

trade_history.refund_id

Stringtrade_history.bank_refund_id

String(20)Self-de ned refund record identi er.
(Format : Half-shaped English number)Must be unique.

trade_history.is_pending

Boolean

It will be true when the transaction is not refunded
completed. In contrast, it will be false when the refund
is done.

trade_history.bank_result_code

String(40)Response code from the bank.
We will reply the actual bank result code in theauthorization and payment capture history. As forrefund, we will show the bank result code of eachrefund transaction.

trade_history.bank_result_msg

String(300)

Response message from the bank.
We will reply the actual bank result message in theauthorization and payment capture history. As forrefund, we will show the bank result message of eachrefund transaction.

Return this parameter when action equals 3 or 6.
Refund action identi er generated by TapPay.

fi

fi

fi

41

Card Metadata API
Card Metadata - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/card/metadata
Production：https://prod.tappaysdk.com/tpc/card/metadata
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

card_key

Y

String(64)A security key used to encrypt the card token.

card_token

Y

String(67)A permanent token that represents thecustomer’s card.

Card Metadata - Response
Item

Type

Description

statusint

Result identi er. 0 indicates success.
* It will be returned 2011 (Card not found. Invalid
token) when the card_key or card_token does notexist or be deleted.

msg

StringResult message.
* It will be returned 2011 (Card not found. Invalid
token) when the card_key or card_token does notexist or be deleted.

card_info

JSONObject

Credit card information

card_info.bin_code

String(6)First six digits of the card

card_info.last_four

String(4)Last four digits of the card

card_info.issuer

StringCard issuer

card_info.issuer_zh_tw

StringIssuer chinese name* If the issuing bank is not in Taiwan, this value will
be an empty

card_info.bank_id

StringBank identi er* If the issuing bank is not in Taiwan, this value will
be an empty

fi

fi

42

Item

Type

Description

card_info.funding

int

Card usage-1 = Unknown
0 = Credit Card
1 = Debit Card
2 = Prepaid Card

card_info.type

int

Card type-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
5 = AMEX

card_info.level

StringCard level

card_info.country

StringCountry of card issuer

card_info.country_code

StringCountry code of card issuer

card_info.expiry_date

StringCard expired date, Format : YYYYMM
When request param of remember equals true will
return.
* Only available in Direct Pay

card_info.token_status

StringToken Status:
NOT_SUPPORTREQUEST_PROCESSING
ACTIVESUSPENDED
DELETED

card_art_info

JSONObject

card_art_info.card_art_status

StringNOT_SUPPORTREQUEST_PROCESSINGSUPPORT

card_art_info.is_real_card_face

BooleanDetermine 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.
2. The card type is Visa or MasterCard, but the issuingbank does not support it.
3. The card type is Visa or MasterCard, but the issuingbank does not provide real card faces to theInternational Credit Card Networks. (Rarely happened)

card_art_info.image

JSONObject

image.url

Stringimage.width

int

Card face width, unit : px

image.height

int

Card face height, unit : px

card_art_info.foreground_color

StringCard face text color

card_art_info.masked_card_num
berStringMasked Credit card last four digits(e.g. : **** **** **** **** 1234)

Card face infomation

image
Image Url, start with “https://”

43

Item

Type

Description

card_art_info.issuer

String

The card issuing bank displayed on the card face (IfIs_real_card_face is false, you can display issuer on thecard face.)44

Card Notify API
After enable TSP service, you will be informed the updated card informationby 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 updatenoti cation.

Card Notify - Request
Request Header
Key: Content-Type
Value: application/json
Request Url
Post
https://{your_tsp_notify_url}
Item

Type

Description

statusint

msg

StringResult 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

Credit card information

card_info.bin_code

String(6)First six digits of the card

card_info.last_four

String(4)Last four digits of the card

card_info.issuer

StringCard issuer

card_info.issuer_zh_tw

StringIssuer Chinese name* If the issuing bank is not in Taiwan, this value will
be an empty

card_info.bank_id

StringBank identi er* If the issuing bank is not in Taiwan, this value will
be an empty

card_info.funding

int

Result identi er. 0 indicates success.

Card usage-1 = Unknown
0 = Credit Card
1 = Debit Card
2 = Prepaid Card

fi

fi

fi

45

Item

Type

Description

card_info.type

int

card_info.level

StringCard level

card_info.country

StringCountry of card issuer

card_info.country_code

StringCountry code of card issuer

card_info.expiry_date

StringCard expired date, Format : YYYYMM
When request param of remember equals true will
return.
* Only available in Direct Pay

card_info.token_status

StringToken Status:
ACTIVESUSPENDED
DELETED

card_art_info

JSONObject

card_art_info.card_art_status

StringNOT_SUPPORTSUPPORT

card_art_info.is_real_card_face

BooleanDetermine 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.
2. The card type is Visa or MasterCard, but the issuingbank does not support it.
3. The card type is Visa or MasterCard, but the issuingbank does not provide real card faces to theInternational Credit Card Networks. (Rarely happened)

card_art_info.image

JSONObject

image.url

Stringimage.width

int

Card face width, unit : px

image.height

int

Card face height, unit : px

card_art_info.foreground_color

StringCard face text color

card_art_info.masked_card_num
berStringMasked Credit card last four digits(e.g. : **** **** **** **** 1234)

card_art_info.issuer

String

The card issuing bank displayed on the card face (IfIs_real_card_face is false, you can display issuer on thecard face.)

Card type-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
5 = AMEX

Card face infomation

image
Image Url, start with “https://”46

Card Notify API Sandbox
After enable TSP service, you will be informed by Card Notify API throughtsp_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 noti cation correctly.
* Only Available in Sandbox

Card Notify Sandbox - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/sandbox/card/metadata/
notifyHeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

card_key

Y

String(64)Card authorization key.
This column is gotten from Pay by Prime or Bind
Card API.
Please use test card : 4242424181784242

card_token

Y

String(67)Card token.
This column is gotten from Pay by Prime or Bind
Card API.
Please use test card : 4242424181784242

tsp_notify_url

YString(500)

Request to url when card status change.

Card Notify Sandbox - Response
Item

Type

statusint

msg

StringDescription
Result identi er. 0 indicates success.
Result message.

fi

fi

47

Get Member Card API
Get Member Card - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/direct-pay/get-member-card
Production：https://prod.tappaysdk.com/tpc/direct-pay/get-member-card
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

member_id

Y

String(64)Member ID customized by merchant.
Use it when use pay by prime with remember
true or bind card)* Only available in Direct Pay

Get Member Card - Response
Item

Type

Description

statusint

msg

Stringmember_id

String(64)Member ID customized by merchant.
Use it when use pay by prime with remember true orbind card)* Only available in Direct Pay

cards

JSONArray

Binding cards.
Each card is a JSONObject.

cards.card_token

String(67)A permanent token that represents the customer’s card

cards.bin_code

String(6)First six digits of the card

cards.last_four

String(4)Last four digits of the card

cards.issuer

StringCard issuer

cards.issuer_zh_tw

StringIssuer Chinese name* If the issuing bank is not in Taiwan, this value will
be an empty

cards.bank_id

StringBank identi er* If the issuing bank is not in Taiwan, this value will
be an empty

Result identi er. 0 indicates success.
Result message.

fi

fi

48

Item

Type

Description

cards.funding

int

Card usage-1 = Unknown
0 = Credit Card
1 = Debit Card
2 = Prepaid Card

cards.type

int

Card type-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
5 = AMEX

cards.level

StringCard levelcards.country

StringCountry of card issuer

cards.country_code

StringCountry code of card issuer

cards.card_identi er

StringCard identi er. Each credit card will only have one card
identi er.

cards.expiry_date

StringCard expired date, Format : YYYYMM
When request param of remember equals true will
return.
* Only available in Direct Pay

fi

fi

fi

49

Update Cardholder API
Update Cardholder - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/card/update-cardholder
Production：https://prod.tappaysdk.com/tpc/card/update-cardholder
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

card_token

Y

String(67)A permanent token that represents thecustomer’s card

name

N

String(40)Namephone_number

N

String(40)Cellphone number

email

N

String(40)E-mail address

zip_codeN

String(40)Zip code number

addressN

String(90)Billing addressnational_id

N

String(40)National ID

member_id

N

String(64)Member ID customized by merchantcountry_code

N

String(2)Country Code (ISO 3166-1 Alphabetical Code)

city

N

String(500)City

Update Cardholder - Response
Item

Type

statusint

msg

Stringcard_token

String(67)update_millis

longcardholder

JSONObject

Description
Result identi er. 0 indicates success.
Result message.
A permanent token that represents the customer’s
card.
Update time
Latest information of the cardholder

fi

50

Item

Type

Description

cardholder.name

String(40)Namecardholder.phone_number

String(40)Cellphone number

cardholder.email

String(40)E-mail address

cardholder.zip_code

String(40)Zip code number

cardholder.address

String(90)Billing address

cardholder.national_id

String(40)National ID

cardholder.member_id

String(64)Member ID customized by merchantcardholder.country_code

String(2)Country Code (ISO 3166-1 Alphabetical Code)cardholder.city

String(500)

City

51

Check A liate Code API
Check A liate Code - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/a liate-code/check
Production：https://prod.tappaysdk.com/tpc/a liate-code/check
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

a liate_code_group_name

N

String(50)A liate code groupa liate_code_name

Y

String(20)A liate code

card_token

N

String(67)Card token
Must be used with card_key, but cannot be usedwith prime at the same time.

card_key

N

String(64)Card keyMust be used with card_token, but cannot be
used with prime at the same time.

prime

N

String(67)The one time token returned from getPrime.
Cannot be used with card_token /card_key at thesame time.

Check A liate Code - Response
Item

Type

statusint

msg

Stringresult_code

int

Description
Result identi er. 0 indicates success.
Result message.
Whether it meets the query conditions.
0 indicates success.
1 indicates fail.

ffi

ffi

ffi

ffi

ffi

fi

ffi

ffi

ffi

ffi

52

Push Token API
Only available in Production

Push Token - Request
Post
Production：https://prod.tappaysdk.com/tpc/tsp/token/push-tokenize
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)tsp_push_token

Y

String(1000) When opening the app, we will send the value of
tspPushToken to the app.

Authentication key for each individual partner.

Push Token - Response
Item

Type

Description

statusint

msg

StringResult message.

token_status

StringToken Status: ACTIVE

card_secret

JSONObject

Contains the card key and token.
* Only available in Direct Pay

card_secret.card_token

String(67)A permanent token that represents the customer’scard. You may use the card token to pay by using Pay
by Card Token API.

card_secret.card_key

String(64)A security key used to encrypt the card token，You
may use the card token to pay by using Pay by Card
Token API.

card_info

JSONObject

Credit card information

card_info.bin_code

String(6)First six digits of the card

card_info.last_four

String(4)Last four digits of the card

card_info.issuer

StringCard issuer

card_info.issuer_zh_tw

StringIssuer Chinese name* If the issuing bank is not in Taiwan, this value will
be an empty

Result identi er. 0 indicates success.

fi

53

Item

Type

Description

card_info.bank_id

StringBank identi er* If the issuing bank is not in Taiwan, this value will
be an empty

card_info.funding

int

Card usage-1 = Unknown
0 = Credit Card
1 = Debit Card
2 = Prepaid Card

card_info.type

int

Card type-1 = Unknown
1 = VISA
2 = MasterCard
3 = JCB
5 = AMEX

card_info.level

StringCard level

card_info.country

StringCountry of card issuer

card_info.country_code

StringCountry code of card issuer

card_info.expiry_date

StringCard expired date, Format : YYYYMM
When request param of remember equals true will
return.
* Only available in Direct Pay

cardholder

JSONObject

The card owner information

cardholder.name

String(40)Namecardholder.phone_number

String(40)Cellphone number* It is recommended to ll in the same number thatthe cardholder apply the credit card in the issuingbank.

cardholder.email

String(40)E-mail address

cardholder.zip_code

String(40)Zip code number* Mandatory when acquirer equals JP_TAPPAY

cardholder.address

String(90)Billing address* Mandatory when acquirer equals JP_TAPPAY

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)

fi

fi

54

Reconciliation API
Reconciliation - Request
Post
Sandbox：https://sandbox.tappaysdk.com/tpc/transaction/reconciliation
Production：https://prod.tappaysdk.com/tpc/transaction/reconciliation
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

records_per_page

N

int

Number of records on each page, up to 200.
Default value is 50.

page

N

int

The returned page.
Default value is 0.

start_time_millis

Y

long

The real capturing and refunding start-time withbank which is measured in milliseconds.

end_time_millis

Y

long

The real capturing and refunding end-time withbank which is measured in milliseconds.

transaction_actions

Y

StringArray

Transaction Action
Capturing: CAPTURE
Refund: REFUND

merchant_ids

NStringArray

Involved merchant’s identi er as de ned on
Portal. This parameter allows multiple merchantid.
* You can only choose merchant id or
acquirer to put in the request body.

acquirers

N

StringArray

This parameter allows multiple acquirers.
* You can only choose merchant id or
acquirer to put in the request body.

Reconciliation - Response
Item

Type

Description

statusint

API response code.
2 indicates end of the list, meaning there are no morerecords to be shown under the given lter.

msg

Stringrecords_per_page

int

Number of records on each page, up to 200.

page

int

The returned page.

API response message.

fi

fi

fi

55

Item

Type

Description

total_page_countint

Total number of pages.

number_of_transactions

long

Total number of transactions.

reconciliation_datas

JSONArray

Capturing and refunding details of each transaction.

merchant_id

StringInvolved merchant’s identi er as de ned on Portal.

merchant_description

StringTapPay merchant reference in Merchant of TapPay
Portal.

acquirer

StringAcquirerpayment_method

StringPayment Method
direct_pay
apple_pay
google_pay_token
google_pay_fpan
tsp_token

rec_trade_id

StringUnique identi er for this transaction generated by
TapPay.

bank_transaction_id

StringTransaction identi er for the bank.

order_number

StringA merchant self-de ned identi er for each transactionin TapPay.

millislong

Trigger status timebank_transaction_millis

long

The practical time that TapPay send the transaction tobank to process authorization, capturing, refund andcanceling refund the payment.

transaction_action

StringTransaction Action
Capturing: CAPTURE
Refund: REFUND

transaction_result

BooleanWhether the status is successful.

trade_amountint

The amount of capturing and refunding.

auth_millis

long

The time that merchant call TapPay API for
authorization.

auth_amountint

Amount while authorization.

currency

String

The letter abbreviation for currency, following ISO
4217.

partial_card_number

StringFirst six digits of the card and last four digits of the
card.

card_type

int

auth_code

StringCard Type-1 = Unknown
1 = Visa
2 = MasterCard
3 = JCB
5 = AMEXBank authorization code.

fi

fi

fi

fi

fi

56

fi

Direct Pay
Apple Pay
Google Pay Token Card
Google Pay Real PAN
TSP Token

Item

Type

is_kyc_veri ed

BooleanDescription
Whether to do KYC or not.
* Only available in Direct Pay and credit cards
issued in Taiwan.

fi57

Create A liate Code API
Create A liate Code - Request
Post
https://api.tappaysdk.com/partner/a liate-code/create
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

a liate_code_name

Y

String(20)A self-de ned name for each a liate code(halfshaped English and number, less than 20
characters).

fpan_bincodes

N

StringArrayFPAN bincode (6~13 digits), which is limited to
50 sets per request.

token_bincodes

N

StringArray

Token bincode (6~13 digits), which is limited to
50 sets per request.

requset_type

Y

Stringsandbox means test environment
prod means production environment

Create A liate Code - Response
Item

Type

Description

statusint

Result identi er. 0 indicates success.

msg

StringResult message.

ffi

ffi

ffi

ffi

ffi

fi

fi

ffi

58

Delete A liate Code API
Delete A liate Code - Request
Post
https://api.tappaysdk.com/partner/a liate-code/delete
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

a liate_code_name

Y

String(20)A self-de ned name for each a liate code(halfshaped English and number, less than 20
characters).

fpan_bincodes

N

StringArrayFPAN bincode (6~13 digits), which is limited to
50 sets per request.

token_bincodes

N

StringArray

Token bincode (6~13 digits), which is limited to
50 sets per request.

requset_type

Y

Stringsandbox means test environment
prod means production environment

Delete A liate Code - Response
Item

Type

statusint

msg

StringDescription
Result identi er. 0 indicates success.
Result message.

ffi

ffi

ffi

ffi

ffi

fi

fi

ffi

59

Create A liate Code Group API
Create A liate Code Group - Request
Post
https://api.tappaysdk.com/partner/a liate-code/group/create
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

a liate_code_group_name

Y

String(50)A self-de ned name for each a liate code group(half-shaped English and number, less than 50
characters).

a liate_code_names

Y

StringArray

A liate Code, which is limited to 50 sets per
request.

requset_type

Y

Stringsandbox means test environment
prod means production environment

Create A liate Code Group - Response
Item

Type

statusint

msg

StringDescription
Result identi er. 0 indicates success.
Result message.

ffi

ffi

ffi

ffi

ffi

fi

fi

ffi

ffi

ffi

60

Delete A liate Code Group API
Delete A liate Code Group - Request
Post
https://api.tappaysdk.com/partner/a liate-code/group/delete
HeaderContent-Type：application/json
x-api-key：Your TapPay partner key
Item

RequiredType

Description

partner_key

YString(64)Authentication key for each individual partner.

a liate_code_group_name

Y

String(50)A self-de ned name for each a liate code group(half-shaped English and number, less than 50
characters).

a liate_code_names

Y

StringArray

A liate Code, which is limited to 50 sets per
request.

requset_type

Y

Stringsandbox means test environment
prod means production environment

Delete A liate Code Group - Response
Item

Type

statusint

msg

StringDescription
Result identi er. 0 indicates success.
Result message.

ffi

ffi

ffi

ffi

ffi

fi

fi

ffi

ffi

ffi

61

Backend API Error Codestatusmsg

0Success2

End of list

4

IP mismatch

5

Wrong JSON format

-

-

41

Wrong card format

43

Card unauthorized access

-

-

61

Merchant not found or removed66

Not a line pay merchant67

This merchant does not support this payment method

68

This merchant does not support refund cancel

70

TapPay doesn’t support cardholder verify function (KYC) of this bank71

This merchant does not support instalment

72

This merchant only support instalment

74

This merchant does not support 3DS2.0

75This merchant does not support non-3D secure

-

-

80

Invaild x-api-key or app key

81

Partner not found

84

Partner unauthorized

89

This merchant does not support this currency

-

-

91

Expired prime

92

The acquirer doesn’t support void auth date is di erent from the auth date.
Error handling:
The Acquiring Bank only supports execute voiding authorization on the same day as
authorization. Please execute refund after capping

-

-

121

Invalid arguments : primeff

62

statusmsg

122

Card encrypt error

-

-

126

Barcode not found

127

Barcode is expired

128

Barcode has been use

129

Member not found130

Merchant group not found131

Merchant group setting error

132

On-us merchant not found141

This partner does not support amount pending

-

-

421

Gateway Timeout

422

Authorization Timeout

-

-

501

Missing arguments : cardholder

502

Missing arguments : merchant_id

503

Missing arguments : prime

504

Missing arguments : currency

505

Missing arguments : details

506

Missing arguments : partner_key507

Missing arguments : cardholder > phone_number

508

Missing arguments : cardholder > name509

Missing arguments : cardholder > email

510

Invalid arguments : amount

511

Invalid arguments : instalment

512

Invalid arguments : delay_capture_in_days513

Out of range : instalment

514

Out of range : delay_capture_in_days

515

Out of range : details

516

Out of range : currency

517

Out of range : order_number

63

msg

518

Out of range : bank_transaction_id519

Out of range : cardholder > phone_number520

Out of range : cardholder > name521

Out of range : cardholder > email

522

Out of range : cardholder > addr523

Out of range : cardholder > zip524

Out of range : cardholder > national_id525

Out of range : cardholder > member_id526

Missing arguments : card_key527

Missing arguments : card_token

528

Out of range : card_key529

Out of range : card_token

-

-

535

Invalid arguments : records_per_page536

Invalid arguments : page537

Invalid arguments : lters > time > start_time

538

Invalid arguments : lters > time > end_time

539

Invalid arguments : lters > rec_trade_id545

Invalid arguments : lters > amount > upper_limit

546

Invalid arguments : lters > amount > lower_limit

547

Invalid arguments : lters > app_id548

Invalid arguments : lters > merchant_id

549

Invalid arguments : lters > record_status

550

Invalid arguments : order_by > attribute

551

Invalid arguments : order_by > is_descending559

Out of range : records_per_page560

Out of range : page561

Out of range : lters > time > start_time562

Out of range : lters > time > end_time563

lters > time > start_time can’t be later than the end_time564

Out of range : lters > amount > upper_limit

fi

fi

fi

fi

fi

fi

fi

fi

fi

fi

64

fi

fi

statusmsg

565

Out of range : lters > amount > lower_limit

566

lters > amount > lower_limit can’t be larger than the upper_limit

567

Out of range : lters > app_id568

Out of range : order_number569

Out of range : bank_transaction_id574

Out of range : card_ccv

578

Out of range : additional_data587

Out of range : partner_key

588

Invalid arguments : delay_capture_in_days

589

Invalid arguments : platform_type

590

Missing arguments : android_merchant_id

591

Missing arguments : pay_token_data

592

Missing arguments : apple_merchant_id593

Out of range : merchant_id594

Out of range : apple_merchant_id595

Out of range : delay_capture_in_days

596

Missing arguments : rec_trade_id597

Out of range : rec_trade_id617

Out of range : fraud_id

622

Missing arguments : member_id

627

Invalid arguments : result_url > backend_notify_url

628

Invalid arguments : result_url > frontend_redirect_url

629

Missing arguments : result_url > backend_notify_url

630

Missing arguments : result_url > frontend_redirect_url

631

Missing arguments : result_url

632

Acquirer doesn’t support 3D Secure.

633

3D Secure get redirect url error

635

Acquirer doesn’t support instalment

636

Acquirer doesn’t support redeem

637

Acquirer doesn’t support instalment and redeem concurrently

643

Invalid arguments : additional_data

fi

65

fi

fi

statusstatusmsg

644

Invalid arguments : line_pay_product_image_url

669

Out of range : request_id670

Out of range : refund_id691

Acquirer doesn’t Support Non-3D Secure.

-

-

693

Missing Arguments : barcode694

Out of range: barcode695

Out of range: barcode_length696

Out of range: barcode_update_secs

697

Invalid arguments : barcode_length

698

Invalid arguments : barcode_update_sec699

Invalid argument : barcode

700

Invalid argument : retry_mode

701

Doesn’t support merchant_id and merchant_group_id concurrently

706

Out of range : bank_refund_id708

Invalid arguments : bank_refund_id713

Partner doesn’t support sub_merchant804

Invalid arguments : no_rebate_amount

-

-

810

Invalid arguments : payment_method811

Out of range : branch_code812

Out of range : branch_name813

Out of range : pos_id

-

-

814

Missing arguments : easy_wallet_secure_code

815

Invalid arguments : easy_wallet_secure_code

816

Missing arguments : easy_wallet_contract_no817

Invalid arguments : easy_wallet_contract_no822

Search time period can not be more than 90 days

823

Missing arguments : easy_wallet_ftps_account824

Invalid arguments : easy_wallet_ftps_account66

statusmsg

825

Missing arguments : easy_wallet_ftps_password

826

Invalid arguments : easy_wallet_ftps_password

827

Ftps connection failed due to wrong easy_wallet_ftps_account oreasy_wallet_ftps_password

828

Easy Wallet upload path not found829

Easy Wallet download path not found835

easy_wallet_ftps_account mismatch with existed merchant836

easy_wallet_ftps_password mismatch with existed merchant837

fubon_sftp_account mismatch with existed merchant838

fubon_sftp_password mismatch with existed merchant839

fubon_sftp_upload_path mismatch with existed merchant840

fubon_sftp_download_path mismatch with existed merchant843

Invalid arguments > product_image_url

844

Out of range : product_image_url

845

Out of range : event_code

846

Invalid arguments : merchant_unversal_links

856

Does not support merchant_ids and acquirers concurrently

857

Missing arguments : transaction_actions

858

Invalid arguments : transaction_actions

860

Missing arguments : emails

861

Invalid arguments : merchant_ids

862

Out of range : kyc_veri cation_merchant_id863

national_id must be veri ed in identity veri cation (KYC)864

kyc_veri cation_merchant_id is only allowed for identity veri cation (KYC)

865

Missing arguments : nccc_terminal_id866Bank not support identity veri cation (KYC)867

Out of range : description868

You have to update at least one cardholder information889

Out of range : payment_number

890

Out of range : nccc_terminal_id891

Cardholder not found

fi

fi

fi

fi

fi

fi

67

statusmsg

892

Out of range : phone_number893

Out or range : name894

Out of range : email895

Out of range : address896

Out of range : zip897

Out of range : national_id898

Out of range : member_id899

Invalid arguments : acquirers

947

EasyWallet transaction not found

950

EasyWallet get redirect url error

-

-

900

Service suspension due to system upgrade901

Decrypt payment data error

904

Merchant’s acquirer not found905

Apple Pay transaction not found

906

Apple Pay order id already exist

907

Android Pay transaction not found908

Android Pay order id already exist

909

Inconsistent amount

910

Inconsistent currency

911

Apple merchant not found912

Android merchant not found

915

System error, please contact TapPay customer service

916

Signature veri cation is not proceed

917

Signature veri cation error

919

PaymentMethodToken expired

920

Message decryption is not proceed

-

-

922

LINE Pay get redirect url error

923

LINE Pay transaction not found924

LINE Pay order is canceled

fi

fi

68

status

msg

-

-

925

Three Domain Secure’s order is canceled

-

-

926

Acquirer doesn’t support this currency

-

-

930

Samsung Pay merchant not found931

Samsung Pay order id already exist

932

Samsung Pay transaction not found

-

-

934

Incorrect status [Transaction has been Captured, it could not be canceled]935

Incorrect status [Transaction does not arrange capture, it could not be canceled]936

Incorrect status [Transaction is capturing, it could not be canceled]

-

-

937

This card does not support this function

939

Request processing

940

Invalid transaction status

941

Transaction arguments mismatch

942

Invalid environment

943

JKOPAY get redirect url error

944

JKOPAY transaction not found946

Do not support refund during bank capturing

-

-

948

Previous process is still accessing, please try again later

949

Previous request is still accessing, please try again later

-

-

1001

Direct Pay transaction not found

-

-

2011

Card not found, Invalid token

2012

Card key error

2013

Card expired

4002

Invalid arguments : rec_trade_id69statusmsg

4014

Repeated refund

-

-

5001

Kyc veri cation merchant not found5002

Identity veri cation (KYC) failed

5003

Identity veri cation (KYC) exception happened

5004

national_id can’t be empty in identity veri cation (KYC)

5005

phone_number can’t be empty if it is in need of identity veri cation (KYC)

5006

This acquirer not support identity veri cation (KYC)

5007

Can not recognize card issuer if this acquirer not support o -us card in identity
veri cation (KYC)

5008

This acquirer not support o -us card in identity veri cation (KYC)

5009

This acquirer not support verify phone number in identity veri cation (KYC)

-

-

6001

Duplicate bank_transaction_id

6002

Duplicate bank_refund_id

-

-

8001

Partner doesn’t support TSP

8002

Missing arguments : tsp_enable

8003

Invalid arguments : tsp_enable

8004

Missing arguments : tsp_token

8005

Missing arguments : token_status

8006

Missing arguments : card_expiry_date

8007

Missing arguments : token_card_expiry_date

8008

Invalid arguments : token_status

8009

Invalid arguments : tsp_token

8010

Invalid arguments : width

8011

Invalid arguments : height

8012

Invalid arguments : tsp_notify_url

8013

Missing arguments : start_millis

8014

Missing arguments : end_millis

8015

Invalid arguments : start_millis

fi

fi

ff

fi

fi

fi

ff

fi

fi

fi

fi

70

statusmsg

8016

Invalid arguments : end_millis

8017

Invalid arguments : end_millis (end_millis is less than start_millis)

8019

Missing arguments : tsp_notify_url

-

-

9003

Out of range : rba_merchant_key

9017

Invalid arguments : challenge_lowest_score

9018

Missing arguments : fpan_bincodes or token_bincodes

9019

Invalid arguments : fpan_bincodes

9020

Invalid arguments : token_bincodes

9021

Missing arguments : a liate_code_names

9022

Invalid arguments : a liate_code_names

9023

Missing arguments : a liate_code_group_name9024

Invalid arguments : a liate_code_group_name9025

Invalid arguments : order_number

9026

Out of range : fpan_bincodes9027

Out of range : token_bincodes

9028

Missing arguments : a liate_code_name9029

Invalid arguments : a liate_code_name9030

Out of range : prime

9031

Missing arguments : card_token or prime

9032

Missing arguments : bank_member_id

9037

Doesn’t support card_token and prime concurrently

-

-

9051

Missing arguments : jko_pay_insurance_policy

9052

Missing arguments : jko_pay_insurance_policy > proposer

9053

Missing arguments : jko_pay_insurance_policy > insured

9054

Missing arguments : jko_pay_insurance_policy > nal_price9055

Missing arguments : jko_pay_insurance_policy > insurance_type

9056

Missing arguments : jko_pay_insurance_policy > policy_id

9057

Missing arguments : jko_pay_insurance_policy > payment_deadline

9058

Missing arguments : jko_pay_insurance_policy > payment_frequency

fi

ffi

ffi

ffi

ffi

ffi

ffi

71

statusmsg

9059

Out of range : jko_pay_insurance_policy > proposer

9060

Invalid arguments : jko_pay_insurance_policy > nal_price9061

Out of range : jko_pay_insurance_policy > policy_id

9062

Invalid arguments : jko_pay_insurance_policy > payment_frequency

9063

Invalid arguments : jko_pay_insurance_policy > payment_deadline

-

-

9118

Missing arguments : tsp_push_token

9119

Out of range : tsp_push_token

-

-

10001

Transaction pending

10002

IP mismatch

10003

Wrong card, please ask for issuer

10004

Bank timeout

10005

Bank system error

10006

Duplicate transaction

10007

3D validate error

10008

Bank merchant account data error

10009

Amount error

10010

Transaction pending capture, can not refund

10011

Refund error. Please try again.

10012

Data format error

10013

Bank transaction id duplicate

10014

Invalid bank transaction id

10015

Redeem failed

10023

Bank error or TSP error

10024

Authorized transaction cannot be partially refunded

10025

Auth code mismatch error

10026

Bank transaction id mismatch error

10028

Samsung Pay error

10029

CTBC decrypt data error

10030

CTBC decrypt data invalid eci

fi72status

msg

10031

CTBC decrypt data missing errorCode

10032

Card CTBC decrypt data missing xid

10033

CTBC decrypt data missing cardNumber

10034

CTBC decrypt data missing expiry

10035

CTBC decrypt data missing eci

10036

Card number mismatch error

10037

Card expiry date mismatch error

10038

Redeem transaction cannot be partially refunded

10039

This merchant does not support this card type

-

-

10042

Doesn’t support this card’s country code

10043

This card can’t nd issuer’s country code

-

-

10048

The transaction amount is 0, cannot be refunded

10049

The transaction amount is 0, cannot be captured

-

-

10050

Out of range : amount10051

Out of range : amount (refund amount must be less than or equal to remained
amount)10052

Con rm order timeout

-

-

10055

Missing arguments : lters > time

10056

Missing arguments : lters

-

-

11000

Invalid arguments : rec_trade_id

-

-

12001

Rba doesn’t support transaction with merchant_id

12007

Merchant Group Setting not match rba recommendation

12008

Payment request not match rba recommendation

-

-

13002

This apple pay merchant identi er is disabled

fi

fi

fi

fi

fi

73

status

msg

-

-

14001

A liate code group not found14002

A liate code not found14003

Duplicate a liate code

14004

Duplicate fpan bincode

14005

Duplicate token bincode

14006

Create a liate code failed

14007

Delete a liate code failed

14008

Update a liate code failed

14009

Create bincode failed

14010

Delete bincode failed

14011

Fpan bincode exceeding single a liate code limit

14012

Token bincode exceeding single a liate code limit

-

-

15001

Easy Wallet not support duplicate bank_member_id binding

15002

Easy Wallet token already canceled binding

-

-

19004

Push-tokenize failed: REQUIRE_ADDITIONAL_AUTHENTICATION

-

-

21001

Terminal Pay transaction not found

21002

Terminal Pay transaction cannot be partially refunded

-

-

9999

System is under maintenance, please contact TapPay customer service

ffi

ffi

ffi

ffi

ffi

ffi

ffi

ffi

74