Introduction

As highlighted in the previous sections, Unico IDPay offers liability guarantee, ensuring maximum accuracy in the validations performed. Unico's Chargeback protection shields you from potential losses in transactions where the cardholder's identity was incorrectly validated by IDPay.

If a transaction validated by IDPay results in an official chargeback process, properly formalized with the acquirer or card network, the IDPay customer may be reimbursed by Unico for the equivalent transaction amount. This guarantee is applicable upon verification, after proper investigation, that there was an error in the validation performed by IDPay and that Unico was responsible for the incorrect decision.

This additional security demonstrates Unico IDPay's commitment to providing reliability and protection in operations carried out with its solution.

When to use this option?

When you have received a chargeback request due to fraud and believe that there was an error by IDPay in validating the credit card holder's identity.

What is chargeback?

Chargeback is the process of investigating a dispute of a purchase/transaction made with credit/debit cards on online platforms, which may result in a reversal/cancellation of the purchase/transaction. Chargebacks can be classified into two main categories:

• Chargeback due to Commercial Disagreement: When a transaction needs to be canceled due to an issue in the consumer-to-business relationship. Examples: Goods not delivered, defective goods, purchase cancellation, duplicate purchase, service not provided, etc.

• Chargeback due to Fraud: When the cardholder claims that they did not make a purchase in their name, initiating a dispute between the parties (who bears the loss).

Chargeback analysis can only be requested in cases of chargeback due to fraud.

Prerequisites for requesting chargeback analysis

Chargeback analysis can only be requested for transactions that meet all of the following conditions:

• The transaction must have been approved (status: approved);

• The transaction must have been created within the last 90 days;

• The transaction must not have been submitted for another chargeback analysis;

• The transaction must be of the "credit" type.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Introduction

Unico IDPay offers a wide range of endpoints, modules, and features, designed to adapt to different scenarios and use cases. Below, we present the key definitions and applications of each feature.

Payment Transactions

The first major feature of IDPay is to validate each transaction made within the establishment, ensuring that the sale can be processed for that user.

Transactions are organized into different modules, each designed to address specific scenarios and varied needs. Explore the available modules and see how each one can be applied to your use case:

Modules

With a subset of validations in transaction creation (Pre)​

This module performs some pre-validations with the provided data. The returned status will be: waiting or fast-inconclusive. The link for biometric capture will only be provided if we are able to validate the user's CPF/credit card number.

This option can be used in various scenarios, including:

• When the provided identification (e.g., CPF) belongs to the cardholder. This flow does not allow the user to provide a new CPF during validation, so if the provided identification is not consistent with the cardholder, it will negatively impact the approval rate;

• When you want to minimize friction (opening the IDPay capture experience) without sacrificing approval, maximizing the approval rate of transactions returned as 'waiting';

• When IDPay is at the top of its fraud prevention funnel;

• In a 100% integrated solution with capture via Webview or iFrame;

• Among others.

With all validations in transaction creation (Super Pre)

This module performs all pre-validations with the provided data. The returned status will be: waiting or fast-inconclusive. The link for biometric capture will only be provided if we are able to validate the user's CPF/credit card number.

This option can be used in various scenarios, including:

• When the provided identification (e.g., CPF) belongs to the cardholder. This flow does not allow the user to provide a new CPF during validation, so if the provided identification is inconsistent with the cardholder, it will negatively impact the approval rate;

• When you want to minimize friction (opening the IDPay capture experience) with a small loss in approval, maximizing the approval rate of transactions returned as 'waiting';

• When IDPay is at the top of its fraud prevention funnel. In a 100% integrated solution with capture via Webview or iFrame;

• Among others.

Without validation in transaction creation (Post)

This module does not perform any pre-validation when creating a transaction. The returned status will always be 'waiting', and the link will always be provided for the user to perform the biometric capture.

This option can be used in various scenarios, including:

• When the provided identification (e.g., CPF) is not necessarily that of the cardholder (this flow allows the user to provide a new CPF during the capture experience);

• When you want to use the IDPay capture experience for all transactions;

• Preferably for sales recovery;

• Among others.

Credit Card Onboarding

With this functionality, you can onboard your users' credit cards to your digital wallet, ensuring that the card belongs to the correct cardholder.

What differentiates this functionality from Payment Transactions are the endpoints and specific parameters of the REST API, which have been developed to optimally meet the needs of card validation and registration in your solution.

