API integration

With assuming you have information authorization token via 3DS Authentication TMS, we shall inform below, regarding Payment Service API integration.※ Parameters and fields stated in the document are required values.

Merchant verification

You should request Payment Service by consisting Header, with authorizationId that can be received after 3DS authentication completed, and received data after below merchant verification succeeded, so that you may use payment(approval and other services).

Request Authentication Code

Live Request URL : GEThttps:/pay.opt-pay.com/authorize
Test Request URL : GEThttps:/test-pay.opt-pay.com/authorize

Sample Code

import axios from "axios"

            class Api extends React.Component {
                const handleSubmit = async ( ) => {
                        try {
                            const response = await axios.get("https:/test-pay.opt-pay.com/authorize", {
                                headers: {
                                  'Content-type': "application/json",
                                  'clientCode': "clientCode",
                                  'clientSecret': "clientSecret"
                                }
                            }
                            console.log(response);
                        } catch(e){
                            console.error(e);
                        }
                    render() {
                        (...)
                    );

Request Header

Header	Type	Description
clientCode	String	Provided Client code
clientSecret	String	Provided Client password

Response Data

Header	Type	Description
Authorization	String	Merchant verification code

Payment request

Service that verifies customer’s identity before payment, and only authorized customer may use the payment service. The authorization shall process via browser, and the result would be sent to CallbackLocation separately, and process page move to redirectUrl. Module shall not provide UI.

URL

Live : POST https://pay.opt-pay.com/order/start
Test : POST https://test-pay.opt-pay.com/order/start

Content-Type

x-www-form-urlencoded

Description of CallbackLocation

This is the URL to receive the final result after the payment is completed. If partner company has a firewall, you need to allow Optatum Server IP 112.175.117.124 and Port 80, 443.

precaution

The request must be made as Form submit in a web browser. UI for integration shall NOT be provided from Optatum, partner company should provide the UI.※ Requests other than Form submit are not allowed

Sample Code

<form method="post" action="https://test-pay.opt-pay.com/order/start"> 
            
                <input type="text" name="merchantId" value="">
                <input type="text" name="merchantReferenceCode" value="Payment Authenticate sample Test">
                <input type="text" name="currency" value="USD">
                <input type="text" name="cardAccountNumber" value="5200000000001096">
                <input type="text" name="cardType" value="MASTER">
                <input type="text" name="cardExpirationMonth" value="01">
                <input type="text" name="cardExpirationYear" value="2023">
                <input type="text" name="firstName" value="John">
                <input type="text" name="lastName" value="Doe">
                <input type="text" name="country" value="KR">
                <input type="text" name="state" value="">
                <input type="text" name="city" value="busan">
                <input type="text" name="address" value="optatumbuilding, 61, Geumjeong-ro, Geumjeong-gu, Busan, Republic of Korea">
                <input type="text" name="postalCode" value="46293">
                <input type="text" name="phone" value="+8212341234">
                <input type="text" name="email" value="test@test-email.com">
                <input type="text" name="callbackLocation" value="">
                <input type="text" name="redirectUrl" value="">
                <input type="text" name="isWindowed" value="N">
                <input type="text" name="isRedirect" value="N">
                <input type="text" name="isAuthenticate" value="Y">
                <input type="text" name="verifyId" value="">
                <input type="text" name="authorization" value="">
                <input type="text" name="amount" value="100">
          
                <button type="submit">Submit</button>
          
          </form>

isRedirect : Y - process Redirect when 3DS Authentication failed / N(default value) – Not moving when 3DS Authentication failed
isWindowed : Y - process authorization with new window / N(default value) – process authorization by moving page
isAuthenticate : Y(default value) – process payment approval / N – process only authorization

Request Form Fields

Field	Type	Description
merchantId	String	merchant MID
merchantReferenceCode	String	field to manage transaction history from merchant
currency	String	Currency code (ISO 4217 refer, “3 digits”)
cardAccountNumber	Number	Card Number Test Ex) VISA 4000000000001091 MASTER 5200000000001096 JCB 3569960010083758
cardType	String	Card company Ex)VISA, MASTER, JCB
cardExpirationMonth	String	Card expiration month(MM) Test Ex) 01
cardExpirationYear	String	Card expiration year(YYYY) Test Ex) Current Year + 3
firstName	String	First name of customer
lastName	String	Last name of customer
country	String	Country code (refer ISO 3166-1 alpha-2 , “2 digit)
state	String	state (only in case of U.S.A. and Canada)
city	String	City
address	String	Address
postalCode	String	Post code (zip code)
phone	String	Customer contact
email	String	Customer E-mail
callbackLocation	String	Server URL to receive results URL address must end with “/”.
redirectUrl	String	URL to go to after completing 3DS authentication. URL address must end with “/”.
isWindowed	String	Option default: Y (available only “Y” or “N”) N : page move \| Y : new page Going back when N Perform closing page when Y
isRedirect	String	Option Default: N (“Y” or “N” only) If Y, Redirect is executed even when 3DS fails.
verifyId	String	Provided Merchant code
authorization	String	Merchant verification code
isAuthenticate	String	Option Default: N (only “Y” or “N” can be used) If Y, payment approval is in progress.

