API Explanation

Request Type

POST

Request URI

/api/v1/payment/local-card/payment3dsV2

Request

ParameterTypeRequiredSample DataDescription
amountNumberYes20000Transaction Amount. Cent is the unit, “100” means a dollar
callBackURLString <= 255 charactersYeshttps://pay.ottpay.com/paymentResultCallback URL. After the payment is completed, the system sends a notification to this URL.
accountNumberStringYes4000620000000123Card number
accountNameStringYesJack SmithCard holder name
accountExpireStringYes0625Card expiry date. Format: MMYY
cvn2StringYes732CVV2 secure code
sslAvsAddressString <= 50 charactersYes3032920100 CORPORATE SQCard holder address.
sslAvsCityString <= 40 charactersYesAtlantaCard holder’s city where the address is located.
sslAvsProvinceString >= 2 characters, <= 40 charactersYesGeorgiaCard holder’s province where the address is located.
sslAvsCountryString =2 charactersYesUS/CACard holder’s country where the address is located. See Country Codes ISO 3166
sslAvsZipString <= 10 charactersYes30327Card holder postal code.
frontURLString <= 255 charactersYeshttps://pay.ottpay.com/paymentResultReturn URL.
sslEciIndStringNo3DS ECI value. This is the Electronic Commerce Indicator code, which gets returned by the card issuer indicating whether the cardholder was successfully authenticated
ssl3dsecureValueString <= 64 charactersNo3 DS secure value. 3DS authentication value returned by 3DS authentication process.
sslDirServerTranIdString <= 64 charactersNo3DS secure transaction ID. This is the identifier of a 3DS authentication returned by the 3DS authentication process.
referenceStringNoMJG498J89TGLNK45The reference number from 3rd party. This can be used for order IDs that generated by integrate merchant.
sessionIdStringYesThe OTT Pay risk control DDC session ID.
emailStringYesThe consumer’s email.
purchase3DSAdditionObjectYesThe Object for challenge mode parameters, i.e. this parameter will take effect if the 3DS authentication process falls into challenge mode.
purchase3DSAddition.versionStringYes“2.1.0”Fix value “2.1.0”
purchase3DSAddition.sessionIDStringYesB61E6B38AFBF79C76A101E0F8CC26A93HTTP session ID as upper.
purchase3DSAdditio.browserUserAgentStringYes
purchase3DSAddition.browserAcceptHeaderStringYes
purchase3DSAddition.browserLanguageStringYes“en-CA”“navigator.language” value of shopper’s brwoser, defined in IETF BCP 47.
purchase3DSAddition.browserJavaScriptEnabledValStringYes1shopper’s browser can execute JAVA? (true/false).
purchase3DSAddition.browserJavaEnabledValStringYes2shopper’s browser can execute JavaScript? (true/false).
purchase3DSAddition.browserScreenHeightStringYes100The total height of the shopper’s device screen in pixels.
purchase3DSAddition.browserScreenWidthStringYes80The total width of the shopper’s device screen in pixels.
purchase3DSAddition.browserTimezoneStringYes8Time difference between UTC time and the shopper’s browser local time.
purchase3DSAddition.browserScreenColorDepthStringYes16Accepted values: 1, 4, 8, 15, 16, 24, 30, 32 or 48 bit color depth.

Request Example：

{
  "accountNumber": "4212345678910006",
  "accountName": "Bob White",
  "accountExpire": "0330",
  "cvn2": "737",
  "sslAvsAddress": "1123 Leslie Street",
  "sslAvsCity": "Toronto",
  "sslAvsProvince": "ON",
  "sslAvsCountry": "CA",
  "sslAvsZip": "M3C 2K5",
  "amount": 2000,
  "callBackURL": "https://uatqrpay.ottpay.com/ac/callback",
  "frontURL": "https://uatqrpay.ottpay.com/ac/front",
  "sslEciInd": "",
  "ssl3dsecureValue": "",
  "sslDirServerTranId": "",
  "reference": "20240405112734753",
  "sessionId": "",
  "email": "",
  "purchase3DSAddition": {
    "version": "2.1.0",
    "sessionID": "B61E6B38AFBF79C76A101E0F8CC26A93",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/536.5 (KHTML, like Gecko) Chrome/19.0.1084.52 Safari/536.5",
    "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
    "browserLanguage": "en-CA",
    "browserJavaScriptEnabledVal": "1",
    "browserJavaEnabledVal": "2",
    "browserScreenHeight": "100",
    "browserScreenWidth": "80",
    "browserTimezone": "8",
    "browserScreenColorDepth": "16"
  }
}

