API 연동하기

3DS Authentication TMS를 통한 정보 인증 토큰을 가지고 있음을 가정하여 아래의 결제 서비스 API 연동에 대한 내용을 안내합니다.※ 문서에서 안내하는 파라미터 및 필드는 필수 값입니다.

가맹점 검증 (Credential)

3DS 인증 완료 후 받을 수 있는 authorizationId와 아래의 가맹점 검증이 성공한 이후 반환받은 데이터를 Header에 구성해서 Payment Service를 요청해야 결제(승인 및 그 외 서비스)를 사용할 수 있습니다.

인증 코드 요청 (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	제공된 클라이언트 코드
clientSecret	String	제공된 클라이언트 암호

Response Data

Header	Type	Description
Authorization	String	가맹점 검증 코드

결제 요청 (Payment Request)

결제 전 고객의 신원을 검증하는 서비스이며, 인증된 고객만이 결제 서비스를 이용할 수 있습니다. 인증은 브라우저 상에서 진행되며, 인증 결과는 CallbackLocation으로 별도로 전송되고, redirectUrl로 페이지 이동을 진행합니다. 모듈은 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

CallbackLocation 상세설명

결제 완료 후, 최종 결과를 전달받을 URL입니다. 고객사에 방화벽이 존재하는 경우 옵타움서버 IP 112.175.117.124 및 Port 80, 443 허용이 필요합니다.

주의사항

반드시 웹 브라우저에서 Form submit 방식으로 요청해야 합니다. 연동에 필요한 UI는 제공되지 않으며, 고객사에서 UI를 제공해야 합니다.※ Form submit 이외의 요청은 허용하지 않습니다.

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 - 3DS 인증 실패시 Redirect 진행 / N(기본값) - 3DS 인증 실패시 이동하지 않음
isWindowed : Y - 새창으로 인증진행 / N(기본값) - 페이지 이동으로 인증진행
isAuthenticate : Y(기본값) - 결제 승인 진행 / N - 인증만 진행

Request Form Fields

Field	Type	Description
merchantId	String	가맹점 MID
merchantReferenceCode	String	가맹점에서 거래 내역 관리를 위한 필드
currency	String	통화 코드 (ISO 4217 참조, “3자리”)
cardAccountNumber	Number	카드 번호 TestEx) VISA 4000000000001091 MASTER 5200000000001096 JCB 3569960010083758
cardType	String	카드사 Ex) VISA, MASTER, JCB
cardExpirationMonth	String	카드 만료 월(MM) Test Ex) 01
cardExpirationYear	String	카드 만료 년(YYYY) Test Ex) 현 년도 + 3
firstName	String	고객 성
lastName	String	고객 이름
country	String	국가 코드 (ISO 3166-1 alpha-2 참조, “2자리)
state	String	주 (미국 및 캐나다만 사용)
city	String	도시
address	String	주소
postalCode	String	우편 번호
phone	String	고객 연락처
email	String	고객 E-mail
callbackLocation	String	결과를 받을 서버 URL URL주소는 “/” 로 끝나야 합니다.
redirectUrl	String	3DS 인증 완료 후 이동할 URL URL주소는 “/” 로 끝나야 합니다.
isWindowed	String	Option 기본값: N (“Y” 또는 “N”만 가능) N : 페이지 이동 \| Y : 새 창 N 일 경우 뒤로가기 Y 일 경우 창 닫기 실행
isRedirect	String	Option 기본값: N (“Y” 또는 “N”만 가능) Y일 경우 3DS 실패시에도 Redirect 실행
verifyId	String	제공된 가맹점 코드
authorization	String	가맹점 검증 코드
isAuthenticate	String	Option 기본값: N (“Y” 또는 “N”만 가능) Y일 경우 결제 승인 진행

Response Data

Field	Type	Description
decision	String	결과 값 (ACCEPT/REJECT)
reasonCode	String	결과 코드 / 성공시 100
transactionId	String	거래 ID
originalTransactionId	String	원거래 ID
결제 승인 미 진행 시(isAuthenticate = “N”)
xid	String	3DS MPI Transaction ID
eci	String	3DS 인증 결과
commerceIndicator	String	3DS 인증 결과
cavvAlgorithm	String	3DS 인증 결과
paresStatus	String	3DS 인증 결과
paSpecificationVersion	String	3DS 인증 결과(값이 있을 경우)
directoryServerTransactionID	String	3DS 인증 결과(값이 있을 경우)
cavv	String	3DS 발급사에서 생성한 cavv (MASTERCARD는 해당사항 없음)
ucafCollectionIndicator	String	3DS 인증 결과(MASTERCARD only)
ucafAuthenticationData	String	3DS 인증 결과(MASTERCARD only)

승인 취소 (Reverse), 매입 요청 (Capture), 환불 (Refund)

URL

승인 취소 Request URL : POST /reverse
매입 요청 Request URL : POST /capture
환불 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	가맹점 ID
merchantReferenceCode	String	가맹점의 거래 내역 관리 코드
currency	String	통화 코드 (ISO 4217, 3자리)
amount	Number	금액
email	String	고객 Email
originalTransactionId	String	원거래 ID

Response Fields

Field	Type	Description
decision	String	결과 값 (ACCEPT/REJECT)
reasonCode	String	결과 코드
transactionId	String	거래 ID
originalTransactionId	String	원거래 ID

무효 (Void)

URL

무효 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	가맹점 ID
merchantReferenceCode	String	가맹점의 거래 내역 관리 코드
currency	String	통화 코드 (ISO 4217, 3자리)
amount	String	금액
email	String	고객 Email
transactionId	String	Request ID
type	String	요청 TransactionId의 거래 상태 반드시 CAPTURE 또는 REFUND

Response Fields

Field	Type	Description
decision	String	결과 값 (ACCEPT/REJECT)
reasonCode	String	결과 코드
transactionId	String	거래 ID
originalTransactionId	String	원거래 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() {
                        (...)
                    );

거래 내역 조회 응답

Field	Type	Description
merchantReferenceCode	String	가맹점의 거래 내역 관리 코드
transactionId	String	거래 ID
originalTransactionId	String	원 거래 ID
step	String	거래 요청 구분
reasonCode	String	사유 코드
status	String	요청 결과 (successful/declined/error)
captureStatus	String	지급 서비스 상태(지급시에만)
message	String	결과 메시지
approvalCode	String	승인 번호
cardType	String	카드사
currencyCode	String	통화 코드 (ISO 4217, 3자리)
amount	Number	금액
cardPrefix	String	카드 앞 번호(MASTERCARD제외)
cardSuffix	String	카드 뒷자리

거래 내역 조회 지급 상태 상세(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

거래 내역 조회 응답 상세(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