Continue reading with the suggested link below:

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Unico IDPay is an innovative solution from Unico that combines, in a single verification, both the identification of the shopper and the validation of the credit card's ownership. This approach ensures safer transactions for remote purchases and helps recover sales that could otherwise be lost due to payment inconsistencies.

With IDPay, you ensure that:

• The user is live at the moment of the transaction;

• The identity matches the credit card holder;

• The credit card belongs to the person performing the transaction at your establishment;

  • The authorized and validated use of third-party cards is possible.

The operation is simple and efficient: a transaction is created from the credit card number and the cardholder's CPF, and IDPay handles the authentication of that transaction, either through facial biometrics or device metadata authentication.

In addition, IDPay is highly flexible and can be tailored to meet different scenarios and needs. Its platform offers a wide range of features that support various use cases, making it ideal for operations that require precision and security.

For a better understanding of IDPay, follow the suggested sequence in the menu below and explore all the possibilities the product offers:

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Overview

Welcome to the Unico IDPay REST API documentation! On this page, you will find everything you need to know to enhance the security and quality of your applications using our REST API.

Read more

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

The errors returned in the request can be identified by the codes below and have the following structure:

{
  "error": "server_error",
  "error_description": "Falha na autenticação x.x.x"
}

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Use Cases

IDPay can be used in various use cases and in many different ways. Below, check out the possible use cases and their correlations.

Checkout

Pre-analysis table

Analysis table tool

Sales recovery

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

To use IDPay, it is necessary to authenticate via access token, using the OAuth2 authentication system.

Unico's OAuth2 authentication system supports server-to-server interaction between a web application and Unico's services.

For this scenario, you will need a service account, which is a non-personal account that belongs to your application and not to an individual user. Your application calls Unico's APIs on behalf of the service account, so users are not directly involved. This scenario is called 'two-legged OAuth' or '2LO'. Typically, an application uses a service account when the application calls Unico's APIs to work with its own data rather than user data.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Integration Overview

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

After creating and configuring a service account, your application needs to complete the following steps:

1. Create a JSON Web Token (JWT), which includes the header, payload, and signature;

2. Request an access token (AccessToken) from the OAuth2 authentication platform;

3. Handle the JSON response that the authentication platform will return.

If the response includes an access token, you can use it to make requests to Unico's product APIs for which the service account has access permissions. (If the response does not include an access token, your JWT and token request may be incorrect, or the service account may not have the necessary permissions to access the requested resources.)

The access token generated in the request mentioned above has a default validity of 3600 seconds, but this may vary depending on the security configuration set for your company. When the access token expires, your application should generate a new JWT, sign it, and request a new access token from the authentication platform.

1 - Creating the JWT

A JWT consists of three parts: a header, a payload, and a signature. The header and payload are JSON objects. These JSON objects are serialized in UTF-8 and then encoded using Base64url encoding¹. This encoding provides resilience against encoding changes in cases of repeated encoding operations. The header, payload, and signature are concatenated with a period (.) character.

A JWT is composed as follows:

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

The base text for the signature is composed as follows:

{Header in Base64url}.{Payload in Base64url}

1.1 - Forming the JWT Header

The header consists of two fields that specify the signing algorithm and the token format. Both fields are mandatory, and each field has only one value. Service accounts rely on the RSA SHA-256 algorithm and the JWT token format. As a result, the JSON representation of the header is as follows:

{"alg":"RS256","typ":"JWT"}

The Base64url representation is as follows:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

1.2 - Forming the JWT Payload

The JWT payload contains information about the JWT, including the requested permissions (scopes), the account requesting access, the issuer, the time when the token was issued, and the token's lifetime. Most fields are mandatory. Just like the JWT header, the payload is a JSON object and is used in the composition of the signature.

1.3 - Mandatory Fields

The mandatory fields in the JWT are shown in the table below. They can appear in any order within the payload.

Understand how the conversion works for the issuance (iat) and expiration (exp) fields of the JWT, and also see examples of how to use these field values here. In addition, the 'iat' field must represent the current time in the required format, and the 'exp' field must respect the following calculation:

exp = iat + 3600

The representation of the mandatory JSON fields in the JWT payload is as follows:

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, // This is just an example. Use the current value generated here.
  "iat": 1626293376 // This is just an example. Use the current value generated here.
}

1.4 - Calculating the Signature

