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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 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
HeaderTypeDescription
clientCodeString제공된 클라이언트 코드
clientSecretString제공된 클라이언트 암호
Response Data
HeaderTypeDescription
AuthorizationString가맹점 검증 코드

결제 요청 (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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 <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
FieldTypeDescription
merchantIdString가맹점 MID
merchantReferenceCodeString가맹점에서 거래 내역 관리를 위한 필드
currencyString통화 코드 (ISO 4217 참조, “3자리”)
cardAccountNumberNumber카드 번호 TestEx) VISA 4000000000001091 MASTER 5200000000001096 JCB 3569960010083758
cardTypeString카드사 Ex) VISA, MASTER, JCB
cardExpirationMonthString카드 만료 월(MM) Test Ex) 01
cardExpirationYearString카드 만료 년(YYYY) Test Ex) 현 년도 + 3
firstNameString고객 성
lastNameString고객 이름
countryString국가 코드 (ISO 3166-1 alpha-2 참조, “2자리)
stateString주 (미국 및 캐나다만 사용)
cityString도시
addressString주소
postalCodeString우편 번호
phoneString고객 연락처
emailString고객 E-mail
callbackLocationString결과를 받을 서버 URL URL주소는 “/” 로 끝나야 합니다.
redirectUrlString3DS 인증 완료 후 이동할 URL URL주소는 “/” 로 끝나야 합니다.
isWindowedStringOption 기본값: N (“Y” 또는 “N”만 가능) N : 페이지 이동 | Y : 새 창 N 일 경우 뒤로가기 Y 일 경우 창 닫기 실행
isRedirectStringOption 기본값: N (“Y” 또는 “N”만 가능) Y일 경우 3DS 실패시에도 Redirect 실행
verifyIdString제공된 가맹점 코드
authorizationString가맹점 검증 코드
isAuthenticateStringOption 기본값: N (“Y” 또는 “N”만 가능) Y일 경우 결제 승인 진행
Response Data
FieldTypeDescription
decisionString결과 값 (ACCEPT/REJECT)
reasonCodeString결과 코드 / 성공시 100
transactionIdString거래 ID
originalTransactionIdString원거래 ID
결제 승인 미 진행 시(isAuthenticate = “N”)
xidString3DS MPI Transaction ID
eciString3DS 인증 결과
commerceIndicatorString3DS 인증 결과
cavvAlgorithmString3DS 인증 결과
paresStatusString3DS 인증 결과
paSpecificationVersionString3DS 인증 결과(값이 있을 경우)
directoryServerTransactionIDString3DS 인증 결과(값이 있을 경우)
cavvString3DS 발급사에서 생성한 cavv (MASTERCARD는 해당사항 없음)
ucafCollectionIndicatorString3DS 인증 결과(MASTERCARD only)
ucafAuthenticationDataString3DS 인증 결과(MASTERCARD only)

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

URL
  • 승인 취소 Request URL : POST /reverse
  • 매입 요청 Request URL : POST /capture
  • 환불 Request URL : POST /refund
Sample Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 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
FieldTypeDescription
merchantIdString가맹점 ID
merchantReferenceCodeString가맹점의 거래 내역 관리 코드
currencyString통화 코드 (ISO 4217, 3자리)
amountNumber금액
emailString고객 Email
originalTransactionIdString원거래 ID
Response Fields
FieldTypeDescription
decisionString결과 값 (ACCEPT/REJECT)
reasonCodeString결과 코드
transactionIdString거래 ID
originalTransactionIdString원거래 ID

무효 (Void)

URL
  • 무효 Request URL : POST /void
Sample Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 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
FieldTypeDescription
merchantIdString가맹점 ID
merchantReferenceCodeString가맹점의 거래 내역 관리 코드
currencyString통화 코드 (ISO 4217, 3자리)
amountString금액
emailString고객 Email
transactionIdStringRequest ID
typeString요청 TransactionId의 거래 상태 반드시 CAPTURE 또는 REFUND
Response Fields
FieldTypeDescription
decisionString결과 값 (ACCEPT/REJECT)
reasonCodeString결과 코드
transactionIdString거래 ID
originalTransactionIdString원거래 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 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() {         (...)     );
거래 내역 조회 응답
FieldTypeDescription
merchantReferenceCodeString가맹점의 거래 내역 관리 코드
transactionIdString거래 ID
originalTransactionIdString원 거래 ID
stepString거래 요청 구분
reasonCodeString사유 코드
statusString요청 결과 (successful/declined/error)
captureStatusString지급 서비스 상태(지급시에만)
messageString결과 메시지
approvalCodeString승인 번호
cardTypeString카드사
currencyCodeString통화 코드 (ISO 4217, 3자리)
amountNumber금액
cardPrefixString카드 앞 번호(MASTERCARD제외)
cardSuffixString카드 뒷자리
거래 내역 조회 지급 상태 상세(CaptureStatus)
Status ValueTypeDescription
PENDINGStringThe 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.
TRANSMITTEDStringThe Capture/Credit request was successfully sent to the Processor.
VOIDEDStringThe 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_ERRORStringThere was an error processing this transaction at the Processor.