Response

ParameterTypeSample DataDescription
referenceStringMJG498J89TGLNK45The reference number from 3rd party. This can be used for order IDs that generated by integrate merchant.
ccTypeStringVISACard Schema VISA / MASTERCARD / AMEX
paymentIdString1694723098440263Payment ID. A unique identifier associated with the payment transaction.
amountString20000Payment amount, i.e. purchase amount. The payment amount of purchase, cent is the unit, “100” means a dollar.
receiptAmountString20000Amount on the payment receipt, i.e. purchase amount +tips + fees - discount. The value of amount appears on receipt, include fees and tips, cent is the unit, “100” means a dollar.
totalAmountString20000Total amount of the transaction, i.e. purchase amount + tips + fees. The value of amount include fees and tips before applying coupon or discount, cent is the unit, “100” means a dollar.
tradeTimeString Format： yyyy-MM-dd HH:mm:ssz2023-09-14 16:25:00 EDTPayment time. The timestamp when the transaction or the query was initiated by the client. Time zone is always calculated/displayed in DST irrespective of the merchant location.
paymentStatusStringauthorisedPayment Status. Please see Payment Status Query API for detail.
escape3DSChallengeFormStringThe http form if the payment falls into a challenge mode.

Response Example：

NOTE: If the issuing bank requires the Identify mode 3DS, the response will be the same as the [Local Card Payment] API. If the issuing bank requires the Challenge mode 3DS, the response will be as below.