The JSON Web Signature (JWS) specification is the mechanism that guides the calculation of the signature for a JWT. The input content for the signature calculation is the byte array of the following content:

{Header in Base64url}.{Payload in Base64url}

The same algorithm specified in the JWT header must be used for calculating the signature. The only signature algorithm supported by the OAuth2 authentication platform is RSA using SHA-256. It is expressed as RS256 in the alg field of the JWT header.

Sign the UTF-8 representation of the input content using SHA256withRSA (also known as RSASSA-PKCS1-V1_5-SIGN with the SHA-256 hash) with the private key that was created and associated with the service account (the .key.pem file generated from the request received by email). The output content will be a byte array.

The signature then needs to be encoded in Base64url. The header, payload, and signature should be concatenated with a period character. The result is the JWT. It should be as follows:

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

Here is an example of a JWT token before Base64url encoding:

{"alg":"RS256","typ":"JWT"}.
{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, // This is just an example. Use the current value generated here.
  "iat": 1626293376 // This is just an example. Use the current value generated here.
}.
[byte array da assinatura]

Below is an example of the JWT that has been signed and is ready for transmission:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRf
bmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb
3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ.JsymP3NZdgCSqeNlgsOM2
-AQ7M450NxFnZnnaKSu4Q8g12QGEIvvM4EhCokUHfwk5s7pOpm2UD_Ng3Hb5g_wgrjfiVSLWH5Q2wYg1AvfLqo
YSoJWaMHm9KL0kpv32XdDD8TZVR-MVd2VBHmCMVbV6gvk8buUoK1HZDN7g84PaY3bfgcB3RKU-
H55lR8yyJjZxToIv17-wfla2G99uaMEFNGX0ZSE7ETn5Z8-WypmFrNAK0TM58upzvfVI6_-
gY4cj4iQvmRbuvxsAaGiHA2xd0RVm2Mrx-gQtdPqtbZPuQcH7k64Z_EOQBgiGTgVjucyHD6zBijr_P-
2mhIxuecNSw

It is also possible to use pre-established libraries to create the JWT. As a reference, you can find a list of libraries on the jwt.io website.

2 - Making a request for an access token

After generating the signed JWT, an application can use it to request an access token. The access token request is a POST HTTPS request, and the body should be URL encoded. The URL is shown below:

https://identityhomolog.acesso.io/oauth2/token

The following parameters are mandatory in the POST HTTPS request:

POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-
bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY
291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsInN1YiI6InVzZXJfaWRlbnRpZmllciIs
ImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI
6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.TjH-mTtwP6tBB93O1sDPaAA6yUF7N2-HZDlpIPz
bf_dxO8A6KZuRWG8ZnICrxX56qj0HREiMlYy27XJgxowrUa0JHvbqc8HJkT7-6Mh7J67UnubZKG1-hi
6jDtkC9BIXBcOhtkNUfZvZetXjLzsRsSDkqxdMtzYZwkRlocvaxL5QXiQhweeEwK_Ux81Adh3z0EIhT
yl7CKJLJ69PuHS7s9IdrjUl79owipp4LF1FvtMhoe7YIL69ohPgFqSv_-Y9qpPdW6be3OEAyKlOM08S
ZBbHBwW4XMvw3uZjTY1sgJ4cBoxrftDpjYOw34oPOKxirqc5-90uOCYe1O1hRtG45w

3 - Handling the Authentication Platform's Response

If the JWT and the access token request are properly formed, and the service account has the necessary permissions, the authentication platform will return a JSON object containing an access token. Here’s an example of the response from the platform:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

The access token returned in the "access_token" field of the JSON object is also a JWT token that should be used in the APIs of Unico's Products. If an error occurs in the request, you can check the error type in the error table by clicking here.

4 - Duration of the Access Token

The duration of the access token is variable. Its duration is specified in the "expires_in" field, which is returned along with the access token. The same access token should be used throughout its validity for all API calls to the products.

Do not request a new access token until the validity of the current token is nearing its end. We recommend a margin of 600 seconds (10 minutes). To do this, perform the following calculation:

token decodificado:
new Date(token.exp - 600)

Where token.exp is the timestamp of the token's expiration.

Examples:

Standard scenario:
expires_in: 3600 (1h) - Token generated at 14:42

Request a new token only at 15:32, that is, 14:42 + (3600 - 600)

