banner bkgd.png

DOCUMENTATION

Asynchronous Notification Merchant Implementation Guide

version 2.0 | publishing date: 10/07/2019 
1. Introduction

Octo3’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 Octo3 Platform, the e-Commerce Payment Service enables online payments to be conducted with high speed and high security.

This document provides technical guidelines on setting up Octo3 Platform’s asynchronous notification via HTTP/HTTPS POST method and describes the specifications in detail.

2. Required Information for Asynchronous Notification

Merchant are required to provide the data feed URL to the Payment Service Provider. Once set up, the Octo3 platform will deliver the notification data to the URL provided. Please make sure there is no firewall rule denying Octo3 platform for access to this URL.

3. Notification Flow

The process flow for asynchronous notification is depicted in Figure 1. The Payments Platform delivers the asynchronous notification via HTTP/HTTPS POST method.

Async Notification (1).png
 
 
 
  1. When the status of a transaction is marked as “ACCEPTED”, "FAILED", "REJECTED", "DECLINED", "VOIDED", "ERROR", and "CANCELLED", Octo3 Platform sends notifications data to the URL provided by Merchant.

  2. Merchant receives the asynchronous notification and return a plain text response with text “ACK” to Octo3 Platform for all status (refer to above item (1)).

  3. Octo3 Platform marks the transaction as successfully notified.

  4. If Octo3 Platform does not receive the text “ACK”, it will actively retry until reaching the maximum failure rate.

Sample form post of asynchronous notification

Asynchronous notification is using HTTP/HTTPS form post method to notify merchant. Here is the sample of HTTPS form post message to merchant data feed URL:

List of Applicable Data Fields
No.
Field Name
Mandatory
1
version
M
2
action
M
3
merch_order_id
M
4
merch_id
M
5
term_id
M
6
pay_type
O
7
currency
M
8
card_num
C
9
merch_txn_id
O
10
locale
O
11
merch_data
O
12
secure_hash
C
13
bill_to_first_name
C
14
bill_to_last_name
C
15
bill_to_company
C
16
bill_to_street
C
17
bill_to_street2
C
18
bill_to_city
C
19
bill_to_state_code
C
20
bill_to_postal_code
C
21
bill_to_country_code
C
22
ship_to_first_name
C
23
ship_to_last_name
C
24
ship_to_company
C
25
ship_to_street
C
26
ship_to_street2
C
27
ship_to_city
C
28
ship_to_state_code
C
29
ship_to_postal_code
C
30
ship_to_country_code
C
31
pay_item
O
32
txn_time
M
33
txn_status
M
34
txn_response_code
M
35
dr_count
M
36
txn_message
O
37
txn_no
O
38
batch_no
O
39
acq_response_code
O
40
auth_id
O
41
receipt_no
O
42
authorized_amount
O
43
captured amount
O
44
refunded amount
O
45
original_amount
C
46
vat rate
C
47
vat amount
C
48
accept time
C
49
bill_to_email_address
C
50
customer ip address
C
Mandatory Notes
Abbrev.
Meaning
M
Mandatory Field
O
Optional Field
C
Conditional Field