{
    "status": "SUCCESS",
    "result": {
        "reference": "20240405112734753",
        "ccType": null,
        "paymentId": null,
        "amount": null,
        "receiptAmount": null,
        "totalAmount": null,
        "tradeTime": null,
        "paymentStatus": "THREEDS_AUTH_CHALLENGE",
        "escape3DSChallengeForm": "&lt;html&gt;     &lt;body&gt;         &lt;form id=&quot;sendAdyen&quot; name=&quot;sendAdyen&quot;  action=&quot;https://checkoutshopper-test.adyen.com/checkoutshopper/threeDS/checkoutRedirect/H4sIAAAAAAAA_2WKTQuCQBQAf43eElHELh40swiVSLPyEsv2che_tn1Pwn-fx0CY08zIgaDRjOQ4BEzJJ5tImBJxAn3VXSCIFBpuaDjJAhfA23EiFKNSoDcESBZ7zTBYfOzXw2JIaIC4cCwU1HeGmyhUF3iDhoGD4cZ5equrIvKzbXks7qVn_vdgVVE2QfnV_BB58zlmu1Rl_t4uQx-r3s_lLvo0bqbzNontujo9fhW01zveAAAA&quot; method=&quot;post&quot;&gt;             &lt;input id=&quot;MD&quot; name=&quot;MD&quot; value=&quot;M2RzMi44YTU1ZDMyMmMzMzY1OTg5NTEyNjZkODNlMWYwMDRhZjE2ZWIyZDY0MDQ5YTRkMzdlY2I5M2RjMTNkZTNmOTJlLjIuH4sIAAAAAAAA_yWOUWuDMBhF_0sexxbz2Uwz30xqdC9W1NINhJIGuzCsOqduUvrfF7unC_ccuPeKAAVoV5aZWo5cNarV9bGMihI9IqAWmXHsv4PKqZxJjV9Drxbc2cqG7i6Vo3TlnIeuHa3vWr2fTnh2MSPg-ZT4G8YoABAs9j9w-Zj7p2bnJ3HScFkcOmPeZ-79Zp_SvBV5DEKaLInWZbJOxxnnUniUQcjkC1DfvaPN_-GHOA_T7eE1TaO8wCK8s2cUkDXtlSvS0zDUrV6sL8Kt5bNqphoFLiHkdvsD1P1AmPoAAAA&quot; /&gt;             &lt;input id=&quot;PaReq&quot; name=&quot;PaReq&quot; value=&quot;BQABAgA4gQ1_trLXe5lV-qHHzXG-kc5ZlXAvuD0jus9VAlJY7-l7lahKu7UFqQTqwmH8yDBRZVuBWyD3oyZxeiZ1s9I1eAfUBsV1x6FsF6ojPf9S-ClLlkumaHO6u7HajDqGheo8eJZ6HylHTmLKo1dZDWgFCKZIa6IvSIi1HTtUAnJZgcgAYv9aid9KYDWopPa_3-KYLNU2_u7qKBdUlBxbddkA1HS6zM7kKmA75jx8UyDIGkWMrolcjW5v6LxKCxjRLw5J23VxiA__maLLggvw6pLwyMHQs8fpJTPeKmFGMdXfR1QJuVddvCqFBStSw8plASQY0JxZHMN8Zcp2Q-u75DUuHp1CHUavMTGdS6SY2PIh5ABHRrz-LyFSA6RRzjgSSaNvCUuOrfYjnAT57fOKeHbzEDzVjwZ1lhLdAp6RlG2dMbvROtVBPt9R65VcXwUCWQ3JgjZ-aeePwjeZxPd48O9cfpVjh8sFcpmpq5l2KQNA2qOR94RqkDS6XWr76f96twcg9Q8b1hUKplybBRWUv4nfjgQ5P2Ce_3V1rYs3WyuBnCHeGS0NOTFZAWke5A2-HDwaaz76sjy04t9LK8nHoXOZ3XRplgL3F9MgpR0eNAnZuMaa_wS6cTmFTCNNonMPtd3nZN8NM5Q4hQqMizYrqE91xvjHoXREcTr8ySwgwJrssQxnikmlYR1mGMpn9b4ASnsia2V5IjoiQUYwQUFBMTAzQ0E1MzdFQUVEODdDMjRERDUzOTA5QjgwQTc4QTkyM0UzODIzRDY4REFDQzk0QjlGRjgzMDVEQyJ9116T86q7dEoJQiqxKaxTRy2a2zb3YA4sHDq10SaMQHkMU2gYQ9tQSyEO-Jrnwcss301xzKc-_grJm0VKgtkl03aqrn_9_ZNHulgjmfXnvXYV5-Ovoe5jwAopxJhfziu66pi6UJKK78Am4tMbhgu_6RvmevMW7d68XLbqmGvUSBWK5Z9x92up-PVZRVCpB93GB-5GDixXQ30AvMjX5dTs1TWNMFPxaxkcku-dIxOLlKlDT56UHo6TLShbNwCb2bwJDJWSeWvaxtvV3Dz13hcEDsJCyyzSHwcZqm7XGIDLTGC-mjYRRWijjSukNd9QAvdBtSzAV_nJfbnkNaNzZ9qY5nnD6KXHg2mXxa0N1UGQ2DuJqC624VPpZsxSMUHKE7mnvZ0N5OKNGmyv06y0FFMQvYquL2_tJuXOl2A0e2L9M0iGWfGpjrW64lRIfn1REbyaM_Xmr4qtz0zTuMIzj1SnzueakQbMHCU0HjLWTavUANjZKXVlGzC-5W8qmIhL8psuMi4FAAEBAGamL6fv-bPYCAjdvOAZjzuY5YP3dnfkLpqCOKlqMKXOWm0tcJMdeN7OzekSmhqVzBtChEFLbpFtFDf5JLOZac7Rk4C5-1uMiYEVWQaYeZY3IffHHjztdjT7co_DIhayv_hJmNhRB_SI3fhr10lyoc7pl9pu9HaYjuVBAnAzlJZPPSXuQRcajA4QO6fbc4AjQIUamIuItbTRu01ieqjCXrJhK7R3em2MyRcGcLf0GT4bQRLUtY6W4ctY4Q0gCncTPsTjk87MSSC1pJC9VtrbhFX3O5CRp1aosXs2x2Z3O6ZboMuWGyFSRNhYDUfOQfx9eY34JV51EN8pAGPcs9hiqEYMmQ3SPcHc_Cqjt_pTAAAZVk-kfL0tIEHL6jieOJFxeHVp3VCO00ZzSDtRg81HGvW5CHrEVloJJ7N6yfs1BWMZOaGxlpgYWD1h2fLlEN79dXbKczQy3yZd70GNQvYX8y9UGSNTqc4Kzkzc7l7NejdEsPcmD8Y2ZJQoUykusSsdX4Jt37Zw5EWkJ7MVvAV3AlmcIyh-TT8ox1CrkPOzc2kLVyu9hwIjOS-LyyypwfeapGmDiCShB-dAJTMYG5wQL-oS0QpxbMaDd9gypgoQyvEHaAcKAhxbsk7v3xtBsWiGcF2JXjEqCRueyvtLRAhhznzM0yKERilrVbyHJlMjUJ_SwGhEcEE1bi5VMDV6JFk8tngp0slJdHiusTLqdnn5aY8Bi_r4NRZPIr3G8SFIy-AB2Ynp9C3gTmoxRjl1X8ViWgUHeKZoZUzuMlSk678arvBPd-11tmVIlzz18jU0X0nqXx5NY9L2aGKWxvP4YPFDE7rhQunHYUMkQtmRpRiTjJD0mWHITo7kS0Hk5wEEpwqKSg5NJdjgIFrnK0GIA2BkrvnTVVSkQvNIQ7vnxJvOD3Rod9SgkE9OMB6oX3q8hibqcFDFukYa5NeRLnPe6fZmcDYilVf7VaCfFJjDIfwQdLqrRYt7dka73bkZA2GQdp04eJJaFy6xwIFE91GfUh3riRKCZKgacMP4o7YQ7JIdKtiq0NEdKd8PEtq0_wUTLWOZdnGhv4JaZJLqk-ghuB48lgsBMQL-Qy6KQjghgzcjVbb4W7qdrw0KNtapfSIoVn9DALvOMWy5phqBktC86RO2Y2Dky7m13Bs3s_Sk1w6-pNuqALkryfOBCFYugS8OCKUzpJvSNa6TEEsdZDIbpT7CpHP1JrHSRq5iyXjNMwLVgztgWwrN14B32C6-vkrbI6z6i9V0ASvZdMyKZxBiGrtutyXaZ8iAqZP9pN4SHcQbvEYF9qyhhpA6fTDkyaOXWIfzJK7BQkHQxvv_-vcaiuLdsRUa68h_H59ShBqOUMGNR-rHh4FWYmmVzGZmgYDXRImDYsY-P9cSY96fcYg58MZT7elxo66ezxo0M58A9kwpmIThCp2_ntSZ05mJMCSQ1OFQa-K0P3k7yyVNof_0WFQNZXQJrKH-cy3J0lvmbs5ruhlhcYEGyziMM5k1BNJPzmlcbO6cN5sEWtVdiRaxNOm9YPIsvxvyQGwnbxnL73ZJyiPFqf0GJKBqwcLUmXUe1MMfDsPhCCU5KmXZbdrbCxrz0vgHUPGSJbWYg89sJ3NMbZEsYuj_9BET97kyJALJUM0X_e3EwAq7XmGqxOI-IL8gvLBDiTwkLemfwj4gzudOtkZJdWdiG8reTBoYBH4gEMtOM-E4nS1dMobyeQf1JvZYOysKJYPLqn0L815QZPYWC5SO3O3roRFVr_dQgoFiHNi437KuctoK7oVGZMqp2dW_ccZOi2pRdwQhglQ6BUrv6aIitDjmzH00VcFzezsiDWDdvVuS0Pk8940LTnaeNe1qMCDXwfRCWxdut2pZ3TWrFkI43uZd_SZpyGOWbMBaFJhqNrBZQMF8xOTzb2Uht_Em7QSVaWv30Q901eQEG0GERA29pKM8xBUIj_7guV9BTSxDAD2OmI3WphIG59clVbEfzbx0EH00PoPWvwYTRWP5Dc00TCc62nFXBw2oGtSuBDxU5f4W662eQRbL-ofJ3t_1l9ie3HZgR88HZXhQu6bTro5p0DPAKWUc-YPbBGoxjckhliw7lUFAncQqF0Ew7zo3BxWNmhtsb1HawYrNgTC6A9JMTEgOozH85yY6t7plHv6ZX13QvtZBYHgWpj3fsKoRtUl9mD_j3Y7qQxEjcvThOp-9xrgzBl-EvP9PI-z118mJP9niGM7Ha34EtBMVRbdDhz9MxxF5SbPPhlyjy66YOhHYbGgJl80tzAHjQEdqMtdXgRzfLysu_HIP7hpVi_rrwZALKkp_sMyTXrOXT7gUWIH1-C6aX19UPwjtOyfMcM-n0IfWZuwYqJfCSAqovONsZWFsWmHtLsjacKUMlF0p8zLkp_HzqCP8UPeEyIhpuQuV_3a45cS2P5cqjNKNJcLTjmeTGOzxJz-zrMJ5DCIN9yda8ip3XNzqbaCNVBlXbnAHWBbqx_qCQxV3kz20oemjY-Mfm6IkLQ02B8l0c1f3-wAUYhPZ6-pzWc6UwFIZIUWV0pLAqtQcKYeUhC01W8sygjriFtNxSrew4ujlWjzTicItF9tTQNqKsNo2kHysgI1a_HeeC5xFXwWSYcQ-8PwsYGrD0XsuTrjOQZv9tpXgSsLTLOpw-xfJc2FJ76vjqc2QW1H_WckoYmsoStMEJ5FCXAnnIWZI_wm_G5otqEuIm4c1mx_pqO6vpEqLjotiUf829ULz2tSC6Suop82PuM9GkoRJsN8z9UdVanyxiqkygBII5HLGg4SlmfrNYQa9kqQqnTsRkPebMyJwRSrVtAMsP6dPrn9ApDUBDTHWHqDSulwHC_B2VlbAWdLbQdRgCszzqVw-BBkpE1IKJ0Z8jxFfQkLWPgkgYv0sRNLoaDAmAi5MbfeLXjyMoa6sESGh6LvB2fSwnposLyr5LPwIcHQ3bKH0ij-y5YvG-3Rh-u-8C26tCSjuKYh5PdDThyrF2UuHrlVWZgI3TSPjENZ8BczP67kk73zTL7ffR9s_V_RKnEF1apXj860BV4ctLTQ3GsSB0r1ZMxA8f26WvKxIa9Uej4iWMfrDETqE0B9y-H4uyFLhevECSPaMXGBL5JiA3oKU9rhEtvStgDwR1Z-Qj_cMcz161wFm4zFY7UPrSuEgklc4EjWkGvGijpeqeOsZWQNtejZ7Tn73CI84hezrJwmed_3VUUee1wJAQ4RP_TiFt9HIpVTdcaFFXeOb7m1AXM_CdUyTXOWFsL-yVFi4hEH6K-S2Ost626OKktLLFq9aggvZ42MNwyTlZOQNnz1NsZzeKoik0Cu3&quot; /&gt;             &lt;input type=&quot;submit&quot; value=&quot;Submit&quot; &gt;        &lt;/form&gt;     &lt;/body&gt;     &lt;script type=&quot;text/javascript&quot;&gt;         setTimeout(function() {                document.getElementById(&quot;sendAdyen&quot;).submit();          }, 100);     &lt;/script&gt;     &lt;/html&gt;"
    }
}