Scenario with modified duration:
expires_in: 7200 (2h) - Token generated at 14:42

Request a new token only at 16:32, that is, 14:42 + (7200 - 600)

A new access token can be requested when there are 10 minutes left until expiration.

• ¹ According to RFC 4648 for BaseN encoding, the Base64url format is similar to Base64, except that the '=' character is omitted, and the characters '+' and '/' are replaced by '-' and '_', respectively.

• ² JSON Web Signature: https://tools.ietf.org/html/rfc7515.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

To use server-to-server interactions, you need to request the creation of a service account by contacting the project manager responsible for your company and sending the following information: company name, application name, name, email, and phone number of the person responsible for the application within the company. Separate accounts must be created for the Testing and Production environments.

Once these details are received, a service account will be created to authenticate your application, and we will send an email for you to generate the key pair for the account.

A service account credential includes a unique account name, a company identifier (Tenant ID), and at least one key pair (public and private). After generating the keys, you will only receive the private key (file .key.pem), as well as the payload that should be used to create the JWT. This payload will have the following format:

If you need the public key to configure it in your system, please contact the project manager responsible for your account. It is also possible to generate a public key using the following openssl command:

openssl req -x509 -new -nodes -sha256 -days 720 \
-key fileName.key.pem -out fileName.cert.pem

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Introduction

Unico IDPay uses conventional HTTP response codes to indicate the success or failure of an API request.

As a general rule:

• Codes in the 2xx range indicate success with the request.

• Codes in the 4xx range indicate incorrect or incomplete parameters (for example, a mandatory parameter was omitted, or an operation failed with third parties, etc.).

• Codes in the 5xx range indicate an error on the Unico IDPay product servers.

Unico IDPay also generates an error message and an error code formatted in JSON:

Possible Errors

In this topic, you will find the possible errors for the endpoints, separated by their HTTP response.

Transaction Creation

Transaction status query

Recovery of the evidentiary set of the transaction

Resending the transaction notification

Transaction cancellation

Download the file below, import it into Postman, and replace the values of the parameters "service_account", "tenant_id", and "secret_key" to test the call.

The GetProcess articles in this documentation describe a way to retrieve the status of a process by calling an endpoint. This allows polling to receive information about the created processes. This means that the endpoint can be called multiple times for the same process to get the most recent status.

By using webhooks, it is possible to notify a specific endpoint every time the status of a process is changed.

What is a webhook?

A webhook is a system notification service that enables asynchronous integration between systems, where one system notifies the other through a trigger. This way, webhooks can keep systems updated with the latest information without the need for constant polling for updates.

How to configure the Webhook

To configure the webhook, the following information is required:

• Notification URL: This is the endpoint used by By Unico for notifications about status updates.

• Authentication Type: This is the authentication method used to invoke the endpoint. The following options are available:

  • Basic Authorization;

  • API Key;

  • No authentication.

• Secret: Indicates a secret used for authentication. The secret is only required when the authentication type is Basic Authorization or API Key:

  • For Basic Authentication, it must be sent in the format user:pass.

  • For API Key, it can be sent in two formats:

    • header:value, when a specific header name is desired;

    • value, when the desired header is Authorization.

• Retry Settings: Indicates the number of retry attempts in case the endpoint call fails:

  • Maximum number of attempts;

  • Interval between attempts (in seconds);

  • Rate Limit: Maximum number of simultaneous submissions (max: 500);

  • Timeout: Maximum waiting time for the endpoint response (in seconds).

• Status to be notified: You can subscribe to specific statuses to receive notifications. These include:

  • approved: Transaction approved;

  • processing: Transaction in processing;

  • inconclusive: We couldn't perform a conclusive validation;

  • shared: Transaction shared, waiting for submission;

  • skipped: The person skipped the biometric capture in the flow;

  • unknown-share: The person marked that they don’t recognize the purchase;

  • absent-holder: The cardholder is not present to perform the capture;

  • expired: The person didn’t complete the capture within the established time and the transaction was expired.

Integration with IDPay

By configuring a webhook on the platform, you can receive information about processes through notifications sent to an API endpoint developed by you to receive these updates.

The information sent by the platform to the API includes:

• ID: Transaction ID;

• Status: Transaction status.Integration with IDPay

Requests

The request should be a POST method in a REST API, making it easier and more secure to send the information. All fields should be mandatory. The request body should accept the transaction ID and the status, as shown in the following example:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved"
}

