# Credit card onboarding

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

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

* UAT: <mark style="color:blue;">`https://transactions.transactional.uat.unico.app/api/public/v1`</mark>;
* Production: <mark style="color:blue;">`https://transactions.transactional.unico.app/api/public/v1`</mark>.
  {% endhint %}

{% hint style="warning" %}
**Important**

The "Credit Card Onboarding" can be performed by either requesting a selfie from the end user and completing the entire registration process, **or** by reusing the biometric captures from processes executed by other products of the Unico IDCloud platform:

* To reuse processes generated by other Unico IDCloud platform products, you must provide the reference process ID in the `additionalInfo.processID` field;
* The reference processes used must have been completed **no more than 1 hour** prior.
  {% endhint %}

## Validate credit card

> Endpoint to validate a credit card.

```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":{"/walletid/transaction":{"post":{"summary":"Validate credit card","description":"Endpoint to validate a credit card.","parameters":[{"name":"Authorization","in":"header","required":true,"description":"Valid access token. 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"],"properties":{"identity":{"type":"object","description":"User identity information.","required":["key","value"],"properties":{"key":{"type":"string","description":"Type of user identifier key."},"value":{"type":"string","description":"Value of the user identifier key."}}},"orderNumber":{"type":"string","description":"Number associated with the onboarding. This value will be used as an index in the portal and can serve 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 include: an HTTPS URL for web redirection or a Schema URL for redirection in native mobile apps."},"card":{"type":"object","description":"Card information 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. Ensure the correct name is provided to avoid encoding issues or invalid values that could cause approval problems, as this data is used in the user experience and communications."}}},"value":{"type":"number","format":"float","description":"Maximum secured value."},"additionalInfo":{"type":"object","description":"If you want to reuse biometric captures made in other products of the Unico IDCloud platform, send this object with the property `processID`.","required":["processID"],"properties":{"processID":{"type":"string","description":"Reference process ID from the IDCloud platform."}}}}}}}},"responses":{"200":{"description":"Transaction created successfully.","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 (only returned if `additionalInfo.processID` is not provided)."},"token":{"type":"string","description":"Signed token containing the necessary parameters to initialize the Unico IDPay web SDK (only returned if `additionalInfo.processID` is not provided)."}}}}}},"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" %}
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 %}

## Check validation status

> Endpoint to check the current status of a specific transaction.

```json
{"openapi":"3.0.0","info":{"title":"Wallet Transaction Status API","version":"1.0.0"},"servers":[{"url":"https://transactions.transactional.uat.unico.app/api/public/v1"}],"paths":{"/walletid/transactions/{transaction_id}":{"get":{"summary":"Check validation status","description":"Endpoint to check the current status of a specific transaction.","parameters":[{"name":"transaction_id","in":"path","required":true,"description":"ID of the transaction to be queried.","schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Valid access token. The value must be sent in the format `Bearer {token}`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Query successfully executed.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Current status of the transaction."},"hasIdentityChanged":{"type":"boolean","description":"Whether an identity swap occurred in the transaction (optional)."}}}}}},"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":"Transaction 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="info" %}
To view 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 your application's performance, 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.&#x20;
{% 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/credit-card-onboarding.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.