Cards

Card payment is a popular method for making transactions using debit or credit cards. This process involves entering card details, such as the card number, expiration date, and CVC/CVV code, in the payment form. To verify identity and secure the transaction, additional confirmation may be required, such as through the use of 3D Secure (e.g., confirmation in the card issuer's app, a code sent via SMS, or a PIN).

Before you start

Ensure that:

• You have API authorization data.
• You handle transaction notifications.
• Card payments are enabled.

Supported card types

Currently, we only support Visa and Mastercard cards.

Payment in other currency

• PLN - documentation API Tpay.
• For other currency - payments in other currency are available only for use of acquirer Elavon. To implement this functionality, use documentation Tpay.

Card transaction

Process card payments using the transaction creation endpoint by specifying groupId: 103.

Send a request to create a card transaction

To create a card transaction, send a POST request to the endpoint:

https://api.tpay.com/transactions

Specify the following parameters in the request:

The basic request body should look like this:

{
  "amount": 0.1,
  "description": "Test card payment",
  "payer": {
    "email": "[email protected]",
    "name": "John Doe"
  },
  "pay": {
    "groupId": 103
  }
}

After sending the request, you will receive a TransactionCreated schema in the response.

The key response parameters are:

Example response:

{
  "result": "success",
  "requestId": "858fa92dc62db44e2c1f",
  "transactionId": "ta_9jQLGqzeY2eOVK01",
  "title": "TR-CWM-CNYHA6X",
  "posId": "ps_e4dkPVDEm4Jg7267",
  "status": "pending",
  "date": {
    "creation": "2024-06-06 21:31:35",
    "realization": null
  },
  "amount": 0.1,
  "currency": "PLN",
  "description": "Test card payment",
  "hiddenDescription": "",
  "payer": {
    "payerId": "py_a9rjlZWxRLdG1bqY",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "",
    "address": "",
    "city": "",
    "country": "PL",
    "postalCode": ""
  },
  "payments": {
    "status": "pending",
    "method": "pay_by_link",
    "amountPaid": 0,
    "date": {
      "realization": null
    }
  },
  "transactionPaymentUrl": "https://secure.tpay.com/?title=TR-CWM-CNYHA6X&uid=01HZQGHZP5P3P7YV8A4BRVDX17"
}

Redirect the payer to the Transaction Panel

Redirect the payer to the URL contained in the response in the transactionPaymentUrl field.

The payer will then fill out the form with card details and submit the form.

3DS Authentication

If necessary, we will redirect the payer to the issuing bank's page for 3D Secure authentication.

3D Secure is an authentication protocol designed to enhance the security of the online transactions made with payment cards. The 3D Secure authorization process works by adding an extra step of authentication before the transaction is authorized.

The payer is asked to provide additional authentication details. These can be a password, SMS code, fingerprint, bank app authorization, or other identity verification methods.

If the payer successfully completes the authentication process, the transaction will be processed to authorization. Otherwise, the transaction is declined.

The payer will be redirected to the success or error page

When the card payment is completed, the payer will be redirected to a success page or error page depending on whether the transaction was successful. Check the details on how to configure the success/error page.

Handle notification

We will notify you of the transaction status via transaction posting notifications.

On-site card transaction

An on-site card transaction involves providing a form on your website for the payer to enter card details.

When creating the transaction, encrypt the card data using the RSA public key available in the Merchant Panel.

• Acquirer Elavon - link to the Merchant Panel settings.
• Acquirer Pekao - link to the Merchant Panel settings.

Pass the encrypted value in the pay.cardPaymentData.card field.

Build a card payment form

To process a card payment, display the payment form on your website.

1. Show card payment as an available payment method.
2. Display Visa and Mastercard logos.
3. Include fields for the payer to enter:
   • Card number.
   • CVC/CVV code.
   • Expiration date.
4. Include the Tpay terms and conditions - link and information clause - link here.

Send a request to create a card transaction

To create a card transaction, send a POST request to the endpoint:

https://api.tpay.com/transactions

Specify the following parameters in the request:

The basic request body should look like this:

{
  "amount": 0.1,
  "description": "Test card payment",
  "payer": {
    "email": "[email protected]",
    "name": "John Doe"
  },
  "pay": {
    "groupId": 103
  }
}

After sending the request, you will receive a TransactionCreated schema in the response.

The key response parameters are:

Example response:

{
  "result": "success",
  "requestId": "858fa92dc62db44e2c1f",
  "transactionId": "ta_9jQLGqzeY2eOVK01",
  "title": "TR-CWM-CNYHA6X",
  "posId": "ps_e4dkPVDEm4Jg726q",
  "status": "pending",
  "date": {
    "creation": "2024-06-06 21:31:35",
    "realization": null
  },
  "amount": 0.1,
  "currency": "PLN",
  "description": "Test card payment",
  "hiddenDescription": "",
  "payer": {
    "payerId": "py_a9rjlZWxRLdG1bqY",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "",
    "address": "",
    "city": "",
    "country": "PL",
    "postalCode": ""
  },
  "payments": {
    "status": "pending",
    "method": "pay_by_link",
    "amountPaid": 0,
    "date": {
      "realization": null
    }
  },
  "transactionPaymentUrl": "https://secure.tpay.com/?title=TR-CWM-CNYHA6X&uid=01HZQGHZP5P3P7YV8A4BRVDX17"
}

Encrypt card data

Prepare a string according to the following format:

card number|card expiration date(MM/YY or MM/YYYY)|CVV or CVC code|host

Example:

1234567891234567|05/25|123|https://accountwebsite.com

Encrypt the string using the RSA public key: and PKCS#1 v1.5 - compliant padding schemes.

• Acquirer Elavon.
• Acquirer Pekao.

Pay the transaction using encrypted card data

To pay for the card transaction, use the previously stored transactionId,parameter by sending a POST request to the address:

https://api.tpay.com/transactions/{transactionId}/pay

Include transactionID in the URL, e.g.:

https://api.tpay.com/transactions/ta_jrkNGj5L29pnlbqw/pay

Specify the following parameters in the request:

The basic request body should look like this:

{
  "groupId": 103,
  "cardPaymentData": {
    "card": "SxzdtoeZWhbQ2jufH7qBj55KGMc722+ULiNZN0ZSYff5keLEtfw6PP+aVCxZBRigaUyN2krJ3xy/0zREs59j6EclpPrEGtdtHOow1iNaLaabNvTN9mVN2FVeV1BRzDD4FSex9V2AK7j0+YII4JtPhYlYx4URWHe/5UqEYQjyoWc="
  }
}

Example:

curl --location 'https://api.tpay.com/transactions/ta_9jQLGqzeY2eOVK01/pay'\
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token> '\
--data '{
  "groupId": 103,
  "cardPaymentData": {
			"card": "SxzdtoeZWhbQ2jufH7qBj55KGMc722+ULiNZN0ZSYff5keLEtfw6PP+aVCxZBRigaUyN2krJ3xy/0zREs59j6EclpPrEGtdtHOow1iNaLaabNvTN9mVN2FVeV1BRzDD4FSex9V2AK7j0+YII4JtPhYlYx4URWHe/5UqEYQjyoWc=",
	}
}'

After sending the request, you will receive a TransactionCreated schema in the response.

Handle 3D Secure

The status parameter with the value pending, indicates that the transaction requires additional 3DS authentication. Redirect the payer to the URL contained in the transactionPaymentUrl, parameter, where they can complete 3DS authentication.

Handle notification

We will notify you of the transaction status via transaction posting notifications.

Display the transaction result

After receiving the transaction status notification, use the tr_status field to display the transaction result.