Response

The response should be synchronous. The status for successful requests should be in the range of 200 to 299. Any other status will be considered a failure, and IDPay will make additional notification attempts (with exponential backoff between them), until receiving a 2xx response or reaching the maximum number of attempts.

Response Status

Currently, we have a set of statuses, but this set may change in the future. Therefore, it is recommended to make configurable the statuses that the client is interested in to take action. For example, if the intention is to take action every time a capture is successfully completed, this currently happens with the status "processing." However, since this could be modified in the future, it is recommended that the status indicating successful capture be configurable in the system, so a future change to the "captured" status can be easily implemented.

Additionally, we recommend having specific actions for specific statuses and a general action in case the status is unrecognized (for example, assuming that anything different from "processing" and "approved" is inconclusive). This is important because new statuses may appear in the future, and it is not expected for the webhook to break due to this.

Important Considerations

Pay attention to the following aspects when developing the API that IDPay will use to notify status changes:

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Introduction

Unico IDPay offers a simple and fast integration. Currently, we standardize integration in applications (mobile or web) through the use of Webview, SDK, and Redirect. This standard enhances the security of your business and customers, abstracting the complexity of handling the users' device camera and capturing selfies.

In our REST API, we provide methods for generating integration links that can be opened and controlled by the applications.

Generating Data in the API

Before moving on to the integration details in your application or website, it is crucial to start by integrating with our API. In this process, two key points will be used:

1. Create Transaction (CreateTransaction):

   • Make sure to fill in the redirectUrl field, as it will be essential for the integration flow.

After completing this initial step, you will be ready to continue with the integration in your application or website.

It is important to remember that once the entire flow is completed, you will need to obtain the transaction result via our API to ensure the process is properly concluded.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Transaction Result

Chargeback result

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Before you begin

Your API requests are authenticated using an access token. Any request that does not include a valid access token will return an error.

You can learn more about how to generate an access token here.

Chargeback Analysis Request

Check the status of the chargeback analysis

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Before you start

Your API requests are authenticated using an access token. Any request that does not include a valid access token will return an error.

You can learn more about how to generate an access token here.

Credit Card Validation

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "fast-inconclusive"
}

Get the validation status

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

For the Android use case, using a Webview is recommended. After creating the transaction and obtaining the transaction link, the following implementation is recommended:

• In your regular flow (where IDPay is integrated), you will open the Webview with the link generated via API.

• You can customize how this opening works in the way that best fits your application.

• You will monitor if there is a URL change (to the redirectUrl) and then close the Webview.

Opening a Webview is quite simple:

import android.webkit.PermissionRequest
import android.webkit.WebChromeClient
import android.webkit.WebView
import android.webkit.WebViewClient

@SuppressLint("SetJavaScriptEnabled")
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_camera)

    findViewById<WebView>(R.id.webView).apply {
        settings.javaScriptEnabled = true
        settings.domStorageEnabled = true
        settings.mediaPlaybackRequiresUserGesture = false
        clearCache(true)
        webViewClient = myWebViewClient
        webChromeClient = object : WebChromeClient() {
            override fun onPermissionRequest(request: PermissionRequest?) {
                request?.grant(request.resources)
            }
        }
        loadUrl("<URL_TO_LOAD>")
    }
}

To control when it is necessary to close the Webview, it can be done as follows:

private val myWebViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(
        view: WebView?,
        request: WebResourceRequest?
    ): Boolean {
        if (request?.url.toString() == "<URL_TO_OBSERVER>") {
            // close here your webview
        }
        return super.shouldOverrideUrlLoading(view, request)
    }
}

To do this, it is necessary to enable permissions in the Android Manifest:

<uses-feature android:name="android.hardware.camera" android:required="false"/>
<uses-permission android:name="android.permission.CAMERA"/>

Example of how it should look in the app:

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Before you begin

Your API requests are authenticated using an access token. Any request that does not include a valid access token will return an error.

You can learn more about how to generate an access token here.

Transaction creation

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "fast-inconclusive"
}

Reuse of Transactions

It is possible to configure the company to reuse transactions that have the same data, avoiding "replicated transaction" errors. The reuse will occur under the following conditions:

• A transaction is being created with the same orderNumber, identity.key, identity.value, company, card.binDigits, card.lastDigits, and value of a previously created transaction.