API Response error code

codemessagedescription
10005Invalid parameterParameter format incorrect
10200Gateway errorOTT gateway’s error response.
20004Database errorTransaction data induced database error.
20005No permission for the merchant1) The entered pre-authorization code is invalid, or 2) The merchant account you provided cannot be found, or 3) The merchant account you provided is disabled, or 4) Your merchant account is not configured for the transaction you attempted.
20007Insufficient balance1) Card balance is insufficient to cover the payment, or 2) not enough funds for refund
20008Unsupported cardThe card type was not recognized, or The card was removed too quickly and the approval process was interrupted POS terminal was unable to encrypt the message and process the transaction
20019Original payment not existOriginal transaction/payment ID you provided cannot be found
20030Payment failedYour request has been declined due to no financial impact - original transaction already declined
20034Other caseAny other errors that not include in the list
50001FailurePayment Failed
50002TimeoutYour request has been declined due to a timeout OR The authorization message is approved. The error occurs if: 1) the transaction was declined by the card afterwards, or 2) timeout on the terminal. As a result, the transaction is reversed.
50003System errorNo response received for the sent request
90000UnauthorizedThe entered access token is invalid

Payment Result

After the OTT Pay API server obtains the payment result from the payment channel, it will immediately send the payment result to the specified callbackURL. Of course, the merchant system can also actively query through Payment Status Query API.