Reason Code

거래 내역 조회 응답 상세(reasonCode)
Reason CodeReply Flag (SCMP)Description
100SOKSuccessful transaction
101DMISSINGFIELDDeclined - The request is missing one or more fields
102DINVALIDDATADeclined - One or more fields in the request contains invalid data.
104DDUPLICATEDeclined - The merchantReferenceCode sent with this authorization request matches the merchantReferenceCode of another authorization request that you sent in the last 15 minutes.
110SPARTIALAPPROVALPartial amount was approved
150ESYSTEMError - General system failure.
151ETIMEOUTError - The request was received but there was a server timeout. This error does not include timeouts between the client and the server.
152ETIMEOUTError: The request was received, but a service did not finish running in time.
200DAVSNOSoft 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.
201DCALLDecline - 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.
202DCARDEXPIREDDecline - Expired card. You might also receive this if the expiration date you provided does not match the date the issuing bank has on file.
203DCARDREFUSEDDecline - General decline of the card. No other information provided by the issuing bank.
204DCARDREFUSEDDecline - Insufficient funds in the account.
205DCARDREFUSEDDecline - Stolen or lost card.
207DCARDREFUSEDDecline - Issuing bank unavailable.
208DCARDREFUSEDDecline - Inactive card or card not authorized for card-not-present transactions.
209DCARDREFUSEDDecline - card verification number (CVN) did not match.
210DCARDREFUSEDDecline - The card has reached the credit limit.
211DCARDREFUSEDDecline - Invalid Card Verification Number (CVN).
220DCHECKREFUSEDDecline - Generic Decline.
221DCHECKREFUSEDDecline - The customer matched an entry on the processor's negative file.
222DCHECKREFUSEDDecline - customer's account is frozen
230DCVSoft 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.
231DINVALIDCARDDecline - Invalid account number
232DINVALIDDATADecline - The card type is not accepted by the payment processor.
233DINVALIDDATADecline - General decline by the processor.
234DINVALIDDATADecline - There is a problem with your merchant configuration.
235DINVALIDDATADecline - The requested amount exceeds the originally authorized amount. Occurs, for example, if you try to capture an amount larger than the original authorization amount.
236DINVALIDDATADecline - Processor failure.
237DINVALIDDATADecline - The authorization has already been reversed.
238DINVALIDDATADecline - The transaction has already been settled.
239DINVALIDDATADecline - The requested transaction amount must match the previous transaction amount.
240DINVALIDDATADecline - The card type sent is invalid or does not correlate with the credit card number.
241DINVALIDDATADecline - The referenced request id is invalid for all follow-on transactions.
242DNOAUTHDecline - 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.
243DINVALIDDATADecline - The transaction has already been settled or reversed.
246DNOTVOIDABLEDecline - 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.
247DINVALIDDATADecline - You requested a credit for a capture that was previously voided.
248DBOLETODECLINEDDecline - The boleto request was declined by your processor.
250ETIMEOUTError - The request was received, but there was a timeout at the payment processor.
251DCARDREFUSEDDecline - The Pinless Debit card's use frequency or maximum amount per use has been exceeded.
254DINVALIDDATADecline - Account is prohibited from processing stand-alone refunds.
400DSCORESoft Decline - Fraud score exceeds threshold.
450DINVALIDADDRESSApartment number missing or not found.
451DINVALIDADDRESSInsufficient address information.
452DINVALIDADDRESSHouse/Box number not found on street.
453DINVALIDADDRESSMultiple address matches were found.
454DINVALIDADDRESSP.O. Box identifier not found or out of range.
455DINVALIDADDRESSRoute service identifier not found or out of range.
456DINVALIDADDRESSStreet name not found in Postal code.
457DINVALIDADDRESSPostal code not found in database.
458DINVALIDADDRESSUnable to verify or correct address.
459DINVALIDADDRESSMultiple address matches were found (international)
460DINVALIDADDRESSAddress match not found (no reason given)
461DINVALIDADDRESSUnsupported character set
475DAUTHENTICATEThe cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction.
476DAUTHENTICATIONFAILEDEncountered a Payer Authentication problem. Payer could not be authenticated.
480DREVIEWThe order is marked for review by Decision Manager
481DREJECTThe order has been rejected by Decision Manager
490Your aggregator or acquirer is not accepting transactions from you at this time.
491Your aggregator or acquirer is not accepting this transaction.
520DSETTINGSSoft Decline - The authorization request was approved by the issuing bank but declined based on your Smart Authorization settings.
700DRESTRICTEDThe customer matched the Denied Parties List
701DRESTRICTEDExport bill_country/ship_country match
702DRESTRICTEDExport email_country match
703DRESTRICTEDExport hostname_country/ip_country match