Response Data

Field	Type	Description
decision	String	Result value (ACCEPT/REJECT)
reasonCode	String	Result code / when succeed 100
transactionId	String	transaction ID
originalTransactionId	String	Original transaction ID
When payment is not approved (isAuthenticate = “N”)
xid	String	3DS MPI Transaction ID
eci	String	3DS authentication result value
commerceIndicator	String	3DS certification results
cavvAlgorithm	String	3DS authentication result
paresStatus	String	3DS authentication result
paSpecificationVersion	String	3DS authentication result (if any)
directoryServerTransactionID	String	3DS authentication result (if any)
cavv	String	Cavv generated by 3DS issuer (Not applicable for MASTERCARD)
ucafCollectionIndicator	String	3DS certification results (MASTERCARD only)
ucafAuthenticationData	String	3DS certification results (MASTERCARD only)

Reverse, Capture, Refund

URL

Reverse Request URL : POST /reverse
Capture Request URL : POST /capture
Refund Request URL : POST /refund

Sample Code

import axios from "axios"

            class Api extends React.Component {
                    const submitData = {
                        merchantId: "test_merchant_id",
                        merchantReferenceCode: "test_merchant_reference_code",
                        currency: "USD",
                        amount: "1",
                        email: "payment@optatumplatform.com",
                        originalTransactionId: "100000000000001"	
                    };
                const handleSubmit = async ( ) => {
                        try {
                            const response = await axios.post("https:/test-pay.opt-pay.com/[Request URL]", submitData, {
                                headers: {
                                  'Content-type': "application/json",
                                  'verifyId': "verifyId",
                                  'Authorization': "Authorization"
                                }
                            }
                            console.log(response);
                        } catch(e){
                            console.error(e);
                        }
                    render() {
                        (...)
                    );

Request Fields

Field	Type	Description
merchantId	String	Merchant ID
merchantReferenceCode	String	Merchant’s reference code of transaction history
currency	String	Currency code (ISO 4217, 3digits)
amount	Number	Amount
email	String	customer Email
originalTransactionId	String	Original transaction ID

Response Fields

Field	Type	Description
decision	String	Result value (ACCEPT/REJECT)
reasonCode	String	Result code
transactionId	String	transaction ID
originalTransactionId	String	Original transaction ID

Void

URL

Void Request URL : POST /void

Sample Code

import axios from "axios"

            class Api extends React.Component {
                    const submitData = {
                        merchantId: "test_merchant_id",
                        merchantReferenceCode: "test_merchant_reference_code",
                        currency: "USD",
                        amount: "1",
                        email: "payment@optatumplatform.com",
                        transactionId: "100000000000001",
                        type: "CAPTURE",	
                    };
                const handleSubmit = async ( ) => {
                        try {
                            const response = await axios.post("https:/test-pay.opt-pay.com/void", submitData, {
                                headers: {
                                  'Content-type': "application/json",
                                  'verifyId': "verifyId",
                                  'Authorization': "Authorization"
                                }
                            }
                            console.log(response);
                        } catch(e){
                            console.error(e);
                        }
                    render() {
                        (...)
                    );

Request Fields

Field	Type	Description
merchantId	String	Merchant ID
merchantReferenceCode	String	Merchant’s reference code of transaction history
currency	String	Currency code (ISO 4217, 3digits)
amount	String	Amount
email	String	customer Email
transactionId	String	Request ID
type	String	request TransactionId’s transaction status only CAPTURE or REFUND

Response Fields

Field	Type	Description
decision	String	Result value (ACCEPT/REJECT)
reasonCode	String	Result code
transactionId	String	transaction ID
originalTransactionId	String	Original transaction ID

Payment Retrieve

URL

Live URL https://pay.opt-pay.com/payment/retrieve/[Merchant ID]/[Transaction ID]
Test URL https://test-pay.opt-pay.com/payment/retrieve/[Merchant ID]/[Transaction ID]

Sample Code

import axios from "axios"

            class Api extends React.Component {
                const handleSubmit = async ( ) => {
                        try {
                            const response = await axios.get("https:/test-pay.opt-pay.com/payment/retrieve/test_merchant_id/100000000000001", {
                                headers: {
                                  'Content-type': "application/json",
                                  'verifyId': "verifyId",
                                  'Authorization': "Authorization"
                                }
                            }
                            console.log(response);
                        } catch(e){
                            console.error(e);
                        }
                    render() {
                        (...)
                    );

Transaction History Inquiry Response

Field	Type	Description
merchantReferenceCode	String	Merchant’s transaction history reference code
transactionId	String	Transaction ID
originalTransactionId	String	Original transaction ID
step	String	Transaction request division
reasonCode	String	Reason code
status	String	Request result (successful/declined/error)
captureStatus	String	Payout service status (only when payout)
message	String	Result message
approvalCode	String	Approval number
cardType	String	Card company
currencyCode	String	Currency code (ISO 4217, 3 digits)
amount	Number	amount
cardPrefix	String	Card front number(except MASTERCARD)
cardSuffix	String	Card back number

Transaction History Inquiry payout status detail(CaptureStatus)

Status Value	Type	Description
PENDING	String	The authorization was captured, the credit request was successful, or the credit card transaction was captured, and the request was sent to the payment processor. The reply from the payment processor is pending.
TRANSMITTED	String	The Capture/Credit request was successfully sent to the Processor.
VOIDED	String	The request for the credit card capture, credit card credit, check debit, or check credit was successfully deleted. The authorization has not been deleted. You can see this transaction only on the search results page and in the exported search results.
TRXN_ERROR	String	There was an error processing this transaction at the Processor.

Reason Code

Transaction History Inquiry Response Detail(reasonCode)

Reason Code	Reply Flag (SCMP)	Description
100	SOK	Successful transaction
101	DMISSINGFIELD	Declined - The request is missing one or more fields
102	DINVALIDDATA	Declined - One or more fields in the request contains invalid data.
104	DDUPLICATE	Declined - The merchantReferenceCode sent with this authorization request matches the merchantReferenceCode of another authorization request that you sent in the last 15 minutes.
110	SPARTIALAPPROVAL	Partial amount was approved
150	ESYSTEM	Error - General system failure.
151	ETIMEOUT	Error - The request was received but there was a server timeout. This error does not include timeouts between the client and the server.
152	ETIMEOUT	Error: The request was received, but a service did not finish running in time.
200	DAVSNO	Soft Decline - The authorization request was approved by the issuing bank but flagged by CyberSource because it did not pass the Address Verification Service (AVS) check.
201	DCALL	Decline - The issuing bank has questions about the request. You do not receive an authorization code programmatically, but you might receive one verbally by calling the processor.
202	DCARDEXPIRED	Decline - Expired card. You might also receive this if the expiration date you provided does not match the date the issuing bank has on file.
203	DCARDREFUSED	Decline - General decline of the card. No other information provided by the issuing bank.
204	DCARDREFUSED	Decline - Insufficient funds in the account.
205	DCARDREFUSED	Decline - Stolen or lost card.
207	DCARDREFUSED	Decline - Issuing bank unavailable.
208	DCARDREFUSED	Decline - Inactive card or card not authorized for card-not-present transactions.
209	DCARDREFUSED	Decline - card verification number (CVN) did not match.
210	DCARDREFUSED	Decline - The card has reached the credit limit.
211	DCARDREFUSED	Decline - Invalid Card Verification Number (CVN).
220	DCHECKREFUSED	Decline - Generic Decline.
221	DCHECKREFUSED	Decline - The customer matched an entry on the processor's negative file.
222	DCHECKREFUSED	Decline - customer's account is frozen
230	DCV	Soft Decline - The authorization request was approved by the issuing bank but flagged by CyberSource because it did not pass the Card Verification Number (CVN) check.
231	DINVALIDCARD	Decline - Invalid account number
232	DINVALIDDATA	Decline - The card type is not accepted by the payment processor.
233	DINVALIDDATA	Decline - General decline by the processor.
234	DINVALIDDATA	Decline - There is a problem with your merchant configuration.
235	DINVALIDDATA	Decline - The requested amount exceeds the originally authorized amount. Occurs, for example, if you try to capture an amount larger than the original authorization amount.
236	DINVALIDDATA	Decline - Processor failure.
237	DINVALIDDATA	Decline - The authorization has already been reversed.
238	DINVALIDDATA	Decline - The transaction has already been settled.
239	DINVALIDDATA	Decline - The requested transaction amount must match the previous transaction amount.
240	DINVALIDDATA	Decline - The card type sent is invalid or does not correlate with the credit card number.
241	DINVALIDDATA	Decline - The referenced request id is invalid for all follow-on transactions.
242	DNOAUTH	Decline - The request ID is invalid. @@@@ You requested a capture, but there is no corresponding, unused authorization record. Occurs if there was not a previously successful authorization request or if the previously successful authorization has already been used in another capture request.
243	DINVALIDDATA	Decline - The transaction has already been settled or reversed.
246	DNOTVOIDABLE	Decline - The capture or credit is not voidable because the capture or credit information has already been submitted to your processor. Or, you requested a void for a type of transaction that cannot be voided.
247	DINVALIDDATA	Decline - You requested a credit for a capture that was previously voided.
248	DBOLETODECLINED	Decline - The boleto request was declined by your processor.
250	ETIMEOUT	Error - The request was received, but there was a timeout at the payment processor.
251	DCARDREFUSED	Decline - The Pinless Debit card's use frequency or maximum amount per use has been exceeded.
254	DINVALIDDATA	Decline - Account is prohibited from processing stand-alone refunds.
400	DSCORE	Soft Decline - Fraud score exceeds threshold.
450	DINVALIDADDRESS	Apartment number missing or not found.
451	DINVALIDADDRESS	Insufficient address information.
452	DINVALIDADDRESS	House/Box number not found on street.
453	DINVALIDADDRESS	Multiple address matches were found.
454	DINVALIDADDRESS	P.O. Box identifier not found or out of range.
455	DINVALIDADDRESS	Route service identifier not found or out of range.
456	DINVALIDADDRESS	Street name not found in Postal code.
457	DINVALIDADDRESS	Postal code not found in database.
458	DINVALIDADDRESS	Unable to verify or correct address.
459	DINVALIDADDRESS	Multiple address matches were found (international)
460	DINVALIDADDRESS	Address match not found (no reason given)
461	DINVALIDADDRESS	Unsupported character set
475	DAUTHENTICATE	The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction.
476	DAUTHENTICATIONFAILED	Encountered a Payer Authentication problem. Payer could not be authenticated.
480	DREVIEW	The order is marked for review by Decision Manager
481	DREJECT	The order has been rejected by Decision Manager
490		Your aggregator or acquirer is not accepting transactions from you at this time.
491		Your aggregator or acquirer is not accepting this transaction.
520	DSETTINGS	Soft Decline - The authorization request was approved by the issuing bank but declined based on your Smart Authorization settings.
700	DRESTRICTED	The customer matched the Denied Parties List
701	DRESTRICTED	Export bill_country/ship_country match
702	DRESTRICTED	Export email_country match
703	DRESTRICTED	Export hostname_country/ip_country match