bazzar/vendor/t_pay/docs/CardsAPIApi.md

16 KiB
Raw Blame History

\CardsAPIApi

All URIs are relative to https://docs.tpay.com/Proxy.php

Method HTTP request Description
api_cards_api_key_check_post POST /api/cards/{api_key}/check check
api_cards_api_key_deregister_post POST /api/cards/{api_key}/deregister deregister
api_cards_api_key_presale_post POST /api/cards/{api_key}/presale presale
api_cards_api_key_refund_post POST /api/cards/{api_key}/refund refund
api_cards_api_key_register_sale_post POST /api/cards/{api_key}/register_sale register sale
api_cards_api_key_sale_post POST /api/cards/{api_key}/sale sale
api_cards_api_key_securesale_post POST /api/cards/{api_key}/securesale secure sale
api_cards_api_key_visacheckout_finish_post POST /api/cards/{api_key}/visacheckout_finish visacheckout finish
api_cards_api_key_visacheckout_prepare_post POST /api/cards/{api_key}/visacheckout_prepare visacheckout prepare

api_cards_api_key_check_post

crate::models::CheckResponse api_cards_api_key_check_post(api_key, basic_data) check

Method, which can be used to ping our API server to establish a monitoring service on the Merchant system.

Parameters

Name Type Description Required Notes
api_key String The api key. [required]
basic_data Option<CheckFields> check method data

Return type

crate::models::CheckResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: /

[Back to top] [Back to API list] [Back to Model list] [Back to README]

api_cards_api_key_deregister_post

serde_json::Value api_cards_api_key_deregister_post(api_key, basic_data) deregister

The method used to deregister client credit card token from Tpay and Merchant system.
A client can also do it himself from the link in an email after payment.

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.

NOTICE: To test this method you need to generate client token and calculate sign with your own API access data.

Parameters

Name Type Description Required Notes
api_key String The api key. [required]
basic_data Option<DeregisterFields> Transaction data.

Return type

serde_json::Value

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: /

[Back to top] [Back to API list] [Back to Model list] [Back to README]

api_cards_api_key_presale_post

crate::models::RegisterSaleResponse api_cards_api_key_presale_post(api_key, basic_data) 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 clients credit card or by API).

Additional information 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

Parameters

Name Type Description Required Notes
api_key String The api key. [required]
basic_data Option<PresaleFields> Transaction data.

Return type

crate::models::RegisterSaleResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: /

[Back to top] [Back to API list] [Back to Model list] [Back to README]

api_cards_api_key_refund_post

crate::models::RefundResponse api_cards_api_key_refund_post(api_key, basic_data) 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).

In both cases, the amount is adjustable in parameter amount. If the only cli_auth is sent, the amount parameter is required. If sale_auth is passed amount and currency are not necessary - the system will take default values from the specified sale and make a full amount refund.
If you pass the amount parameter and specific sale_auth, you can create more than one refund until the sum of all refunds reach the transaction amount.

In test mode this method has 50% probability of success and the status parameter is picked randomly.

Parameters

Name Type Description Required Notes
api_key String The api key. [required]
basic_data Option<RefundFields> Transaction data.

Return type

crate::models::RefundResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: /

[Back to top] [Back to API list] [Back to Model list] [Back to README]

api_cards_api_key_register_sale_post

crate::models::RegisterSaleResponse api_cards_api_key_register_sale_post(api_key, basic_data) 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.

The parameter sale_auth can be used to redirect a client to payment transaction panel:
https://secure.tpay.com/cards/
with argument sale_auth passed with the POST or GET method.

Test mode notice!
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.
Notification about positive transaction status will be sent to result URL which is set in account settings.

Parameters

Name Type Description Required Notes
api_key String The api key. [required]
basic_data Option<RegisterSaleFields> Transaction data.

Return type

crate::models::RegisterSaleResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: /

[Back to top] [Back to API list] [Back to Model list] [Back to README]

api_cards_api_key_sale_post

crate::models::SaleResponse api_cards_api_key_sale_post(api_key, basic_data) 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.

Passed cli_auth has to match with cli_auth used while creating a sale in presale method.

Test mode notice! The method will return correct status with 50% probability. The same concerns declined status. In this case, reason value is also randomly picked.

Parameters

Name Type Description Required Notes
api_key String The api key. [required]
basic_data Option<SaleFields> Transaction data.

Return type

crate::models::SaleResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: /

[Back to top] [Back to API list] [Back to Model list] [Back to README]

api_cards_api_key_securesale_post

crate::models::SecuresaleResponse api_cards_api_key_securesale_post(api_key, basic_data) 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:

1. Generate webpage with your public RSA key in javascript
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.
3. In backend prepare parameters and send them with securesale method
4. Inform client about payment result

Card cypher is made from string

card number|expiry date(MM/YY or MM/YYYY)|cvv or cvc|host

eg. "1234567891234567|05/17|123|https://merchantwebsite.com"

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.
In production mode, this generated hash works only once and should always be generated even for the same card data.

There are two ways for performing payment

a) Pay by card without 3D- Secure.
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

b) Pay by card with 3D-Secure.
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.

An example 3ds URL is presented below

https://secure.tpay.com/cards/?sale_auth=2587bf3a98dfa699ef9d01eba38359b7

• 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 Merchants Site. Return URL is set in Merchants Panel or sent dynamically.

• Do not use an inline frame to implement the 3D-Secure authentication on Merchants Site. In this case, some banks can block 3DS authorisation.

The parameters are sent with POST method. Merchant system has to respond to the notification by printing array in JSON format.
See Card's notifications section.

Test mode notice!
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.

Additional information 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

Parameters

Name Type Description Required Notes
api_key String The api key. [required]
basic_data Option<SecuresaleFields> Transaction data.

Return type

crate::models::SecuresaleResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: /

[Back to top] [Back to API list] [Back to Model list] [Back to README]

api_cards_api_key_visacheckout_finish_post

crate::models::SecuresaleResponse api_cards_api_key_visacheckout_finish_post(api_key, basic_data) visacheckout finish

The Method used to finish Visa Checkout payment.

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

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

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.
Other fields if not changed dont have to be sent.
The response format is the same as in SecureSale method - see the method for more details.

NOTICE: 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).

Parameters

Name Type Description Required Notes
api_key String The api key. [required]
basic_data Option<VcFinishFields> Transaction data.

Return type

crate::models::SecuresaleResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: /

[Back to top] [Back to API list] [Back to Model list] [Back to README]

api_cards_api_key_visacheckout_prepare_post

crate::models::VcPrepareResponse api_cards_api_key_visacheckout_prepare_post(api_key, basic_data) visacheckout prepare

The method used to prepare Visa Checkout payment.

NOTICE: 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).

Parameters

Name Type Description Required Notes
api_key String The api key. [required]
basic_data Option<VcPrepareFields> Transaction data.

Return type

crate::models::VcPrepareResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: /

[Back to top] [Back to API list] [Back to Model list] [Back to README]