API parameters
Important Notice
New version of Payment Action API has been released.
We are recommending our merchants to refer new guide Payment Maintenance to implement Payment Action API.
Data types
N - Numeric
C - Characters (AlphaNumeric and symbols)
Payment Action Request Parameter
Sample Request
<PaymentProcessRequest>
<version>3.3</version>
<timeStamp></timeStamp>
<merchantID></merchantID>
<processType></processType>
<invoiceNo></invoiceNo>
<actionAmount></actionAmount>
<bankCode></bankCode>
<accountName></accountName>
<accountNumber></accountNumber>
<subMerchantList>
<subMerchant subMID="" subAmount="" />
<subMerchant subMID="" subAmount="" />
</subMerchantList>
<notifyURL></notifyURL>
<hashValue></hashValue>
</PaymentProcessRequest>
Detailed descriptions of the parameters are explained in the following table:
| Variable | Data Type | Length | Mandatory | Description | Remark |
|---|---|---|---|---|---|
| version | Numeric | 5 | Y | Version of the Payment Request | 3.1 |
| timeStamp | Character | 22 | N | Date and time of request Message. (if empty, system will take the server received date time.) | Requst DateTime in format of "ddMMyyHHmmss" |
| merchantID | Character | 15 | Y | Merchant ID | Payment request merchant ID. Provided by 2C2P to merchant. |
| processType | Character | 2 | Y | Payment process command. I = Inquiry S = Settlement V = Void/Cancel R = Refund RS = Refund Status | Refund option availability depends on the bank and payment channel. |
| invoiceNo | Character | 50 | Y | Invoice No / order ID | Transaction unique invoice number. Generated by merchant. |
| actionAmount | Numeric | 13 | N | Refund / settle amount in 2 decimal format. Required only for Refund and Settlement request. | The amount should not exceed original transaction amount. If partial refund was made, the total refund amount (previous+current refund) should not exceed original transaction amount. Example: 1.00, 100.00, 1000.00 |
| bankCode | Character | 10 | N | Customer’s account’s bank code. | (Only applicable to APM transaction Refund request. NOT required for Malaysia.) |
| accountName | Character | 50 | N | Customer’s bank account name | (Only applicable to APM transaction Refund request. NOT required for Malaysia.) |
| accountNumber | Character | 50 | N | Customer’s bank account number | (Only applicable to APM transaction Refund request. NOT required for Malaysia.) |
| subMerchantList | Array | N | (Only applicable to MasterMerchant Account) | ||
| subMerchant subMID | hashValue | 15 | N | Sub Merchant ID Required only for Master Merchant Account | sub merchant’s MID provided by 2C2P. |
| subMerchant subAmount | Numeric | 13 | N | Refund / settle amount in 2 decimal format. Required only for Master Merchant Account | The total of subAmount(s) must match the action Amount. Example: 1.00, 100.00, 1000.00 |
| notifyURL | Character | 250 | N | URL to notify final refund status | will notify with the same format as ‘PaymentProcessResponse’ |
| hashValue | Character | 150 | Y | Hash value computed by HMACSHA1 with secret key provided by 2C2P System. |
Payment Action Response Parameters
Sample Response
<PaymentProcessResponse>
<version></version>
<timeStamp></timeStamp>
<respCode></respCode>
<respDesc></respDesc>
<processType></processType>
<invoiceNo></invoiceNo>
<amount></amount>
<status></status>
<approvalCode></approvalCode>
<referenceNo></referenceNo>
<transactionDateTime></transactionDateTime>
<paidAgent></paidAgent>
<paidChannel></paidChannel>
<maskedPan></maskedPan>
<eci></eci>
<subMerchantList>
<subMerchant subMID="" subAmount="" />
<subMerchant subMID="" subAmount="" />
</subMerchantList>
<refundList>
<refund referenceNo="" status="" amount="" dateTime=”” userDefined1="" ... userDefined5=""/>
<refund referenceNo="" status="" amount="" dateTime=”” userDefined1="" ... userDefined5=""/>
</refundList>
<paymentScheme></paymentScheme>
<processBy></processBy>
<hashValue></hashValue>
</PaymentProcessResponse>
Detailed descriptions of the parameters are explained in the following table:
| Variable | Data Type | Length | Mandatory | Description | Remark |
|---|---|---|---|---|---|
| version | Character | 5 | Y | Version of the Payment Action Request | 3.1 |
| timeStamp | Character | 22 | Y | Date and time of request Message | Request DateTime in format of "ddMMyyHHmmss" |
| respCode | Character | 2 | Y | Response code | Refer Result Code |
| respDesc | Character | 100 | Y | response code description | |
| processType | Character | 2 | Y | Payment process command. I = Inquiry S = Settlement V = Void/Cancel R = Refund RS = Refund Status | Refund inquiry availability depends on the bank and payment channel. |
| invoiceNo | Character | 50 | Y | Invoice No / order ID | Transaction unique invoice number. Generated by merchant. |
| amount | Numeric | 13 | N | Payment amount made by customer, or refund / captured amount | Example: 1.00, 100.00, 1000.00 |
| status | Character | 3 | Y | Status of the transaction requested | Refer Transaction Status Code |
| approvalCode | Character | 6 | N | Transaction Approval Code | Approval code provided by Credit Card Host or from WebPay provider. |
| referenceNo | Character | 30 | N | Reference number | trace no for credit card payment, RefNo1 for APM payment, Refund reference no when requesting Refund. |
| transactionDateTime | Character | 14 | N | Transaction Date Time value with 'yyyyMMddhhmmss' format | |
| paidAgent | Character | 30 | N | Agent Code that customer made payment with. | Refer Paid Agent List |
| paidChannel | Character | 30 | N | Channel Code that customer made payment with. | Refer [Paid Channel List] (doc:payment-action-references#section-paid-channel-list) |
| maskedPan | Character | 16 | N | Masked Credit Card Number | Masked Card Format based on merchant profile setting. • First 6 Last 4 (411111XXXXXX1111) • Last 4 (XXXXXXXXXXXX1111) |
| eci | Character | 3 | N | Transaction Approval Code from Credit Card Host | (only for creditcard payment) 3DS E-Commerce Indicator |
| subMerchantList | Array | N | (Only applicable to Master Merchant Account) | ||
| subMerchant subMID | Character | 15 | N | Sub Merchant ID Required only for Master Merchant Account | sub merchant’s MID provided by 2C2P. |
| subMerchant subAmount | Numeric | 13 | N | Refunded / settled amount in 2 decimal format. Required only for Master Merchant Account | Example: 1.00, 100.00, 1000.00 |
| refundList | Array | N | (Only applicable to Refund Status request) | ||
| refund referenceNo | Character | 30 | N | Reference number | Refund reference number returned by PGW when refund request was completed |
| refund status | Character | 3 | N | Status of the transaction requested | Refer to Transaction Status code |
| refund amount | Numeric | 13 | N | Payment amount made by customer, or refund / captured amount. | Example: 1.00, 100.00, 1000.00 |
| refund dateTime | Character | 14 | N | refund approval Date Time with yyyyMMddhhmmss format | |
| paymentScheme | Character | 2 | N | Card brand / Payment Scheme | Card brand or Payment Scheme of the payment VI - VISA MA - MASTER JC - JCB AM - AMEX DI - DINNER UP - Union Pay MP - MPU AL - ALIPAY LP - LINEPAY PA - PAYPAL AP - ALTERNATIVE PAYMENT WC - WECHAT Refer to Payment Scheme / Process by |
| processBy | Character | 2 | N | Payment Process By code | Payment processing network of the payment VI - VISA MA - MASTER JC - JCB AM - AMEX DI - DINNER UP - Union Pay MP - MPU AL - ALIPAY LP - LINEPAY PA - PAYPAL AP - ALTERNATIVE PAYMENT WC - WECHAT Refer to Payment Scheme / Process by |
| hashValue | Character | 150 | Y | Hash value computed by HMACSHA1 with secret key provided by 2C2P System. |
Card Tokenization Request Parameters
Sample Request
<MaintenanceRequest>
<version>2.3</version>
<timeStamp></timeStamp>
<merchantID></merchantID>
<storeCardUniqueID></storeCardUniqueID>
<pan></pan>
<panBank></panBank>
<panCountry></panCountry>
<panCurrency></panCurrency>
<cardholderName></cardholderName>
<cardholderEmail></cardholderEmail>
<panExpiry></panExpiry>
<action></action>
<hashValue></hashValue>
</MaintenanceRequest>
Detailed descriptions of the parameters are explained in the following table.
| Variable | DataType | Length | Mandatory | Description | Remark |
|---|---|---|---|---|---|
| Version | Character | 5 | Y | Version of the payment request | 2.3 |
| timeStamp | Character | 22 | N | Date and time of the maintenance request. (if empty, system will take server received date time.) | Requst DateTime in format of "ddMMyyHHmmss" |
| merchantID | Character | 15 | Y | Merchant ID | merchant ID provided by 2C2P to merchant. |
| storeCardUniqueID | Character | 20 | N | Unique ID of store card info. | Mandatory if action is not ‘A’. storeCardUniqueID as provided by processor previously. |
| panBank | Character | 50 | N | Credit Card Issuer Bank name. | Keyed in by Customer on the merchant website. Example: Siam Commercial Bank |
| panCountry | Character | 2 | N | Credit Card Issuer Bank Country Code | Selected country by Customer on the merchant website. Example: TH, SG (following ISO 3166-1 alpha 2) |
| cardholderName | Character | 50 | N | Cardholder Name | Keyed in by customer at merchant site. Only the following characters are allowed. -_,'.A-Za-z& |
| cardholderEmail | Character | 50 | N | Cardholder Email address | Keyed in by customer at merchant site. |
| panExpiry | Character | 4 | N | Credit Card Expiry | Credit Card Expiry in MMYY format (e.g 0215) |
| pan | Character | 19 | N | FULL Card Number | For “Add” request only |
| panCurrency | Character | 3 | N | Credit Card Primary Currency Code | 3 Numeric Currency Code e.g 764, 702 |
| action | Character | 1 | Y | Maintenance action command | A = Add I = Inquiry D = Delete U = Update |
| hashValue | Character | 150 | Y | Hash value computed by HMACSHA256 with secret key provided by 2C2P System. |
Card Tokenization Response Parameters
Sample Response
<MaintenanceResponse>
<version>2.4</version>
<timeStamp></timeStamp>
<merchantID></merchantID>
<respCode></respCode>
<respReason></respReason>
<panBank></panBank>
<storeCardUniqueID></storeCardUniqueID>
<panCountry></panCountry>
<cardholderName></cardholderName>
<cardholderEmail></cardholderEmail>
<panMasked></panMasked>
<hashValue></hashValue>
</MaintenanceResponse>
Detailed descriptions of the parameters are explained in the following table.
| Variable | DataType | Length | Mandatory | Description | Remark |
|---|---|---|---|---|---|
| Version | Character | 5 | Y | Version of the payment request | 2.4 |
| timeStamp | Character | 22 | Y | Date and time of the maintenance request. | Requst DateTime in format of "ddMMyyHHmmss" |
| merchantID | Character | 15 | Y | Merchant ID | Payment request merchant ID. Provided by 2C2P to merchant |
| respCode | Character | 2 | Y | The code whether The transaction is successful or not. | 00 = Success RespCode not 00 is failed. |
| respReason | Character | 100 | Y | Reason of failure | |
| panBank | Character | 50 | N | Credit Card Issuer Bank name | Keyed in by Customer on the merchant website. Example: Siam Commercial Bank |
| storeCardUniqueID | Character | 20 | Y | Unique ID of store card info. | storeCardUniqueID as provided by processor previously. |
| panCountry | Character | 2 | N | Credit Card Issuer Bank Country Code | Example: TH, SG (following ISO 3166-1 alpha 2) |
| cardholderName | Character | 50 | N | Cardholder Name | Keyed in by customer at merchant site. |
| cardholderEmail | Character | 50 | N | Cardholder Email address | Keyed in by customer at merchant site. |
| panMasked | Character | 19 | N | Masked Card Number | Masked Card Format based on merchant profile setting. • First 6 Last 4 (411111XXXXXX1111) • Last 4 (XXXXXXXXXXXX1111) |
| hashValue | Character | 150 | Y | Hash value computed by HMACSHA256 with secret key provided by 2C2P System. |
RPP (Recurring Payment Plan) Maintenance Request Parameters
Sample Request
<RecurringMaintenanceRequest>
<version></version>
<timeStamp></timeStamp>
<merchantID></merchantID>
<recurringUniqueID></recurringUniqueID>
<processType></processType>
<recurringStatus></recurringStatus>
<amount></amount>
<allowAccumulate></allowAccumulate>
<maxAccumulateAmount></maxAccumulateAmount>
<recurringInterval></recurringInterval>
<recurringCount></recurringCount>
<chargeNextDate></chargeNextDate>
<chargeOnDate></chargeOnDate>
<hashValue></hashValue>
</RecurringMaintenanceRequest>
Detailed descriptions of the parameters are explained in the following table.
| Variable | Data Type | Length | Mandatory | Description | Remark |
|---|---|---|---|---|---|
| version | Character | 5 | Y | Version of the Recurring Maintenance Request | 2.4 |
| timeStamp | Character | 22 | Y | Date and time of request Message | Request DateTime in format of "ddMMyyHHmmss" |
| merchantID | Numeric | 20 | Y | Merchant ID | merchant ID Provided by 2C2P to merchant. |
| recurringUniqueID | Numeric | 20 | Y | The unique id of recurring payment cycle | This id is returned by 2C2P to merchant for recurring payment request. |
| processType | Char | 1 | Y | Payment process command. I = Inquiry C = Cancel U = Update | |
| recurringStatus | Character | 1 | N | The active status of recurring payment cycle. The value is either Y (yes) or N (no). | Merchant can set ‘Y’ for active and ‘N’ for inactive. It is mandatory for Update Request. |
| amount | Numeric | 12 | N | Recurring amount in 12 digits leading zero format. | It is mandatory for Update Request. |
| allowAccumulate | Character | 1 | N | Allow accumulation if authorization failed. | Merchant can set ‘Y’ for yes and ‘N’ for no to allow accumulation in next recurring cycle. It is mandatory for Update Request. |
| maxAccumulateAmount | Numeric | 12 | N | Limit for the accumulate amount before terminate. Format is 12 digits leading zero format. | If the current accumulate amount exceeded the limitation, the recurring cycle will be terminated. It is mandatory for Update Request. |
| recurringInterval | Numeric | 5 | N | Recurring Interval in days NOTE : if this parameter is used, please do not passed in value for parameter chargeOnDate due to only 1 condition can be applied. | Charge card every x days. Max value 365(1 year). It is mandatory for Update Request. |
| recurringCount | Numeric | 5 | N | Recurring total count allowed. | Repeat this payment x times. Value ‘0’ for endless loop until terminated manually. It is mandatory for Update Request. |
| chargeNextDate | Character | 8 | N | The next date of recurring payment | Date in DDMMYYYY format. No value will be current date + recurring Interval. It is mandatory for Update Request. |
| chargeOnDate | Character | 8 | N | Charge On Date, format : ddMM NOTE : if this parameter is used, please do not passed in value for parameter recurringInterval due to only 1 condition can be applied. | Charge card on X day of the month. dd for Day, MM for Month. It is mandatory for Update Request when recurringInterval is NULL / EMPTY |
| hashValue | Character | 150 | Y | Hash value computed by HMACSHA256 with secret key provided by 2C2P System. |
RPP (Recurring Payment Plan) Maintenance Response Parameters
Sample Response
<RecurringMaintenanceResponse>
<version></version>
<timeStamp></timeStamp>
<respCode></respCode>
<respReason></respReason>
<recurringUniqueID></recurringUniqueID>
<recurringStatus></recurringStatus>
<invoicePrefix></invoicePrefix>
<currency></currency>
<amount></amount>
<maskedCardNo></maskedCardNo>
<allowAccumulate></allowAccumulate>
<maxAccumulateAmount></maxAccumulateAmount>
<recurringInterval></recurringInterval>
<recurringCount></recurringCount>
<currentCount></currentCount>
<chargeNextDate></chargeNextDate>
<chargeOnDate></chargeOnDate>
<hashValue></hashValue>
</RecurringMaintenanceResponse>
Detailed descriptions of the parameters are explained in the following table.
| Variable | Data Type | Length | Mandatory | Description | Remark |
|---|---|---|---|---|---|
| version | Character | 5 | Y | Version of the Recurring Maintenance Request | 2.4 |
| timeStamp | Character | 22 | Y | Date and time of request Message | Requst DateTime in format of "ddMMyyHHmmss" |
| respCode | Character | 3 | y | Response Code of recurring maintenance request. | 00 = success respCode not 00 is failed. |
| respReason | Character | 100 | N | Reason of Failure | |
| recurringUniqueID | Numeric | 20 | Y | The unique id of recurring payment cycle | |
| recurringStatus | Character | 1 | N | The active status of recurring payment cycle. The value is either Y (yes) or N (no). | |
| invoicePrefix | Characters | 15 | N | Invoice Prefix | |
| Currency | Numeric | 3 | N | payment currency in ISO4217 three Numeric code | Refer to Currency List |
| amount | Numeric | 12 | N | Recurring amount in 12 digits leading zero format. | |
| maskedCardNo | Character | 16 | N | Masked Credit Card Number | Masked Card Format based on merchant profile setting. • First 6 Last 4 (411111XXXXXX1111) • Last 4 (XXXXXXXXXXXX1111) |
| allowAccumulate | Character | 1 | N | Allow accumulation if authorization failed. | The value is ‘Y’ for yes and ‘N’ for no |
| maxAccumulateAmount | Numeric | 12 | N | Limit for the accumulate amount before terminate. Format is 12 digits leading zero format. | |
| recurringInterval | Numeric | 5 | N | Recurring Interval in days | Charge card everyx days. Max value 365(1 year). |
| recurringCount | Numeric | 5 | N | Recurring total count allowed. | Repeat this payment x times. Value ‘0’ for endless loop until terminated manually. |
| currentCount | Numeric | 5 | N | Current recurring count of recurring cycle. | |
| chargeNextDate | Character | 8 | N | The next date of recurring payment | Date in DDMMYYYY format. No value will be current date + recurring Interval. |
| chargeOnDate | Character | 8 | N | Charge On Date, ddMM | |
| hashValue | Character | 150 | Y | Hash value computed by HMACSHA256 with secret key provided by 2C2P System. |
IPP Option Request Parameters
Sample Request
<IppOptionRequest>
<version>2.3</version>
<timeStamp>041016180647</timeStamp>
<merchantID>JT</merchantID
<hashValue>478DBA0F2CAA63D22B6B214CE1CC6ACB467C6D1A</hashValue>
</IppOptionRequest>
Detailed descriptions of the parameters are explained in the following table.
| Variable | Data Type | Length | Mandatory | Description | Remark |
|---|---|---|---|---|---|
| version | Numeric | 5 | Y | Version of the Payment Request | |
| timeStamp | Character | 22 | N | Date and time of request Message. (if empty, system will take the server received date time.) | Requst DateTime in format of "ddMMyyHHmmss" |
| merchantID | Character | 15 | Y | Merchant ID | Payment request merchant ID. Provided by 2C2P to merchant. |
| hashValue | Character | 150 | Y | Hash value computed by HMACSHA256 with secret key provided by 2C2P System. |
IPP Option Response Parameters
Sample Response
<IppOptionResponse>
<version>2.3</version>
<timeStamp>041016180707</timeStamp>
<respCode>00</respCode>
<respReason>Success</respReason>
<ippBanks>
<ippBank>
<bankName>2C2P Simulator</bankName>
<bankShortName>SIMU</bankShortName>
<bankLogoUrl>https://d11fwxgc8zkidi.cloudfront.net/images/ippbanklogo/23.png</bankLogoUrl>
<bankPromoUrl>https://d11fwxgc8zkidi.cloudfront.net/images/ipppromologo/23.png</bankPromoUrl>
<bankTerms>Demo terms and conditions</bankTerms>
<bins>
<bin>300307</bin>
<bin>365988</bin>
</bins>
<installmentOptions>
<option id="1" installmentPeriod="10" merInterestRate="-1.00" cusInterestRate="1.00" minAmount="100.00" currencyCode="THB" validFrom="2016-03-01" validUntil="2022-03-31" />
</installmentOptions>
</ippBank>
<ippBank>
<bankName>Bangkok Bank</bankName>
<bankShortName>BBL</bankShortName>
<bankLogoUrl>https://d11fwxgc8zkidi.cloudfront.net/images/ippbanklogo/3.png</bankLogoUrl>
<bankPromoUrl>https://d11fwxgc8zkidi.cloudfront.net/images/ipppromologo/3.png</bankPromoUrl>
<bankTerms>TOC</bankTerms>
<bins>
<bin>411111</bin>
<bin>544485</bin>
</bins>
<installmentOptions>
<option id="1" installmentPeriod="3" merInterestRate="0.40" cusInterestRate="0.50" minAmount="1.00" currencyCode="THB" validFrom="2014-07-01" validUntil="2020-12-31" />
</installmentOptions>
</ippBank>
</ippBanks>
<hashValue>965C8DB713EF63FD50D86DA972BBD4C8E31659F6</hashValue>
</IppOptionResponse>
Detailed descriptions of the parameters are explained in the following table.
| Variable | Data Type | Length | Mandatory | Description | Remark |
|---|---|---|---|---|---|
| version | Character | 5 | Y | Version of the Payment Action Request | 2.3 |
| timeStamp | Character | 22 | Y | Date and time of request Message | Request DateTime in format of "ddMMyyHHmmss" |
| respCode | Character | 3 | Y | Response Code of payment request XML. Initial character of the response code represents payment request type. | 00 = success Response code not 00 is failed. |
| respReason | Character | 100 | N | Reason of Failure | |
| ippBanks | Array | N | Array of ippBank | ||
| bankName | Character | 250 | Y | IPP Bank Name | |
| bankShortName | Character | 250 | Y | Bank Short Name / Bank Code | |
| bankTerms | Character | - | Y | Terms and condition of Bank | |
| bankLogoUrl | Character | 250 | Y | Bank Logo URL | |
| bankPromoUrl | Character | 250 | Y | Bank Promo URL | |
| bins | Array | Array of bin | |||
| bin | Character | 6 | Y | Allow BIN | |
| installmentOptions | |||||
| option id | Numeric | 2 | Y | Serial No for Option | |
| option installmentPeriod | Numeric | 2 | Y | No of Months IPP Period | |
| option merInterestRate | decimal | 2,2 | Y | Merchant Pay Interest Rate | Negative value means there is no option for merchant pay interest |
| option cusInterestRate | decimal | 2,2 | Y | Customer Pay Interest Rate | Negative value means there is no option for customer pay interest |
| option minAmount | decimal | 2,2 | Y | Minimum amount to be Eligible for IPP | |
| option currencyCode | Character | 3 | Y | Payment Currency to be eligible for IPP | in 3 Char Currency Code. e.g THB, SGD |
| option validFrom | date | 10 | Y | Option valid from Date format: yyyy-MM-dd | |
| option validUntil | date | 10 | Y | Option valid Until Date format: yyyy-MM-dd | |
| hashValue | Character | 150 | Y | Hash value computed by HMACSHA256 with secret key provided by 2C2P System |
Updated almost 3 years ago