Create Transaction

---

Introduction

---

This article explains how to create a transaction through the REST API.

This method is used to create a transaction.

It can also pre-validate the data entered according to your company's configured module. In this way, it is not necessary to open the IDPay capture experience in all cases.

Modules

---

No validation on transaction creation (post)

---

This module does not perform any pre-validation when creating a transaction. The status returned will always be waiting.

This option can be used in various scenarios, including:

• When the identification (CPF for example) is not necessarily that of the cardholder (this flow allows the user to enter 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.

With subset of validations at transaction creation (pre)

---

This module performs some pre-validations with the data entered. The status returned will be: waiting or fast-inconclusive.

This option can be used in various scenarios, including:

• When the identification (CPF for example) is that of the cardholder. This flow does not allow the user to enter a new CPF during validation, so if the identification entered is not consistent with the cardholder, this will result in a drop in the approval rate;

• When you want to minimize friction (opening up the IDPay capture experience) but without losing approval, maximizing the approval rate of transactions returned as waiting.

• When IDPay is at the top of the funnel;

• In a 100% integrated solution with Webview capture;

• Among others.

With all the validations when creating the transaction (super pre)

---

This module performs all pre-validations with the data entered. The status returned will be: waiting or fast-inconclusive.

This option can be used in various scenarios, including:

• When the identification (CPF for example) is that of the cardholder. This flow does not allow the user to enter a new CPF during validation, so if the identification entered is not consistent with the cardholder, this will result in a drop in the approval rate;

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

• When IDPay is at the top of the funnel;

• In a 100% integrated solution with Webview capture;

• Among others.

How to use?

---

Make a POST request to the /credit/transaction endpoint.

---

With a valid access token, make a request to the (POST/credit/transaction) endpoint, sending the following parameters:

{
    "identity": {
        "key": "cpf",
        "value": "CPF_DO_USUARIO"
    },
    "orderNumber": "NUMERO_DO_PEDIDO",
    "company": "ID_DA_EMPRESA",
    "redirectUrl": "URL",
    "card": {
        "binDigits": "6_OU_8_PRIMEIROS_DIGITOS_CARTAO",
        "lastDigits": "4_ULTIMOS_DIGITOS_CARTAO",
        "expirationDate": "DATA_VALIDADE_CARTAO",
        "name": "NOME"
    },
    "value": VALOR_COMPRA,
    "phone": "CELULAR_NOTIFICACAO",
    "email": "EMAIL_NOTIFICACAO",
    "captureBehavior": "COMPORTAMENTO_DE_CAPTURA",
    "additionalInfos": {
        "seller": {
            "identity": {
                "key": "cpf ou cnpj",
                "value": "CPF_OU_CNPJ_DO_USUARIO"
            }
        }
    }
}

The company field is provided by Unico.

The redirectUrl field is used to redirect the person to the desired url address. The redirection is done at the end of the flow (webview). This field is optional.

The expirationDate field is also optional.

The phone and email fields are not required. If the phone field is empty, the SMS is not sent. If the email field is empty, the E-mail is also not sent. There is a possibility of not completing these fields. In this case, sending can be done through whatsapp, app push, webview in app.

The name field must be sent with the correct name and beware of encoding problems, incorrect and/or invalid values can cause problems with approval in the flow. Since this field is used in the experience and communication with the user.

The captureBehavior field (optional), we have the following options:

• biometric: The identity authentication model used is biometrics only, for flows where we always want to have biometric capture.

• silent: The identity authentication model used is silent, validating only device metadata in this case, for flows where we don't want any friction (the approval rate is low).

• adaptive: This is a hybrid of the two above, using adaptive validation and biometrics. It is a flow with less friction, security and a better approval rate (default).

The additionalInfos field is used for additional information and its submission is optional. Currently it is possible to send additional information:

• Seller: Information about the seller of that transaction.

  • The identification of that seller (cpf or cnpj) can be sent.

The other fields are mandatory.

The orderNumber field must be filled in with the UNIQUE order number of that e-commerce purchase, it is wrong to send a different transactional ID.

It's important to pay attention to this field, as it can have a negative impact on the user experience in the final flow, causing problems when using the product.

Possible impacts include:

• Low conversion:

  • The order number is used to help the end user complete the flow;

• API errors:

  • You may receive errors such as: replicated transaction if the same order number, bin and last4 are used¹.

¹If the company is configured to reuse transactions with the same data, check the section Reuse of transactions.

If everything is right in the request, the response is a JSON with the transaction ID, transaction status, token that can be used in the iFrame and the capture link, as follows:

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "waiting",
    "link": "https://aces.so/teste",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

If the validations decides that it is not necessary to capture the biometrics, the response will have a different status and a link for the capture will not be generated, as follows:

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

If an error occurs, the response is a JSON with the error and the error code:

{
    "error": {
        "code": "40004",
        "description": "transaction id is invalid"
    }
}

The following is a list of possible errors returned by the service:

HTTP Code	Code	Description	Reason
400	40001	error decoding json	The data sent does not match the service contract
400	40002	error validating json	Some of the information is badly formatted or not filled in
400	40021	invalid phone	The phone is invalid. The default to be followed is 55 DDD NUMBER. Example: 5543999999999
400	40022	invalid email	The e-mail is invalid
400	40027	replicated transaction	Sent transaction already exists and cannot be recreated
400	40045	max value reached	When the transaction value exceeds the accepted limits
403	40301	not allowed	The user does not have permission to perform such an action.
404	40404	company not found	The company does not exist
429	40001	too many requests	Ratelimit reached
500	50001	internal error	Internal service failure

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 as a previously created transaction;

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

If the transaction to be created and the previous transaction do NOT meet these conditions, a new transaction will be created. Otherwise, these 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": "eyJhbGciOiJIUzI1NiIsIkpv[..]adQssw5c"
}

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

---

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.