EC Payment API Specification

 

1. Introduction 

The DAO’s e-Commerce Payment Service (or simply the “e-Commerce Payment Service”) provides an efficient, secure and easy-to-use payment integration solution to enable merchant systems with online payment capability.  Built on top of The DAO Platform (referred subsequently in this document as “Payments Platform”), the e-Commerce Payment Service enables online payments to be conducted with high speed and high security.

 

This document provides technical guidelines on the use of the Application Programming Interface (API) for merchant system integration and describes the API specification in details.

1.1.Abbreviation

Overview of e-Commerce Payment Service

1.2.Payment Transaction Flow

The DAO’s e-Commerce Payment Service is a real-time payment transaction service which transfers funds between cardholder’s account and the merchant’s financial institution securely over the Internet.  An e-Commerce payment process flow usually involves four main parties, namely the Cardholder, the Merchant System, the Payments Platform, and the Financial Institution.

The e-Commerce Payment Service API is a simple-to-use and secure payment service interface which allows the merchant to integrate real-time payment capability into its system with minimal development effort.

The Merchant System communicates with the e-Commerce Payment Service via a secure communication channel over the Internet with the industry security standard of 256-bit SSL encryption.  By leveraging the Internet infrastructure, no additional cost on dedicated network infrastructure is required by the merchant.

The basic payment transaction flow is depicted below:

  1. Merchant System prepares the required payment transaction parameters which form a Digital Order (DO) with a digital signature.

  2. Merchant System calls the e-Commerce Payment Service API to initiate a payment request with the DO.

  3. The DO is passed to the Payments Platform, either directly or indirectly depending on the Integration Model used (which is covered in the later section) over a secure channel.

  4. Upon receiving the DO, the Payments Platform authenticates the request, and performs data integrity validation.  It will then process the payment request with the Financial Institution.

  5. Payments Platform generates a Digital Receipt (DR) with digital signature and returns the payment result to the Merchant System. 

  6. Merchant System authenticates the DR, validates the data integrity and retrieves the payment transaction result.

  7. Merchant System proceeds with its business logic according to the payment transaction result. 

The e-Commerce Payment Service provides a “Query Transaction” API which returns the final transaction status of a previously submitted transaction request.  It is highly recommended for the Merchant System to make a “Query Transaction” request against any transaction which has uncertain status (e.g. due to timeout caused by network problem, etc.).

1.3.Communication Interface

HTTPS POST method is used as the communication method between the merchant systems and the Payments Platform.  For merchant systems, there is no special requirement on the supported platform or development languages.  Its implementation can be done with any popular programming language (such as Java, ASP.NET, PHP, etc.) as long as the communication protocol (HTTPS) is supported.

For character encodings, Unicode is the standard when transmitting messages between the merchant systems and the Payments Platform.

1.4.Transaction Security Measures

The e-Commerce Payment Service incorporates a highly secure design which provides data confidentiality, message integrity and authenticity for the entire payment transaction process.

 

Data confidentiality is provided by highly secure encryption technology.  The e-Commerce Payment Service is provisioned via a highly secure payment infrastructure where secure web services are incorporated with 256-bit SSL support.  Merchant System communicates with the e-Commerce Payment Service via a secure communication channel over the Internet with the industry security standard of 256-bit SSL encryption.  Data communicated among the parties in the process is securely encrypted, and only the targeted party is able to decrypt and access the data properly.  Sensitive transaction data is properly encrypted by industrial best practice cryptographic standards with Hardware Secure Model (HSM).

 

The e-Commerce Payment Service incorporates a secure design of Digital Order (DO) and Digital Receipt (DR) for the transaction communication process.  A digital signature, based on the industrial security standard HMAC-SHA1 (Hash-based Message Authentication Code – SHA1), is incorporated into the Digital Order and Digital Receipt.   A Digital Order is the payment transaction request order with a digital signature generated by the merchant system, whereas a Digital Receipt is the payment transaction response with a digital signature generated by the Payments Platform.  A HMAC verification process of the digital signature with the order information can validate whether the order has been altered during the process and also verify if the order is generated from the genuine sender.  In essence, this provides the message integrity and authenticity.

 

The Payments Platform can also provide additional security control by supporting access control based on the merchant profile, user profile, and IP address.

2. Overview of System Integration 

2.1.Required Information for System Integration and Certification

Merchant will be provided with the following information for the sake of carrying out system integration with the Payments Platform’s testing system.

