# TpaycomTechnicalDocumentation.CardsAPIApi All URIs are relative to *https://secure.tpay.com* Method | HTTP request | Description ------------- | ------------- | ------------- [**apiCardsApiKeyCheckPost**](CardsAPIApi.md#apiCardsApiKeyCheckPost) | **POST** /api/cards/{api_key}/check | check [**apiCardsApiKeyDeregisterPost**](CardsAPIApi.md#apiCardsApiKeyDeregisterPost) | **POST** /api/cards/{api_key}/deregister | deregister [**apiCardsApiKeyPresalePost**](CardsAPIApi.md#apiCardsApiKeyPresalePost) | **POST** /api/cards/{api_key}/presale | presale [**apiCardsApiKeyRefundPost**](CardsAPIApi.md#apiCardsApiKeyRefundPost) | **POST** /api/cards/{api_key}/refund | refund [**apiCardsApiKeyRegisterSalePost**](CardsAPIApi.md#apiCardsApiKeyRegisterSalePost) | **POST** /api/cards/{api_key}/register_sale | register sale [**apiCardsApiKeySalePost**](CardsAPIApi.md#apiCardsApiKeySalePost) | **POST** /api/cards/{api_key}/sale | sale [**apiCardsApiKeySecuresalePost**](CardsAPIApi.md#apiCardsApiKeySecuresalePost) | **POST** /api/cards/{api_key}/securesale | secure sale [**apiCardsApiKeyVisacheckoutFinishPost**](CardsAPIApi.md#apiCardsApiKeyVisacheckoutFinishPost) | **POST** /api/cards/{api_key}/visacheckout_finish | visacheckout finish [**apiCardsApiKeyVisacheckoutPreparePost**](CardsAPIApi.md#apiCardsApiKeyVisacheckoutPreparePost) | **POST** /api/cards/{api_key}/visacheckout_prepare | visacheckout prepare # **apiCardsApiKeyCheckPost** > CheckResponse apiCardsApiKeyCheckPost(apiKey, opts) check Method, which can be used to ping our API server to establish a monitoring service on the Merchant system. ### Example ```javascript var TpaycomTechnicalDocumentation = require('tpaycom_technical_documentation'); var apiInstance = new TpaycomTechnicalDocumentation.CardsAPIApi(); var apiKey = "apiKey_example"; // String | The api key. var opts = { 'basicData': new TpaycomTechnicalDocumentation.CheckFields() // CheckFields | check method data }; var callback = function(error, data, response) { if (error) { console.error(error); } else { console.log('API called successfully. Returned data: ' + data); } }; apiInstance.apiCardsApiKeyCheckPost(apiKey, opts, callback); ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **apiKey** | **String**| The api key. | **basicData** | [**CheckFields**](CheckFields.md)| check method data | [optional] ### Return type [**CheckResponse**](CheckResponse.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: application/json - **Accept**: Not defined # **apiCardsApiKeyDeregisterPost** > InlineResponse200 apiCardsApiKeyDeregisterPost(apiKey, opts) deregister The method used to deregister client credit card token from Tpay and Merchant system.<br/>A client can also do it himself from the link in an email after payment.<br/><br/>After successful deregistration Merchant will not be able anymore to charge client's card. Tpay system sends notification about this deregistration to merchant endpoint, defined in merchant panel settings.<br/><br/><b>NOTICE:</b> To test this method you need to generate client token and calculate sign with your own API access data. ### Example ```javascript var TpaycomTechnicalDocumentation = require('tpaycom_technical_documentation'); var apiInstance = new TpaycomTechnicalDocumentation.CardsAPIApi(); var apiKey = "apiKey_example"; // String | The api key. var opts = { 'basicData': new TpaycomTechnicalDocumentation.DeregisterFields() // DeregisterFields | Transaction data. }; var callback = function(error, data, response) { if (error) { console.error(error); } else { console.log('API called successfully. Returned data: ' + data); } }; apiInstance.apiCardsApiKeyDeregisterPost(apiKey, opts, callback); ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **apiKey** | **String**| The api key. | **basicData** | [**DeregisterFields**](DeregisterFields.md)| Transaction data. | [optional] ### Return type [**InlineResponse200**](InlineResponse200.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: application/json - **Accept**: Not defined # **apiCardsApiKeyPresalePost** > RegisterSaleResponse apiCardsApiKeyPresalePost(apiKey, opts) presale The method used to create a new sale for payment on demand. It can be called after receiving a notification with client registered token (cli_auth parameter). It can not be used if 'onetimer' parameter was sent in register_sale or client has unregistered (by the link in an email sent by tpay.com after registering client’s credit card or by API).<br/><br/><b>Additional information</b> Please feel free to read detailed case study of <a href=\"https://support.tpay.com/en/case-study/wdrozenie-platnosci-rekurencyjnych-cyklicznych\" target=\"_blank\">Implementation of the recurrent payments</a> ### Example ```javascript var TpaycomTechnicalDocumentation = require('tpaycom_technical_documentation'); var apiInstance = new TpaycomTechnicalDocumentation.CardsAPIApi(); var apiKey = "apiKey_example"; // String | The api key. var opts = { 'basicData': new TpaycomTechnicalDocumentation.PresaleFields() // PresaleFields | Transaction data. }; var callback = function(error, data, response) { if (error) { console.error(error); } else { console.log('API called successfully. Returned data: ' + data); } }; apiInstance.apiCardsApiKeyPresalePost(apiKey, opts, callback); ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **apiKey** | **String**| The api key. | **basicData** | [**PresaleFields**](PresaleFields.md)| Transaction data. | [optional] ### Return type [**RegisterSaleResponse**](RegisterSaleResponse.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: application/json - **Accept**: Not defined # **apiCardsApiKeyRefundPost** > RefundResponse apiCardsApiKeyRefundPost(apiKey, opts) refund The method used to transfer money back to the client. The refund can reference to chosen sale (sale_auth) or directly to the client (cli_auth).<br/><br/> In both cases, the amount is adjustable in parameter amount. If the only cli_auth is sent amount parameter is required, if sale_auth is passed amount and currency is not necessary - the system will take default values from the specified sale.<br/>With sale_auth refund can be made only once. <br><br/> Parameter status is randomly picked in test mode. <br/><br/><b>NOTICE:</b> This method works only in production mode. To test this method you need to create and pay for production transaction with your own API access. ### Example ```javascript var TpaycomTechnicalDocumentation = require('tpaycom_technical_documentation'); var apiInstance = new TpaycomTechnicalDocumentation.CardsAPIApi(); var apiKey = "apiKey_example"; // String | The api key. var opts = { 'basicData': new TpaycomTechnicalDocumentation.RefundFields() // RefundFields | Transaction data. }; var callback = function(error, data, response) { if (error) { console.error(error); } else { console.log('API called successfully. Returned data: ' + data); } }; apiInstance.apiCardsApiKeyRefundPost(apiKey, opts, callback); ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **apiKey** | **String**| The api key. | **basicData** | [**RefundFields**](RefundFields.md)| Transaction data. | [optional] ### Return type [**RefundResponse**](RefundResponse.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: application/json - **Accept**: Not defined # **apiCardsApiKeyRegisterSalePost** > RegisterSaleResponse apiCardsApiKeyRegisterSalePost(apiKey, opts) register sale The method used to create sale initialisation in tpay.com system. The successful request returns sale_auth used to redirect a client to transaction panel. <br><br>The parameter sale_auth can be used to redirect a client to payment transaction panel: <br> <b> https://secure.tpay.com/cards/ </b><br> with argument sale_auth passed with the POST or GET method. <br><br> <b>Test mode notice!</b><br> In test mode, the transaction panel offers multiple system answers. You can choose at the transaction panel (instead of making a real transaction) to accept or decline payment to test all paths. In production mode client will be directly redirected to payment gateway with credit card data form. <br> Notification about positive transaction status will be sent to result URL which is set in account settings. ### Example ```javascript var TpaycomTechnicalDocumentation = require('tpaycom_technical_documentation'); var apiInstance = new TpaycomTechnicalDocumentation.CardsAPIApi(); var apiKey = "apiKey_example"; // String | The api key. var opts = { 'basicData': new TpaycomTechnicalDocumentation.RegisterSaleFields() // RegisterSaleFields | Transaction data. }; var callback = function(error, data, response) { if (error) { console.error(error); } else { console.log('API called successfully. Returned data: ' + data); } }; apiInstance.apiCardsApiKeyRegisterSalePost(apiKey, opts, callback); ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **apiKey** | **String**| The api key. | **basicData** | [**RegisterSaleFields**](RegisterSaleFields.md)| Transaction data. | [optional] ### Return type [**RegisterSaleResponse**](RegisterSaleResponse.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: application/json - **Accept**: Not defined # **apiCardsApiKeySalePost** > SaleResponse apiCardsApiKeySalePost(apiKey, opts) sale The method used to execute created sale with presale method. Sale defined with sale_auth can be executed only once. If the method is called second time with the same parameters, the system returns actual sale status - in parameter status - done for correct payment and declined for rejected payment. In that case, client card is not charged the second time. <br><br> Passed cli_auth has to match with cli_auth used while creating a sale in presale method. <br><br><b>Test mode notice!</b> The method will return correct status with 50% probability. The same concerns declined status. In this case, reason value is also randomly picked. ### Example ```javascript var TpaycomTechnicalDocumentation = require('tpaycom_technical_documentation'); var apiInstance = new TpaycomTechnicalDocumentation.CardsAPIApi(); var apiKey = "apiKey_example"; // String | The api key. var opts = { 'basicData': new TpaycomTechnicalDocumentation.SaleFields() // SaleFields | Transaction data. }; var callback = function(error, data, response) { if (error) { console.error(error); } else { console.log('API called successfully. Returned data: ' + data); } }; apiInstance.apiCardsApiKeySalePost(apiKey, opts, callback); ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **apiKey** | **String**| The api key. | **basicData** | [**SaleFields**](SaleFields.md)| Transaction data. | [optional] ### Return type [**SaleResponse**](SaleResponse.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: application/json - **Accept**: Not defined # **apiCardsApiKeySecuresalePost** > SecuresaleResponse apiCardsApiKeySecuresalePost(apiKey, opts) secure sale This method allows Merchant to host payment form on his website and perform sale without any client redirection to tpay.com system. Securesale method supports 3D Secure validation which is an additional security layer for online credit and debit card transactions. This approach requires special security considerations. We support secure communication by encrypting card data (card number, validity date and cvv/cvs number) on the client side (javascript) with Merchant public RSA key and send it as one parameter (card) to our API gate. A valid SSL certificate on the Merchant domain is required. Application flow is presented below for clarification:<br/><br/> 1. Generate webpage with your public RSA key in javascript<br/> 2. Before sending payment form, insert new input with encrypted card data using your public key and clear inputs with card data so only encrypted data will be sent and submit form. <br/> 3. In backend prepare parameters and send them with securesale method <br/> 4. Inform client about payment result<br/> <br/> Card cypher is made from string<br/><br/> card number|expiry date(MM/YY or MM/YYYY)|cvv or cvc|host <br/><br/> eg. \"1234567891234567|05/17|123|https://merchantwebsite.com\" <br/><br/> We have published code samples, libraries and instructions to give some insights on the process - see https://github.com/tpay-com/tpay-php . The library used in the example has a limit of 117 input characters for encryption. <br/> <b>In production mode, this generated hash works only once and should always be generated even for the same card data.</b><br/><br/> There are two ways for performing payment<br/><br/> a) <b>Pay by card without 3D- Secure.</b> <br/> If input parameters are correct, request is processed correctly and the entered card does not have the 3D-Secure option enabled, method returns parameters in JSON format<br/><br/> b) <b>Pay by card with 3D-Secure.</b> <br/>If input parameters are correct, the request is processed correctly and the card has enabled the 3D-Secure, the method returns the 3ds_url parameter in JSON format. <br/><br/> An example 3ds URL is presented below <br/><br/> https://secure.tpay.com/cards/?sale_auth=2587bf3a98dfa699ef9d01eba38359b7 <br/><br/> • The best way to implement 3DS is to open a link to 3D-Secure authentication in a new window. If this method is used, parameter \"enable_pow_url\" should be sent with value 1. After a correct authorization, a customer will be redirected to the Merchant’s Site. Return URL is set in Merchant’s Panel or sent dynamically. <br/><br/> • Do not use an inline frame to implement the 3D-Secure authentication on Merchant’s Site. In this case, some banks can block 3DS authorisation. <br/><br/> The parameters are sent with POST method. Merchant system has to respond to the notification by printing array in JSON format.<br/> See Card's notifications section.<br/><br/> <b>Test mode notice!</b> <br/>In test mode, transaction panel offers the choice of system answer for transactions with 3D-Secure authentication. You can choose to accept or decline payment to test all paths.<br/><br/><b>Additional information</b> Please feel free to read detailed case study of <a href=\"https://support.tpay.com/en/case-study/wdrozenie-bramki-platnosci-kartami-na-stronie-sklepu\" target=\"_blank\">Implementation of the card payment gateway at the store's website<a/> ### Example ```javascript var TpaycomTechnicalDocumentation = require('tpaycom_technical_documentation'); var apiInstance = new TpaycomTechnicalDocumentation.CardsAPIApi(); var apiKey = "apiKey_example"; // String | The api key. var opts = { 'basicData': new TpaycomTechnicalDocumentation.SecuresaleFields() // SecuresaleFields | Transaction data. }; var callback = function(error, data, response) { if (error) { console.error(error); } else { console.log('API called successfully. Returned data: ' + data); } }; apiInstance.apiCardsApiKeySecuresalePost(apiKey, opts, callback); ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **apiKey** | **String**| The api key. | **basicData** | [**SecuresaleFields**](SecuresaleFields.md)| Transaction data. | [optional] ### Return type [**SecuresaleResponse**](SecuresaleResponse.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: application/json - **Accept**: Not defined # **apiCardsApiKeyVisacheckoutFinishPost** > SecuresaleResponse apiCardsApiKeyVisacheckoutFinishPost(apiKey, opts) visacheckout finish The Method used to finish Visa Checkout payment. <br/><br/> Summary_data has format compliant with Visa Checkout Summary Payment Data. Its structure is described in Visa Checkout documentation at <a href=\"https://developer.visa.com/products/visa_checkout/guides#extracting-consumer-data\">extracting-consumer-data</a><br><br/> The example table with this format can be found at <a href=\"https://developer.visa.com/capabilities/visa_checkout/docs#pdfs_for_merchants_integrating_with_visa_checkout\">Link</a> <br><br>When some data change between visacheckout_prepare and visacheckout_finish, you should send the modified data with the summary_data table. You can only send to tpay.com the data, which changes (i.e. only the amount ) but you need to send it in the summary_data JSON structure. <br/>Other fields if not changed don’t have to be sent.<br/> The response format is the same as in SecureSale method - see the method for more details.<br/><br/><b>NOTICE:</b> To use Visa Checkout methods, you need to have access to cards API at your account and pass Visa requirements (see Visa Checkout Integration section). ### Example ```javascript var TpaycomTechnicalDocumentation = require('tpaycom_technical_documentation'); var apiInstance = new TpaycomTechnicalDocumentation.CardsAPIApi(); var apiKey = "apiKey_example"; // String | The api key. var opts = { 'basicData': new TpaycomTechnicalDocumentation.VcFinishFields() // VcFinishFields | Transaction data. }; var callback = function(error, data, response) { if (error) { console.error(error); } else { console.log('API called successfully. Returned data: ' + data); } }; apiInstance.apiCardsApiKeyVisacheckoutFinishPost(apiKey, opts, callback); ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **apiKey** | **String**| The api key. | **basicData** | [**VcFinishFields**](VcFinishFields.md)| Transaction data. | [optional] ### Return type [**SecuresaleResponse**](SecuresaleResponse.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: application/json - **Accept**: Not defined # **apiCardsApiKeyVisacheckoutPreparePost** > VcPrepareResponse apiCardsApiKeyVisacheckoutPreparePost(apiKey, opts) visacheckout prepare The method used to prepare Visa Checkout payment. <br/><br/><b>NOTICE:</b> To use Visa Checkout methods, you need to have access to cards API at your account and pass Visa requirements (see Visa Checkout Integration section). ### Example ```javascript var TpaycomTechnicalDocumentation = require('tpaycom_technical_documentation'); var apiInstance = new TpaycomTechnicalDocumentation.CardsAPIApi(); var apiKey = "apiKey_example"; // String | The api key. var opts = { 'basicData': new TpaycomTechnicalDocumentation.VcPrepareFields() // VcPrepareFields | Transaction data. }; var callback = function(error, data, response) { if (error) { console.error(error); } else { console.log('API called successfully. Returned data: ' + data); } }; apiInstance.apiCardsApiKeyVisacheckoutPreparePost(apiKey, opts, callback); ``` ### Parameters Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **apiKey** | **String**| The api key. | **basicData** | [**VcPrepareFields**](VcPrepareFields.md)| Transaction data. | [optional] ### Return type [**VcPrepareResponse**](VcPrepareResponse.md) ### Authorization No authorization required ### HTTP request headers - **Content-Type**: application/json - **Accept**: Not defined