Visa Mobile

Visa Mobile is a card payment method where the payer provides the phone number registered in the Visa Mobile service and then confirms the payment in their banking app or the Visa Mobile app.

To use Visa Mobile, the payer must activate the service in their bank's mobile app or install and activate the Visa Mobile app on their phone. The availability of Visa Mobile in the banking app depends on the bank's participation in the Visa Mobile program. If the bank does not provide this option, its cards can be used for Visa Mobile payments through the Visa Mobile app. Learn more about which banks and to what extent participate in this service here.

Find out more

Before you start

Ensure that:

You have API authorization data.
You handle transaction webhooks.
You have card payments enabled.
You have the Visa Mobile payment channel enabled.

Note

Visa Mobile is currently only available for Elavon acquirer. Check if your card payments are processed through this acquirer.

Visa Mobile transaction

Process Visa Mobile payments using the transaction creation endpoint with the groupId: 171.

Send a request to create a Visa Mobile transaction

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

https://api.tpay.com/transaction

Check the details in the API Reference documentation: POST /transactions

In the request, specify the following parameters:

amount	Transaction amount (in PLN).
description	Description of the transaction visible to the payer.
payer.email	Payer's email address.
payer.name	Payer's name.
pay.groupId	Payment group ID for Visa Mobile: 171.

The basic request body should look like this:

{
  "amount": 0.1,
  "description": "Visa Mobile test payment",
  "payer": {
    "email": "[email protected]",
    "name": "John Doe"
  },
  "pay": {
    "groupId": 171
  }
}

Example:

curl --location 'https://api.tpay.com/transactions' \
--header 'Authorization: Bearer <access_token> \
--header 'Content-Type: application/json' \
--data-raw '{
   "amount": 0.1,
   "description": "Visa Mobile test payment",
   "payer": {
      "email": "[email protected]",
      "name": "John Doe"
   },
   "pay": {
      "groupId": 171
   }
}'

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

Key response parameters:

result	success - The transaction has been successfully created.
status	pending - The transaction is awaiting payment.
transactionPaymentUrl	URL to redirect the payer.

Example response:

{
  "result": "success",
  "requestId": "f2a39301d8c269e69f8d",
  "transactionId": "ta_NmLeGv2e85MBGbEP",
  "title": "TR-BRA-CPBRFHX",
  "posId": "ps_NyRBLzV5kelrpjaM",
  "status": "pending",
  "date": {
    "creation": "2024-06-07 21:54:16",
    "realization": null
  },
  "amount": 0.1,
  "currency": "PLN",
  "description": "Visa Mobile test 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-BRA-CPBRFHX&uid=01HZT487JQ5PVSX4ZMJ9KWW57D"
}

Note

Store the transactionId in your system. More about transactionId.

Redirect the payer to the transaction panel

Redirect the payer to the URL provided in the transactionPaymentUrl field of the response.

Then, the payer enters their phone number in the payment form and confirms it.

The bank sends a push notification to the payer's bank app or the Visa Mobile app to confirm the payment. Upon receiving the notification in the app, the payer has 5 minutes to confirm the transaction. After this time, the transaction is canceled.

The Payer will be redirected to the success or error page

When the Google Pay payment is completed, the payer will be redirected to the success page or error page depending on whether the transaction was successful.

Handle the notification

We will inform you about the transaction status via the transaction webhook. Check the details.

Visa Mobile on-site

Visa Mobile on-site is the integration of Visa Mobile payments in your website/mobile application.

It involves placing a form for entering the phone number, allowing payers to make payments directly from your system or mobile application. The payment is made without redirecting to the transaction panel.

Note

The Visa Mobile on-site method is currently only available for the Elavon acquirer. Check if your card payments are processed through the Elavon acquirer.

Build the Visa Mobile payment form

To process Visa Mobile payments, display the payment form in your system.

Display Visa Mobile as an available payment method
Include a field where the payer can enter their phone number with the international phone code.
Implement a mechanism to validate the number before sending the payment
- type - string.
- minimum length: 7 characters.
- maximum length: 15 characters.
- only numeric characters without any spaces, dashes, letters, etc.
- it is necessary to pass the country phone code before the payer's number in the format XXYYYYYYYYY (e.g., 48123456789).

Send a request to create a Visa Mobile transaction, providing the phone number

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

https://api.tpay.com/transactions

Check the details in the API Reference documentation: POST /transactions

In the request, specify the following parameters:

amount	Transaction amount (in PLN).
description	Description of the transaction visible to the payer.
payer.email	Payer's email address.
payer.phone	Payer's phone number with country code.
payer.name	Payer's name.
groupId	Payment group ID for Visa Mobile: 177.

The basic request body should look like this:

{
  "amount": 0.1,
  "description": "Visa Mobile test payment",
  "payer": {
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "48123456789"
  },
  "pay": {
    "groupId": 171
  }
}

Example:

curl --location 'https://api.tpay.com/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token> \
--data-raw '{
   "amount": 0.1,
   "description": "Visa Mobile test payment",
   "payer": {
      "email": "[email protected]",
      "name": "John Doe",
"phone": "48123456789",
   },
   "pay": {
      "groupId": 171
   }
}'

Note

The payer.phone field is optional. If not provided, the response will generate a URL for the Transaction Panel. When this URL is opened in a browser, the payer will be able to enter the phone number necessary for the Visa Mobile payment.

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

Transaction successfully created

If the phone number is registered with Visa Mobile and the transaction is successfully initialized:

The payments.status: parameter will be returned as pending
The transactionPaymentUrl parameter will not be returned.

Upon initializing such a transaction, a notification request will be sent to the payer's app (either the Visa Mobile app or the banking app that supports this type of payment) to confirm the payment.

Handle the notification

We will notify your system of the transaction status via the webhook.

Display the transaction result

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

Transaction not successfully registered

If the phone number is not registered with Visa Mobile or the transaction cannot be successfully created:

The payments.status: parameter will be returned as declined
The transactionPaymentUrl parameter will be returned along with the URL for the Transaction Panel.

The phone number is incorrect

If the phone number is incorrect, meaning it does not meet the validation requirements described above, a HTTP Status 400 - Bad Request will be returned when creating the transaction.