As part of the quality assurance process, merchants are requested to carry out Certification Test on the Payments Platform’s testing system, in cooperation with the support personnel, prior to connecting to the Live system of the Payments Platform.  This is to ensure a smooth and flawless communication and transaction data flow between the Merchant System and the Payments Platform.  A new set of the above information for the Live merchant account will be released to the merchant upon successful completion of the Certification Test.

2.2 Transaction Integration Models

A transaction integration model refers to the way that the Cardholder, the Merchant System, and the Payments Platform interact during the payment transaction process.

The e-Commerce Payment Service supports two different Transaction Integration Models, which provide the flexibility for merchants to control how to process a payment transaction and receive the transaction result.  These Transaction Integration Models are:

  1. Secure Direct Transaction Integration Model (SDTIM)

  2. Secure 3-Way Transaction Integration Model (S3TIM)

 

  • Secure Direct Transaction Integration Model (SDTIM)

In this model, Merchant System connects to the Payments Platform directly over SSL secure channel.   Merchant System gathers the required payment information from the customer and submits the Digital Order (DO) to the Payments Platform directly.  The Payments Platform processes the DO, and returns a Digital Receipt (DR) to the Merchant System directly over SSL secure channel (refer to Section 3 for more details).

SDTIM is applicable to Merchant System which is not a web-oriented application, and the merchant acts on behalf of the customer to initiate the payment, e.g. MOTO (Mail Order / Telephone Order) transaction in a Call Centre environment.

Therefore, SDTIM cannot support 3D-Secure mechanism (e.g. Verified-by-VISA®, MasterCard SecureCode®) which requires the online interaction with the cardholder.

  • Secure 3-Way Transaction Integration Model (S3TIM)

This model provides a 3-party interaction among the Cardholder, the Merchant System and the Payments Platform.  In this model, the payment request is initiated by the Merchant System, and is redirected via the Cardholder’s browser and sent to the Payments Platform.  Credit card information can be either:

  • passed from the Merchant System (refer to Section 3.2); or

  • collected from the cardholder via the Payments Platform’s Hosted Payment Page (refer to Section 3.3).

In this model, 3D-Secure mechanism (e.g. Verified-by-VISA®, MasterCard SecureCode®), which requires the online interaction with the cardholder, can be supported in this model.

3. Transaction Integration Models 

3.1.Secure Direct Transaction Integration Model

The transaction flow for Secure Direct Transaction Integration Model (SDTIM) is depicted in Figure 3-1.  The merchant application can be either a web-based application or any back-end application, which connects to the Payments Platform via HTTPS POST.

SDTIM.png

Figure 3-1: Transaction flow in Secure Direct Transaction Integration Model

The Process Flow (for Payment Services: Sale / Authorization):

  1. Merchant application gathers cardholder’s card details.  Depending on the merchant’s application, the card information may be retrieved from its own database or gathered from the cardholder during the transaction process.

  2. Merchant application submits the payment request in the form of a Digital Order (DO) to Payments Platform.

  3. Payments Platform processes the DO.

  4. Payments Platform returns the result as a Digital Receipt (DR) to the merchant application, which proceeds with its business logic in accordance with the payment result.

The Process Flow (for Advanced Merchant Services API: Capture, Void, Refund, Query Transaction, Query Card Information, and Generate Card Token):

  1. Merchant application prepares the related transaction information in the form of Digital Order (DO).

  2. Merchant application submits the DO to Payments Platform.

  3. Payments Platform processes the DO.

  4. Payments Platform returns the result as a Digital Receipt (DR) to the merchant application, which proceeds with its business logic in accordance with the transaction result.

Secure 3-Way Transaction Integration Model with Card Information

The transaction flow for a Sale / Authorization transaction with card information is depicted in Figure 3-2.  In this scenario, the card information is collected by the merchant’s Payment Page.

Secure 3-way Transction Integration Mode

Figure 3-2: Sale Transaction Flow with Card Information in Secure 3-Way Transaction Integration Model

The Process Flow:

  1. Cardholder submits the order request to the merchant application.

  2. Merchant Payment Page is displayed for Cardholder to input card information.

  3. Card information is submitted to the merchant application.

  4. Transaction with card information is sent to Payments Platform in the form of a Digital Order (DO) by HTTPS redirection via cardholder’s browser.

  5. If 3D-Secure is enabled, card information is redirected to ACS (Access Control Server) for Card Issuer’s processing.

  6. 3D-Secure Authentication Page is displayed for Cardholder to input 3D-Secure Password.

  7. 3D-Secure Password is submitted to ACS for authentication.

  8. 3D-Secure authentication result is redirected to Payments Platform.

  9. Payments Platform processes the Sale order and redirects the result as a Digital Receipt (DR) to the merchant application.

  10. Merchant application retrieves the output fields from the returned DR. and displays the Result Page to Cardholder.