• The previous transaction has not yet exceeded the expiration time configured for the company.

If the transaction to be created and the previous transaction do not meet these conditions, a new transaction will be created. Otherwise, the following are the possible responses:

If the previous transaction is in a final status, such as approved or inconclusive:

{
    // previous transaction information
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

If the previous transaction is still in an initial status, such as waiting or shared:

{
    // previous transaction information
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "waiting",
    "link": "https://aces.so/teste",
    "token": "eyJhbGciOiJIUzI1NiIsIn[...]dQssw5c"
}

In this last case, the transaction still in an initial status will have its expiration date recalculated, based on the date of this request.

Transaction status query

Obtaining the set of evidence for the transaction

Resending the transaction notification

Transaction cancellation

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

For web usage, the recommended approach is to use the Unico SDK for the following reasons:

• Higher security;

• Integrated experience with your flow;

• Higher conversion rate when using the SDK;

• Easier implementation.

How to get started

To use IDPay through the Unico IDPay SDK, the first step is to register the domains that will be used as hosts to display the user journey experience.

To begin using the SDK, we should start with the installation of the Unico web SDK:

Available Methods

Security

After careful analysis of the needs and challenges we face, we decided to adopt a solution based on iFrames with authentication tokens instead of implementing a Content Security Policy (CSP). This decision was driven by several considerations related to security and the flexibility required to meet our clients' demands.

Context and Challenges with CSP

The Content Security Policy (CSP) is a powerful tool to protect web applications against various types of attacks, such as Cross-Site Scripting (XSS) and code injection. However, when configuring a CSP policy, it is necessary to define a strict list of trusted domains. This approach works well when domains are fixed and predictable. However, for our clients who often use dynamic and variable domains, this rigid configuration presents significant challenges.

Vulnerability with Dynamic Domains

Dynamic domains pose a substantial security risk when using CSP. When a client has domains that change frequently or are created dynamically, it would be necessary to constantly update the CSP policy to include these new domains. This not only increases the maintenance effort but also exposes the domains that the CSP policy applies to. Each domain added to the CSP policy is potentially a point of vulnerability if not properly managed.

Solution with iFrame and Auth Token

To mitigate these risks and meet the flexibility required by our clients, we opted to use iFrames combined with authentication tokens. This solution provides an additional layer of security and eliminates the need to expose or manage an extensive and dynamic list of domains.

How It Works

• Secure Authentication: Each iframe is loaded with a unique authentication token for each transaction, ensuring that only authorized users can access the content. This token is verified in real-time, providing an additional layer of security and control.

• Content Isolation: The use of iFrames allows content to be isolated in a separate context, reducing the risk of interference between different origins and mitigating potential attacks.

• Flexibility for Dynamic Domains: By not relying on a static CSP policy, our solution easily adapts to clients' dynamic domains without the need for constant updates to security policies.

The web version offers the option to use the redirect model, but the iframe model is the most recommended.

1) Using window.open()

When creating the transaction, the redirectUrl field was passed as a parameter, which will be used later. You can use this option.

The window.open() option consists of opening a new browser tab for the user to complete the capture flow. Once done, the tab will close and redirect back to the previously visited site. We recommend:

• Follow the public documentation on this, which can be found here;

• Monitor if the URL has changed (to the redirectUrl), and then close the tab using window.close().

2) Using redirect

When creating the transaction, the redirectUrl field was passed as a parameter, which will be used later. You need to follow these steps:

• In your regular flow (where IDPay is integrated), you will redirect the customer to the link generated via the API;

• After this, the customer within the IDPay webpage will complete the necessary steps to continue the flow;

• Once completed, they will be redirected back to your page (using the redirectUrl passed when creating the transaction).

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Frequently asked questions about the Unico IDPay:

• Click here to access the IDPay FAQ;

• Click here to access the Unico general FAQ.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

For iOS usage, using ASWebAuthenticationSession is one of the recommended approaches.

After creating the transaction and obtaining the transaction link, the following implementation is recommended:

• In your regular flow (which includes IDPay), you will open the ASWebAuthenticationSession with the link generated via API.

• You can customize this opening in the way that works best for your app.

• You will monitor if the URL has changed (to the redirectUrl) and then close the page.

To make the flow work, you need to follow the following steps:

Step 1: Create the Payment Authentication Controller

