# Payment transactions

### 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 [<mark style="color:blue;">**here**</mark>](broken://pages/2OdzKnzlALAhN6ymTIUN).

{% hint style="info" %}
**Base URL**:

* UA&#x54;**:** <mark style="color:blue;">`https://transactions.transactional.uat.unico.app/api/public/v1`</mark>**;**
* Productio&#x6E;**:** <mark style="color:blue;">`https://transactions.transactional.unico.app/api/public/v1`</mark>**.**
  {% endhint %}

## Create Transaction

> Endpoint to create a new transaction.

```json
{"openapi":"3.0.0","info":{"title":"Create Credit Transaction API","version":"1.0.0"},"servers":[{"url":"https://transactions.transactional.uat.unico.app/api/public/v1"}],"paths":{"/credit/transaction":{"post":{"summary":"Create Transaction","description":"Endpoint to create a new transaction.","parameters":[{"name":"Authorization","in":"header","required":true,"description":"Valid access token. The value must be sent in the format \"Bearer {token}\".","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["identity","orderNumber","company","card","value"],"properties":{"identity":{"type":"object","description":"User identification data.","required":["key","value"],"properties":{"key":{"type":"string","description":"Type of user identification key. We recommend that you use your CPF, as there is a higher conversion rate.","enum":["cpf","cnpj"]},"value":{"type":"string","description":"User identification key value. Must be sent without dots or dashes."}}},"orderNumber":{"type":"string","description":"Order number associated with the transaction. This data will be used as an index in the portal and can be used as a foreign key between your system and IDPay."},"company":{"type":"string","description":"ID of the company responsible for the transaction. This field is provided by Unico."},"redirectUrl":{"type":"string","description":"URL to which the user will be redirected after completing the transaction. Possible values are: An https URL to redirect web pages or a URL Schema for redirection in native mobile applications."},"card":{"type":"object","description":"Information about the card used in the transaction.","required":["binDigits","lastDigits","name"],"properties":{"binDigits":{"type":"string","description":"First 8 digits of the card."},"lastDigits":{"type":"string","description":"Last 4 digits of the card."},"expirationDate":{"type":"string","description":"Card expiration date."},"name":{"type":"string","description":"Cardholder's name. The name field must be sent correctly, avoiding encoding issues, incorrect or invalid values, which may cause problems with approval in the flow, as this data is used in the user experience and communication."}}},"value":{"type":"number","format":"float","description":"Total purchase value."},"mainContacts":{"type":"array","description":"These fields must be populated when IDPay is responsible for user notification. This is the list of main contacts ( emails and/or phone numbers ) used to immediately notify the user about a transaction. They will be used during the creation process and for resending notifications.","items":{"type":"object","properties":{"key":{"type":"string","description":"Contact type (ex.: 'phone', 'email')"},"value":{"type":"string","description":"Contact value."}}}},"fallbackContacts":{"type":"array","description":"These fields must be populated when IDPay is responsible for user notification and if there are fallback contacts. This is the list of fallback emails and/or phone numbers, which must be different from the main contacts. They will be triggered if the notification attempts to the main contacts fail. They will also be used in resendings, according to the configuration. Their use occurs after a certain time from the creation of the transaction.","items":{"type":"object","properties":{"key":{"type":"string","description":"Contact type (ex.: 'phone', 'email')"},"value":{"type":"string","description":"Contact value."}}}}}}}}},"responses":{"200":{"description":"Transaction successfully created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID of the created transaction."},"status":{"type":"string","description":"Current transaction status."},"link":{"type":"string","description":"Link related to the transaction."},"token":{"type":"string","description":"Signed token containing the necessary parameters to initialize Unico IDPay web SDK."},"expiresAt":{"type":"string","description":"Transaction expiration date and time in ISO 8601 (UTC) format."}}}}}},"400":{"description":"Invalid request data.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code."},"message":{"type":"string","description":"Error details."}}}}}},"403":{"description":"Access forbidden (invalid token or insufficient permissions).","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code."},"message":{"type":"string","description":"Error details."}}}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code."},"message":{"type":"string","description":"Error details."}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error code."},"message":{"type":"string","description":"Error details."}}}}}}}}}}}
```

{% hint style="danger" %}
To ensure better conversion, create the transaction **only after** completing any pre-authentication or validation that could finalize the operation before the IDPay experience.
{% endhint %}

{% hint style="danger" %}
The **orderNumber** field must be filled with the UNIQUE order number of that purchase in the e-commerce system, and using a distinct transactional ID is incorrect.

It is important to pay attention to this field, as it may negatively impact the user experience in the final flow, causing issues with product usage.

Possible impacts include:

* **Low Conversion**:&#x20;
  * The order number is used to help the end user complete the flow.
* **API Errors**:&#x20;
  * You might encounter errors such as "replicated transaction" if the same order number, cpf, BIN, and last4 digits are used.
    {% endhint %}

{% hint style="warning" %}
If the validations determine that biometric capture is not required, the response will have a different status, and a capture link will not be generated, as shown below:

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

This scenario will occur if you use the Pre or Super Pre modules, for cases where you use IDPay in the Checkout, as specified in the Features section.
{% endhint %}

{% openapi src="/files/8FvAfXuegsfHLmiHWHyg" path="/credit/transactions/{transaction\_id}" method="get" %}
[GetTransaction.yaml](https://4215638879-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwXjg7k5gG7wmNiFGOIuw%2Fuploads%2FbGbZU0OyEohuGOxLrd6t%2FGetTransaction.yaml?alt=media\&token=8abec42b-cacc-4da7-ab5a-2d6aab3bd7ce)
{% endopenapi %}

{% hint style="info" %}
To see all possible statuses, refer to the [<mark style="color:blue;">**Enumerated**</mark>](/unico-idpay/en/integration/apis/enumerated.md) section.
{% endhint %}

{% hint style="success" %}
To optimize the performance of your application, you can also implement our [<mark style="color:blue;">**Webhook**</mark>](/unico-idpay/en/integration/webhook.md) to know when to check the transaction status. See more in the Webhook section.
{% endhint %}

{% openapi src="/files/dBwIB9AbFseOqnX3kXFY" path="/credit/transactions/{transaction\_id}/probative" method="get" %}
[GetEvidence.yaml](https://4215638879-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwXjg7k5gG7wmNiFGOIuw%2Fuploads%2FUaEMvG64BbAjtGBxjLcY%2FGetEvidence.yaml?alt=media\&token=e4f6820a-6204-41a3-b6dc-1ee7d9ff4016)
{% endopenapi %}

{% hint style="warning" %}
The evidence set can only be generated for approved transactions.
{% endhint %}

{% hint style="danger" %}
The link returned for the evidence set is valid for five minutes after it is obtained. Therefore, it is important that this link is not saved, but rather used to download the evidence set.
{% endhint %}

{% openapi src="/files/EYSKUsGXL3ZlRIGHQr7P" path="/credit/transactions/{transaction\_id}/notify" method="post" %}
[ResendNotification.yaml](https://4215638879-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwXjg7k5gG7wmNiFGOIuw%2Fuploads%2FuKbP7bcw844tZ4JZmbb0%2FResendNotification.yaml?alt=media\&token=18a206a0-f3c1-4556-9649-d6651d6facfb)
{% endopenapi %}

{% hint style="info" %}
It is also possible to configure the resending of notifications through the portal, without the need to implement it via API. To understand the possibilities, speak with the person responsible for your project.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devcenter.unico.io/unico-idpay/en/integration/apis/api-reference/payment-transactions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.