API Explanation

Request Type

POST

Request URI

/api/v1/payment/local-card/payment3ds

Request

Parameter Type Required Sample Data Description
amount Number Yes 20000 Transaction Amount. Cent is the unit, “100” means a dollar
callBackURL String <= 255 characters Yes https://pay.ottpay.com/paymentResult Callback URL. After the payment is completed, the system sends a notification to this URL.
accountNumber String Yes 4000620000000123 Card number
accountName String Yes Jack Smith Card holder name
accountExpire String Yes 0625 Card expiry date. Format: MMYY
cvn2 String Yes 732 CVV2 secure code
sslAvsAddress String <= 50 characters Yes 3032920100 CORPORATE SQ Card holder address.
sslAvsCity String <= 40 characters Yes Atlanta Card holder’s city where the address is located.
sslAvsProvince String >= 2 characters, <= 40 characters Yes Georgia Card holder’s province where the address is located.
sslAvsCountry String =2 characters Yes US/CA Card holder’s country where the address is located. See Country Codes ISO 3166
sslAvsZip String <= 10 characters Yes 30327 Card holder postal code.
frontURL String <= 255 characters Yes https://pay.ottpay.com/paymentResult Return URL.
sslEciInd String No 3DS ECI value. This is the Electronic Commerce Indicator code, which gets returned by the card issuer indicating whether the cardholder was successfully authenticated
ssl3dsecureValue String <= 64 characters No 3 DS secure value. 3DS authentication value returned by 3DS authentication process.
sslDirServerTranId String <= 64 characters No 3DS secure transaction ID. This is the identifier of a 3DS authentication returned by the 3DS authentication process.
reference String No MJG498J89TGLNK45 The reference number from 3rd party. This can be used for order IDs that generated by integrate merchant.
sessionId String No The OTT Pay risk control DDC session ID.
email String No The consumer’s email.
purchase3DSAddition Object Yes The Object for challenge mode parameters, i.e. this parameter will take effect if the 3DS authentication process falls into challenge mode.
purchase3DSAddition.version String Yes “2.1.0” Fix value “2.1.0”
purchase3DSAddition.sessionID String Yes B61E6B38AFBF79C76A101E0F8CC26A93 HTTP session ID as upper.
purchase3DSAdditio.browserUserAgent String Yes
purchase3DSAddition.browserAcceptHeader String Yes
purchase3DSAddition.browserLanguage String Yes “en-CA” “navigator.language” value of shopper’s brwoser, defined in IETF BCP 47.
purchase3DSAddition.browserJavaScriptEnabledVal String Yes 1 shopper’s browser can execute JAVA? (true/false).
purchase3DSAddition.browserJavaEnabledVal String Yes 2 shopper’s browser can execute JavaScript? (true/false).
purchase3DSAddition.browserScreenHeight String Yes 100 The total height of the shopper’s device screen in pixels.
purchase3DSAddition.browserScreenWidth String Yes 80 The total width of the shopper’s device screen in pixels.
purchase3DSAddition.browserTimezone String Yes 8 Time difference between UTC time and the shopper’s browser local time.
purchase3DSAddition.browserScreenColorDepth String Yes 16 Accepted 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

Parameter Type Sample Data Description
reference String MJG498J89TGLNK45 The reference number from 3rd party. This can be used for order IDs that generated by integrate merchant.
ccType String VISA Card Schema VISA / MASTERCARD / AMEX
paymentId String 1694723098440263 Payment ID. A unique identifier associated with the payment transaction.
amount String 20000 Payment amount, i.e. purchase amount. The payment amount of purchase, cent is the unit, “100” means a dollar.
receiptAmount String 20000 Amount 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.
totalAmount String 20000 Total 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.
tradeTime String Format: yyyy-MM-dd HH:mm:ssz 2023-09-14 16:25:00 EDT Payment 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.
paymentStatus String authorised Payment Status. Please see Payment Status Query API for detail.
escape3DSChallengeForm String The 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

code message description
10005 Invalid parameter Parameter format incorrect
10200 Gateway error OTT gateway’s error response.
20004 Database error Transaction data induced database error.
20005 No permission for the merchant 1) 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.
20007 Insufficient balance 1) Card balance is insufficient to cover the payment, or 2) not enough funds for refund
20008 Unsupported card The 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
20019 Original payment not exist Original transaction/payment ID you provided cannot be found
20030 Payment failed Your request has been declined due to no financial impact - original transaction already declined
20034 Other case Any other errors that not include in the list
50001 Failure Payment Failed
50002 Timeout Your 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.
50003 System error No response received for the sent request
90000 Unauthorized The 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.