Secure 3-Way Transaction Integration Model without Card Information

The transaction flow for a Sale / Authorization transaction without card information is shown in Figure 3-3.  In this scenario, the card information is collected by the Payments Platform’s Hosted Payment Page.

Secure 3 Way Transaction integration wit

Figure 3-3: Sale Transaction Flow without Card Information in Secure 3-Way Transaction Integration Model

The Process Flow:

  1. Cardholder submits the order request to the merchant application.

  2. Transaction without card information is sent to Payments Platform in the form of a Digital Order (DO) by HTTPS redirection via cardholder’s browser.

  3. Payments Platform’s Hosted Payment Page is displayed to cardholder to input card information.

  4. Cardholder submits card information to Payments Platform.

  5. If 3D-Secure is enabled, card information is redirected to ACS (Access Control Server) for Card Issuer’s processing.

  6. 3D-Secure Authentication Page is displayed for cardholder to input 3D-Secure Password.

  7. 3D-Secure Password is submitted to ACS for authentication.

  8. 3D-Secure authentication result is redirected to Payments Platform.

  9. Payments Platform processes the Sale order and redirects the result as a Digital Receipt (DR) to the merchant application.

  10. Merchant application retrieves the output fields from the returned DR, and displays the Result Page to Cardholder.

4. e-Commerce Payment Service API 

4.1 Purpose and Usage

The e-Commerce Payment Service provides a set of Payment Service APIs for the Merchant System to manage and process a payment order.

The table below provides a high-level description for the purpose and usage of each Payment Service API, as well as the supported Transaction Integration Model(s) for each of them.