The first step is to create the payment authentication controller. To do this, create a class called IDPayAuthenticationController (or any name you prefer).

Next, import the AuthenticationServices framework at the top of the class.

Declare the class as NSObject and implement the ASWebAuthenticationPresentationContextProviding protocol.

The result should be:

import AuthenticationServices

class IDPayAuthenticationController: NSObject, ASWebAuthenticationPresentationContextProviding {
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
           if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene {
               if let mainWindow = windowScene.windows.first {
                   return mainWindow
               }
           }
           return ASPresentationAnchor()
       }
}

Step 2: Implement Authentication

Open the file where you will perform the authentication and add the necessary imports (in our example, we are doing this in ContentView.swift).

import SwiftUI
import AuthenticationServices

To control the authentication state, we will create a @State property.

@State private var isAuthenticated = false

Create an instance of the IDPayAuthenticationController class outside the body of the ContentView structure.

let idPayController = IDPayAuthenticationController()

To validate the payment, create a function called authenticatePayment.

func authenticatePayment() {
    guard let url = URL(string: "URL_AUTHENTICATION") else { return }

    var session: ASWebAuthenticationSession?
    session = ASWebAuthenticationSession(url: url, callbackURLScheme: "BUNDLE") { callbackURL, error in
        guard callbackURL != nil else {
            if let error = error {
                return print("Erro durante a autenticação: \(error.localizedDescription)")
            }
            return
        }

        // Processa o URL de callback para verificar se a autenticação foi bem-sucedida
        session?.cancel()
        isAuthenticated = true
    }

    session?.presentationContextProvider = idPayController
    session?.prefersEphemeralWebBrowserSession = true
    session?.start()
}

Example of how it should look in the app:

For more information, we recommend reading the following articles and documentation:

To access the official documentation, click here.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

For the iOS usage scenario, using WKWebView is one of the recommended approaches.

After creating the transaction and obtaining the transaction link, the following implementation is recommended:

• In your common flow (which includes IDPay), you will open the WKWebView with the link generated via the API;

• You can customize this opening as needed for your app;

• You will monitor if the URL has changed (to the redirectUrl) and then close the WKWebView.

Opening a WKWebView is quite simple:

import UIKit
import WebKit
import SafariServices

var webView: WKWebView!

override func viewDidLoad() {
    super.viewDidLoad()
    // Do any additional setup after loading the view.
    self.view.backgroundColor = .white
}

@IBAction func open(_ sender: Any) {
    createWKWebViewFull()
}

func createWKWebViewFull() {
    webView = WKWebView(frame: self.view.bounds, configuration: getWKWebViewConfiguration())
    webView.navigationDelegate = self
    view.addSubview(webView)
    self.loadUrl()
}

func loadUrl() {
    if let url = URL(string:"<URL_TO_LOAD>") {
        webView.load(URLRequest(url: url))
        webView.allowsBackForwardNavigationGestures = true
    }
}

private func getWKWebViewConfiguration() -> WKWebViewConfiguration {
    let config = WKWebViewConfiguration()
    config.allowsInlineMediaPlayback = true
    config.mediaTypesRequiringUserActionForPlayback = []

    return config
}

To control when to close the WKWebView, this can be done as follows:

func webView(_ webView: WKWebView, didCommit navigation: WKNavigation!) {
    if let currentURL = webView.url {
        print("URL changed to: \(currentURL.absoluteString)")
        if currentURL.absoluteString == "<URL_TO_OBSERVER>" {
            closeWebView()
        }
    }
}

@objc func closeWebView() {
    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
        self.webView.removeFromSuperview()
    }
}

Example of how it should look in the app:

To learn more, we recommend reading the following articles and documentation:

• To access the official documentation, click here.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

For the use case using Flutter, it is recommended to use inappwebview.

After creating the transaction and obtaining the transaction link, the following implementation is recommended:

• In your common flow (which includes IDPay), you will open the inappwebview with the link generated via the API;

• You can customize this opening as needed for your application;

• You will monitor if the URL changes (to the redirectUrl) and then close the inappwebview;

