Интеграция API

Ниже приведена процедура интеграции API платежного сервиса, с учетом того, что имеется токен авторизации информации (authorizationId), полученный через 3DS Authentication TMS※ Поля и параметры, указанные в данном руководстве, являются обязательными значениями

Проверка клиента (Credential)

Оплату (подтверждение и другие сервисы) можно использовать только после отправки запроса Payment Service, указав в заголовке authorizationId, полученный после успешного прохождения 3DS Аутентификации, и данные, которые были возращены после успешного прохождения проверки клиента.

Запрос кода подтверждения (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. Модуль не предоставляет пользовательский интерфейс.

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-адрес для получения окончательного результата после завершения платежа. Если у компании есть брандмауэр, вам необходимо разрешить Optatum Server IP 112.175.117.124 и порты 80, 443.

Предупреждение

Запрос должен быть сделан в форме отправки в веб-браузере. Пользовательский интерфейс для интеграции НЕ предоставляется Optatum, пользовательский интерфейс предоставляет компания.※ Запросы, отличные от отправки формы, не допускаются.

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	Срок действия карты (Месяц) Test Ex) 01
cardExpirationYear	String	Срок действия карты (Год) Test Ex) Current Year + 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	Адрес электронной почты клиента
callbackLocation	String	URL-адрес сервера для получения результатов URL-адрес должен заканчиваться на “/”.
redirectUrl	String	URL-адрес, по которому нужно перейти после 3DS аутентификации. URL-адрес должен заканчиваться на “/”.
isWindowed	String	Вариант по умолчанию: Y (доступно только «Y» или «N») N: переход на страницу \| Y: новое окно Вернуться назад, когда N Закрыть страницу, когда Y
isRedirect	String	Вариант по умолчанию: N (только «Y» или «N») Если Y, перенаправление выполняется даже в случае сбоя 3DS.
verifyId	String	Предоставленный код клиента
authorization	String	Код подтверждения клиента
isAuthenticate	String	Вариант по умолчанию: N (можно использовать только «Y» или «N») Если Y, выполняется подтверждение платежа.

Response Data

Field	Type	Description
decision	String	Значение результата (ПРИНЯТЬ / ОТКЛОНИТЬ)
reasonCode	String	Код результата / при успехе 100
transactionId	String	ID транзакции
originalTransactionId	String	ID исходной транзакции
Если платеж не подтвержден (isAuthenticated = «N»)
xid	String	ID транзакции 3DS MPI
eci	String	Значение результата 3DS аутентификации
commerceIndicator	String	Значение результата 3DS аутентификации
cavvAlgorithm	String	Значение результата 3DS аутентификации
paresStatus	String	Значение результата 3DS аутентификации
paSpecificationVersion	String	Результат 3DS аутентификации (если есть)
directoryServerTransactionID	String	Результат 3DS аутентификации (если есть)
cavv	String	Cavv, созданный эмитентом 3DS (Не применимо для MASTERCARD)
ucafCollectionIndicator	String	Результаты 3DS сертификации (только MASTERCARD)
ucafAuthenticationData	String	Результаты 3DS сертификации (только MASTERCARD)

Отмена подтверждения (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	Адрес электронной почты клиента
originalTransactionId	String	ID оригинальной транзакции

Response Fields

Field	Type	Description
decision	String	Значение результата (ПРИНЯТЬ / ОТКЛОНИТЬ)
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	Адрес электронной почты клиента
transactionId	String	Request ID
type	String	Статус транзакции запроса TransactionId Должен быть ЗАХВАТ или ВОЗВРАТ

Response Fields

Field	Type	Description
decision	String	Значение результата (ПРИНЯТЬ / ОТКЛОНИТЬ)
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	Результат запроса (успешный / отклоненный / ошибка)
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