Merchant System should send the Digital Order (DO) via a FORM POST to the Payment Service API URL of the Transaction Integration Model that is used (e.g. for SDTIM: https://txn1.atn.network/ecommerce-web/pay2p).  The exact Payment Service API URLs for connecting to the Live system of Payments Platform, and all the other merchant account information, will be provided by the PSP at the time when the Live merchant account is released to the merchant.

4.2 List of Applicable Data Fields for Each API

11.JPG
22.JPG
33.JPG

5. Definition of Data Fields 

6. Implementation Details 

6.1.Secure Hash Code

Secure hash code can be generated by the Merchant System to allow the Payments Platform to perform integrity checking of the transaction requests.

HMAC-SHA1 (Hash-based Message Authentication Code – Secure Hash Algorithm-1) symmetric-key hashing algorithm is used.  The generated hash code has 160 bits, which is then hex-encoded into 40 characters for transmission.

A hash key of maximum 32 bytes (all in ASCII) is kept at both the Merchant System and the Payments Platform.  The hash key has to be stored securely in database or file with proper permissions and must not be stored within program code.  The hash key can also be changed in the Payments Platform instantly.

The hash input value for the HMAC function should be built as below:

  1. All input field values are concatenated in ascending alphabetical order of the field names.

  2. All values are concatenated without separator and terminating character.

For example:

4.JPG

6.2. Payment Type

6.2.1.Supported Integration Models for Each Payment Type

The API parameter “pay_type” is used to specify the requested payment types of the transaction.  Table 6-1 below shows the payment types that are currently supported in the Payments Platform, as well as the applicability of Transaction Integration Model(s) and card tokenization service for each of them.

Table 6-1: Supported Payment Types in the Payments Platform

 

Payment type code “CC” can be used to specify multiple credit card payment types (e.g. VC, MC, JC, AE, and DC) so that there is no need to specify each of them explicitly.

 

If the “pay_type” parameter is blank, it means all the payment types that are accepted by the merchant are included.  In a S3TIM transaction, if “pay_type” is specified as blank and the merchant accepts more than one payment type (e.g. Visa, MasterCard, American Express, etc.), the Payments Platform’s will display the Payment Type Selection Page for the cardholder to choose the payment type for the transaction.  A sample of the Payment Type Selection Page is shown below.

5.png

Figure 6-2: Sample Payment Type Selection Page in the Payments Platform

 

On the other hand, if the merchant accepts only one payment type, that payment type will be used automatically without displaying the Payment Type Selection Page.

6.2.2. Supported Payment Service APIs for Each Payment Type

The table below shows the Payment Service APIs that are currently supported for each payment type.

111.JPG
222.JPG

Please note that, for credit card payment types (e.g. VC, MC, JC, AE, and DC), although the Payment Platforms supports both “Void” and “Refund” (full refund and/or partial refund) for these payment types, the availability of these functions is subject to the acquiring institutions (such as acquiring bank or payment processor) that process the transactions.  For example, some acquirers do not support “VOID_AUTH” (though AUTH_CARD and AUTH_ONLY are supported); whereas some acquirers do not support partial refund (though full refund using REFUND_ORDER is supported).  Please consult the PSP about the availability of the functions on a case-by-case basis.

6.3. Sample Code

This section provides some examples of HTML/XML code to illustrate the content of the transaction requests (i.e. Digital Orders) in the following scenarios:

 

  • A “Sale” transaction initiated from a Merchant-hosted payment page (i.e. using SALE_CARD function in the SDTIM model) – refer to Sections 6.3.1 and 6.3.2

  • A “Sale” transaction initiated from the Merchant System and using the Payments Platform’s Hosted Payment Page (i.e. using SALE_ONLY function in the S3TIM model) – refer to Sections 6.3.3 and 6.3.4

  • A “Void Sale” transaction initiated from the Merchant System (applicable to the SDTIM model only) – refer to Section 6.3.5

  • A “Generate Card Token” request initiated from the Merchant System (applicable to the SDTIM model only) – refer to Section 6.3.6

  • An “Authorization” transaction initiated from a Merchant-hosted payment page using a previously returned card token in the SDTIM model – refer to Section 6.3.7

  • A “Capture” transaction initiated from the Merchant System (applicable to the SDTIM model only) – refer to Section 6.3.8

  • A “Refund” transaction initiated from the Merchant System (applicable to the SDTIM model only) – refer to Section 6.3.9

  • A “Query Transaction” initiated from the Merchant System (applicable to the SDTIM model only) – refer to Section 6.3.10

  • A “Payout” transaction initiated from the Merchant System – refer to Section 6.3.11

  • A “Verify Card Token” transaction initiated from the Merchant System – refer to Section 6.3.12

  • A “Query Balance” transaction initiated from the Merchant System – refer to Section 6.3.13

6.3.1.Sample Code for SALE_CARD in SDTIM Model (No Secure Hash Code)

 

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

6.3.2.Sample Code for SALE_CARD in SDTIM Model (with Secure Hash Code)

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

6.3.3.Sample Code for SALE_ONLY in S3TIM Model (No Secure Hash Code)

Sample Transaction Request (Digital Order)

6.3.4.Sample Code for SALE_ONLY in S3TIM Model (with Secure Hash Code)

Sample Transaction Request (Digital Order)

6.3.5.Sample Code for VOID_SALE in SDTIM Model

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

6.3.6.Sample Code for GEN_TOKEN in SDTIM Model​

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

6.3.7.Sample Code for AUTH_CARD Using Card Token in SDTIM Model

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

6.3.8.Sample Code for CAP_AUTH in SDTIM Model

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

6.3.9.Sample Code for REFUND_ORDER in SDTIM Model

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

6.3.10.Sample Code for WUERY_TXN in SDTIM Model

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

6.3.11.Sample Code for PAYOUT

6.3.11.1 Sample Code for PAYOUT (Debit Card) - 2 way

Sample Transaction Response (Digital Receipt)

6.3.11.2.Sample Code for PAYOUT (Debit Card) - 3 way

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

6.3.12.Sample Code for VER_TOKEN in SDTIM Model

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

6.3.13.Sample Code for QUERY_BAL in SDTIM Model

Sample Transaction Request (Digital Order)

Sample Transaction Response (Digital Receipt)

7. Known Issues for the e-Commerce Payment Service API

7.1.iframe Support Issue in Secure 3-Way Integration

When integration is using the iframe (html tag) to include the payment page for performing a Secure 3-way transaction, it is found that the payment cannot be done because there will be “third party cookies” warning which blocks the transaction to go through.  The end user needs to allow the “third party cookies” in the web browser before the transaction can be performed.

 

Suggestion is to redirect the whole page to external instead of just redirecting the html inside the frame.

8. Appendices 

8.1 Appendix A – Payment Service API Response Codes

8.2. Appendix B – English Country Names and Code Elements

The following table shows the mapping of the Country Names (official short names in English) in alphabetical order as given in ISO 3166-1 and the corresponding ISO 3166-1-alpha-2 Code.

 
 
 
 
 
 
 

8.3. Appendix C – China Bank Names and Bank Code