To open an inappwebview and control URL changes, you can do it as follows:

  import 'package:flutter_inappwebview/flutter_inappwebview.dart';  
  import 'package:unico_poc_id_pay_inappwebview/RedirectScreen.dart';
  import 'package:unico_poc_id_pay_inappwebview/service.dart';

  Widget setWebView(String URL_TO_LOAD) {
    InAppWebViewGroupOptions options = InAppWebViewGroupOptions(
        crossPlatform: InAppWebViewOptions(
          useShouldOverrideUrlLoading: true,
          mediaPlaybackRequiresUserGesture: false,
        ),
        android: AndroidInAppWebViewOptions(
          useHybridComposition: true,
        ),
        ios: IOSInAppWebViewOptions(
          allowsInlineMediaPlayback: true,
        ));

    return Expanded(
      child: InAppWebView(
        initialUrlRequest: URLRequest(
          url: Uri.parse(URL_TO_LOAD),
        ),
        initialOptions: options,
        androidOnPermissionRequest: (controller, origin, resources) async {
          return PermissionRequestResponse(
              resources: resources,
              action: PermissionRequestResponseAction.GRANT);
        },
        onWebViewCreated: (controller) {
          setState(() {
            _inAppWebViewController = controller;
          });
        },
        onLoadStart: (controller, url) {
          print('CARREGANDO');
          setState(() {
            _link = url.toString();
          });
        },
        onProgressChanged: (controller, progress) {
          setState(() {
            progress == 100 ? _isLoading = false : _isLoading = true;
          });
        },
        onLoadStop: (controller, url) {
          print('CARREGADO');
          setState(() {
            _link = url.toString();
          });
        },
        shouldOverrideUrlLoading: (controller, navigationAction) async {
          var uri = navigationAction.request.url;
          if (uri == Uri.parse("<URL_TO_OBSERVER>")) {
            setState(() {
              _link = "";
            });

            Navigator.push(
              context,
              MaterialPageRoute(
                builder: (context) => const RedirectSreen(),
              ),
            );
            return NavigationActionPolicy.CANCEL;
          }
          return NavigationActionPolicy.ALLOW;
        },
      ),
    );
  }

To obtain camera permission, you can do it as follows:

  import 'package:permission_handler/permission_handler.dart';

  void requestPermission() async {
    var status = await Permission.camera.status;
    if (status.isDenied) {
      if (await Permission.camera.request().isGranted) {
        print("ok");
      }
    }
  }

To obtain camera permission, you can do it as follows:

For more information, we recommend reading the following articles and documentation:

• To access the official documentation, click here.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

To use the Unico IDPay product, there are some prerequisites, which are as follows:

• iOS: From version 11.0 (if opened in WebView, iOS 13 and above).

• Android: From version 5.1 (if opened in WebView, Android 8 and above).

• Desktop: No specific version or OS requirements.

The capture frame provided through the SDK is compatible with the following combinations of browsers and operating systems:

In general, the SDK supports WebRTC and the latest versions of the browsers listed above. For compatibility and security reasons, functionality in very old versions of these browsers is not guaranteed.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Logo Customization

It is possible to customize the logo displayed to the end user, as shown in the image below:

To request the inclusion of this logo, you need to send the Unico team an image in .PNG format, with a size of 56x56px.

Button Color and Shape Customization

Throughout the implementation process, it is possible to request the configuration of the color and shape of the buttons in the IDPay interface, according to the company’s visual identity, as shown in the images below:

To configure this, simply send the following information to the Unico team:

• Hexadecimal color code for the button's background.

  • Example: #000000.

• Hexadecimal color code for the button’s text.

  • Example: #ffffff.

• Button corner rounding in pixels.

  • Example: 10px.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

How to communicate identity validation via IDPay to the consumer?

We know that biometric validation performed by a third-party provider can raise doubts and friction with your end users. Therefore, it is important to provide transparency about this process and offer proper support to ensure good results for your operation. Below, you'll find a series of tips that can assist you in this communication:

• Communicate that a partner company (preferably mention Unico) may contact the user via SMS, email, or WhatsApp requesting a photo of their face for facial biometric validation.

• Inform that, in some cases, they will need to confirm their CPF number, which is used to verify the digital identity of the credit card holder.

• Explain that the identity validation is specific to the credit card holder to ensure consent for using the card.

• Warn the consumer not to provide any personal information or photos via email, SMS, or WhatsApp. The entire validation flow occurs within the link sent.

• Notify/train the customer service team to handle any questions or concerns from the consumer.

• Include a section in your FAQ page detailing this validation process.

• Provide the link to our help center:

Still need help?

Didn't find something or still need help? If you're already a client or partner, you can reach out through our .