# QI Tech — Banking-as-a-Service › Prepaid Card Management

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
17 página(s).

Índice:
- Authorization Request (/en/documentation/cards/autorizacao/)
- Simulate authorization (/en/documentation/cards/autorizacao/simular_autorizacao)
- Creating a physical card (/en/documentation/cards/create/gerar_cartao_fisico)
- Creating a virtual card (/en/documentation/cards/create/gerar_cartao_virtual)
- Introduction (/en/documentation/cards/introducao)
- Retrieve Authorization (/en/documentation/cards/search/buscar_autorizacao)
- List Authorizations (/en/documentation/cards/search/buscar_autorizacoes)
- Search card by key (/en/documentation/cards/search/buscar_cartao_by_key)
- Search PCI data (/en/documentation/cards/search/buscar_dados_pci)
- Track card delivery by key (/en/documentation/cards/search/buscar_entrega_by_key)
- Retrieve PCI Password (/en/documentation/cards/search/buscar_senha)
- List Cards (/en/documentation/cards/search/listar_cartoes)
- Activate physical card (/en/documentation/cards/status/ativar_cartao)
- Update status (/en/documentation/cards/status/update_status_cartao)
- Contactless Configuration (/en/documentation/cards/update/contactless_cartao)
- Update password (/en/documentation/cards/update/password_cartao)
- Update delivery address (/en/documentation/cards/update/update_delivery_address)

---

# Authorization Request

URL: /en/documentation/cards/autorizacao/

---

Once the program is set up, the cardholder has been added and has an active card, which can be used to make purchases at various points of sale around the world. Whenever a purchase is started, an `Authorization` is created to authorize it. An `Authorization Request` is forwarded to the integration partner, so that it can decide whether or not to approve this authorization based on the information contained within the request.

The `Authorization` entity contains the current state of the authorized and captured values and can assume the following status values:

| Status | Description |
|---|---|
| pending | Authorization request was authorized and no capture or reversal events were processed |
| unauthorized | Authorization request was not approved |
| completed | Authorization with at least one captured value (equal to, less than, or greater than the total authorized amount) |
| reversed | Authorization was voided in full or expired without capture |

Authorization details can be found at [Retrieve Authorization](https://docs.qitech.com.br/documentation/cards/search/buscar_autorizacao/).

The `Authorization Request` contains [Authentication Headers](https://docs.qitech.com.br/documentation/cards/autorizacao/autenticacao/) and has the following attributes:

### Authorization Request

ENDPOINT (client_url)/authorization_request
METHOD POST

Request Body

```json
{
	"authorization_key": "c91ce179-517c-48f9-9c28-18368457b67f",
	"authorization_request_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"card": {
		"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
		"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
		"type": "virtual",
		"card_name": "ecommerce sample",
		"printed_name": "Aurora Catarina",
		"status": "active",
		"brand": "visa",
		"bin": "123456",
		"last_four_digits": "5695"
	},
	"terminal_id": "123456",
	"terminal_country_code": "BRA",
	"terminal_type": "2",
	"terminal_pin_entry_capability": true,
	"terminal_magnetic_stripe_capability": true,
	"terminal_contactless_capability": false,
	"terminal_chip_capability": true,
	"merchant_acquirer_code": "250",
	"merchant_code": "123456",
	"merchant_name": "VASP LINHAS AEREAS",
	"merchant_street": "RUA CMDTE X, 127",
	"merchant_city": "SAO PAULO, SP",
	"merchant_region": "BRA",
	"merchant_postal_code": "04570-140",
	"merchant_mcc": "3036",
	"authorization_code": "473890",
	"nsu": "123456",
    "acquirer_reference_number": "12312423",
	"merchant_currency_code": "BRL",
	"merchant_amount": 10.59,
	"billing_currency_code": "BRL",
	"billing_amount": 10.59,
	"processing_datetime": "2023-01-10T13:45:52.000Z",
	"number_of_installments": 1,
	"authorization_request_type": "authorization",
	"pan_entry_mode": "chip",
	"pin_sent": true,
	"authorization": {Authorization Object}
}
```

#### Authorization Request

| Field | Type | Description |
|---|---| ---|
| `authorization_request_key` | string | Authorization request unique identifier |
| `authorization_key` | string | Authorization unique identifier |
| `card` | object |**[Object Card](#object-card)** |
| `terminal_id` | string | The terminal identifier sent by the acquirer in the authentication message |
| `terminal_country_code` | string | The country code of the terminal, sent in the authorization message according to ISO 3166-1 alpha-3 |
| `terminal_type` | string | The endpoint type as received in the authorization message |
| `terminal_pin_entry_capability` | boolean | Is there a possibility to enter the card password in the terminal? |
| `terminal_magnetic_stripe_capability` | boolean | Is the terminal capable of reading the magnetic stripe? |
| `terminal_contactless_capability` | boolean | Is the terminal capable of initiating contactless transactions? |
| `terminal_chip_capability` | boolean | Is the terminal capable of initiating transactions using the EMV chip? |
| `merchant_acquirer_code` | string | The acquirer's identifier as per the authorization message |
| `merchant_code` | string | The identifier of the merchant in the acquirer according to the authorization message |
| `merchant_name` | string | The name of the merchant according to the authorization message |
| `merchant_street` | string | Merchant's address street |
| `merchant_city` | string | Merchant's address city |
| `merchant_region` | string | Merchant's address region |
| `merchant_postal_code` | string | Merchant's address postal code |
| `merchant_mcc` | string | Merchant's category code - [Updated list can be found here](https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf ) |
| `authorization_code` | string | 6-digit authorization code |
| `nsu` | string | Unique sequential number that defines an authorization |
| `acquirer_reference_number` | string | Unique identifier of the authorization in the acquirer |
| `merchant_currency_code` | string | The currency used by the merchant - ISO 4217-alpha |
| `merchant_amount` | decimal | Authorization amount in the merchant's currency |
| `billing_currency_code` | string | The cardholder's billing currency - ISO 4217-alpha |
| `billing_amount` | decimal | Authorization amount in cardholder's billing currency |
| `processing_datetime` | timestamp utc | Authorization's processing time |
| `number_of_installations` | int | Number of installments |
| `authorization_request_type` | enum | Enumerator of **[Authorization Request Types](#authorization-types)** |
| `pan_entry_mode` | enum | **[PAN Input Modes](#pan-input-modes)** - Chip, Typed, Stripe, Fallback, Contactless |
| `pin_sent` | boolean | Was a PIN entered in the terminal? |
| `authorization` | object | Authorization object in [Retrieve Authorization](https://docs.qitech.com.br/documentation/cards/search/buscar_autorizacao/) - presented only when the type of the authorization request is incremental |

#### Card Object

| Field | Type | Description |
|---| ---| ---|
| card_key | string | Card unique identifier|
| account_key | string | Card linked account unique identifier |
| type | string | Card type |
| card_name | string | Card name |
| printed_name | string | Name printed on card |
| status | string | Current card status |
| brand | string | Card network name |
| bin | string | Card BIN |
| last_four_digits | string | Card's last four digits |

#### Authorization Request Types

| Enumerator | Description |
|---|---|
| `authorization` | Normal authorization request |
| `incremental_authorization` | Incremental authorization request |
| `partial_reversal_authorization` | Authorization to perform a partial reversal of a previous authorized `Authorization` |
| `reversal_authorization` | Authorization to fully reverse a previous `Authorization` |

#### PAN Input Modes

Enumerator | ISO 8583 | Description
---------- | -------- | -----------
unknown | 00 | PAN entry mode unknown.
typed | 01 | PAN entered manually (typed).
bar_code | 03 | PAN entered via barcode reader
ocr | 04 | PAN entered via OCR (Optical Character Recognition)
chip | 05 | PAN inserted by integrated circuit card (Chip)
track_1 | 06 | PAN inserted by Track 1 of the stripe card
contactless | 07 | PAN entered via Contactless EMV
fallback_typed | 79 | An attempt was made to use the card or stripe reader on the device and the card but it was not possible to process the transaction with that information (Possibly a problem with the device or the card), so the PAN was entered. In some cases, the acquirer is not approved to use the CHIP or the stripe and sends this code.
fallback_magnetic_stripe | 80 | An attempt was made to use the card reader on the device and the card but it was not possible to process the transaction with that information (Possibly a problem with the device or the card), so the magnetic stripe on the card was used.
ecommerce | 81 | E-commerce / non-face-to-face transaction
magnetic_stripe | 90 | Stripe transaction (Card does not have a chip or device does not have a reader/was not approved)

### Approve or deny response to an authorization request

The response to the `Authorization Request` must be always a HTTP Status 201 and the decision must be informed in the `authorization_request_response` attribute. If the decision is negative, a denial reason enumerator must be informed and the denial details can be provided.

ENDPOINT (client_url)/authorization_request
METHOD POST
HTTP STATUS 201

Response Body

```json
{
    "approve": false,
    "denial_reason": "fraud_suspicion",
    "denial_reason_details": "Customer tried to perform a transaction 10 times the average transactions"
}
```

 
#### Detail

| Field | Type | Description |
|---|---| ---|
| `authorization_request_response` *(required)* | enumerator | `authorized` if the authorization is approved or `unauthorized` if the authorization is denied |
| `denial_reason` | enum | **[Denial Reason Enumerator](#denial-reason-enumerator)** |
| `denial_reason_details` | string | Denial reason details | |

#### Denial Reason Enumerator
| Enumerator | Description |
|--- | --- |
| **fraud_suspicion** | Authorization request with suspicious behavior|
| **blocked_cardholder** | Cardholder blocked or with restrictions |

#### Negative answer

Any HTTP status other than 201 will be interpreted as the client's inability to process the authorization. The decision rule configured in the client program will then be applied for cases of unavailability.

Important: Authorizations that are denied by the default card validation rules are automatically responded to the card network (Visa) by QI without forwarding the authorization request to the integration partner.

## Incremental Authorization

An `Authorization` may receive more than one `Authorization Request`- the second and greater are called incremental authorizations. Each `Authorization Request` may or may not be authorized and the `Authorization` entity always represents the result of all authorized responses to `Authorization Requests`.

An incremental authorization can be identified by the `authorization_type` field with value *incremental_authorization*. Whenever the request is of this type, the related `Authorization` object will be sent together with the `Authorization Request` payload.

---

# Simulate authorization

URL: /en/documentation/cards/autorizacao/simular_autorizacao

### Request

ENDPOINT /mock/card/authorization
METHOD POST

Request Body

```json
{
  "card_key": "ff3c4484-7a52-457e-b989-d9dcb87dfcd6",
  "merchant_name": "Supermarket XYZ",
  "merchant_city": "São Paulo",
  "merchant_region": "BR",
  "merchant_postal_code": "01001000",
  "merchant_mcc": "5411",
  "amount": 150.75,
  "authorization_type": "purchase"
}
```

### Response

```json
{
  "is_approved": true,
  "response_code": "00",
  "limit_amount": null
}
```

### Request Body Object

In this table, a description of all the variables used in the above-detailed requests is available.

| Field                 | Type   | Description                                        | Max. Length  | Example              |
|-----------------------|--------|----------------------------------------------------|--------------|----------------------|
| **card_key**          | string | Card unique key (required)                         | 36           | "ff3c4484-7a52-457e-b989-d9dcb87dfcd6"    |
| **authorization_type**| string | Type of the authorization (required)               | **[Enumerators](#authorization-type-enumeradores)** |
| **merchant_name**     | string | Name of the merchant                               | 40           | "Supermarket XYZ"    |
| **merchant_city**     | string | City of the merchant                               | 40           | "São Paulo"          |
| **merchant_region**   | string | Country of the merchant                            | 2            | "BR"                 |
| **merchant_postal_code** | string | Postal code of merchant                         | 8            | "01001000"           |
| **merchant_mcc**      | string | Category code of the merchant                      | **[Enumerators](#merchant-mcc-enumeradores)** |
| **amount**            | number | Transaction amount                                 | -            | 150.75               |

### Merchant_mcc enumerators

| Enumerator | Description                                 |
|------------|--------------------------------------------|
| 5812       | Eating Places, Restaurants                 |
| 5499       | Miscellaneous Food Stores                  |
| 5814       | Fast Food Restaurants                      |
| 5411       | Grocery Stores, Supermarkets               |
| 4121       | Taxicabs and Limousines                    |
| 4111       | Local and Suburban Transit                 |
| 4215       | Courier Services, Air or Ground            |
| 5912       | Drug Stores and Pharmacies                 |
| 5815       | Digital Goods: Applications (Excludes Games)|
| 8999       | Professional Services (Not Elsewhere Classified)|
| 5462       | Bakeries                                   |
| 5541       | Service Stations (with or without Ancillary Services)|
| 7523       | Parking Lots, Parking Meters and Garages   |
| 5300       | Wholesale Clubs                            |
| 4899       | Cable, Satellite and Other Pay Television and Radio Services|
| 5311       | Department Stores                          |
| 5813       | Bars, Cocktail Lounges, Discotheques, Nightclubs and Taverns (Drinking Places)|
| 7372       | Computer Programming, Data Processing and Integrated Systems Design Services|
| 5099       | Durable Goods (Not Elsewhere Classified)   |
| 5943       | Stationery Stores, Office and School Supply Stores|
| 7299       | Miscellaneous Personal Services (Not Elsewhere Classified)|
| 5199       | Nondurable Goods (Not Elsewhere Classified)|
| 7230       | Beauty and Barber Shops                    |
| 5999       | Miscellaneous and Specialty Retail Stores  |
| 5651       | Family Clothing Stores                     |

### Authorization_type enumerators

| Enumerator  | Description                |
|-------------|----------------------------|
| purchase    | Purchase                   |
| reversal    | Reversal                   |
| withdrawal  | Withdrawal                 |

---

# Creating a physical card

URL: /en/documentation/cards/create/gerar_cartao_fisico

## Request

ENDPOINT /prepaid/card
METHOD POST

Request Body

```json
{
    "account_key": "5294ed8d-08fc-4397-b15f-6d9aa07b0041",
    "program_key": "7d405c31-ec9a-46c1-8ac8-54bab209bf41",
    "type": "plastic",
    "card_name": "ecommerce",
    "printed_name": "Aurora Catarina",
    "contactless_enabled": true,    
    "delivery_address": {
        "address": "Rua Cel. Domingos Diniz",
        "neighborhood": "Centro",
        "zip_code": "35797000",
        "city": "Presidente Juscelino",
        "state": "MG",
        "complement": "Quadra 08 Lote 259",
        "reference": "Supermercado Presidente",
        "address_type": "residential"
    }
}
```

:::info Information
The address used for sending the physical card will be the same one provided when opening the payment account at QI Tech. 
:::

### Body params

| Field                   | Type    | Description                                                                                     | Characters                                 |
|-------------------------|---------|-------------------------------------------------------------------------------------------------|--------------------------------------------|
| `account_key` *         | string  | Account identification key on QI Tech payment.                                                  | uuid                                       |
| `program_key` *         | string  | Program identification key to issue a card.                                                     | uuid                                       |
| `type` *                | string  | Type of card to be issued (PLASTIC).                                                            | **[Enumerators](#Enumerators-card_type)** |
| `card_name` *           | string  | Card alias, how this card will be identified.                                                   | 15                                         |
| `printed_name` *        | string  | Name to be printed on the card (numbers and special characters will not be allowed).            | 26                                         |
| `contactless_enabled` * | boolean | Enable or disable the use of contactless on the card                                            | -                                          |
| `delivery_address`   | Object | Card delivery address.                                                                              | **[Object Address](#address)** |

### Enumerators card_type

| Enumerator | Translate     | 
|------------|---------------|
| plastic    | Physical Card | 
| virtual    | Virtual Card  |

### Address

| Field         | Type   | Description                              | Characters |
|---------------|--------|------------------------------------------|------------|
| address*      | string | Card delivery address                    | 100        |
| neighborhood* | string | Neighborhood of the delivery address     | 100        |
| zip_code*     | string | ZIP code of the delivery address         | 8          |
| city*         | string | City of the delivery address             | 100        |
| state*        | string | State of the delivery address            | 2          |
| number        | number | Street number of the delivery address    |            |
| complement    | string | Complement of the delivery address       | 100        |
| reference     | string | Reference point of the delivery address   | 100        |
| address_type* | string | Type of delivery                         | **[Enumerators](#address-type-enumerators)** |

:::caution Attention!
The `number` field is optional. Addresses without a street number can be submitted without this field.
:::

### Enumeradores address_type

| Enumerator | Translation            | 
|------------|------------------------|
| residential| Residential address    |  
| commercial | Commercial address     | 
| other      | Other address          | 

## Response

STATUS 201

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
	"created_at": "2023-06-20T19:28:16Z",
    "status":"created"
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "The type of person is invalid for this program, please try another.",
  "translation": "Invalid Person",
  "code": "CARD000007"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000005| 404          | It was not possible to fetch the Program for the program_key \{program_key\}.|
| CARD000006| 404          | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000007| 400          | The type of person is invalid for this program, please try another.|
| CARD000008| 400          | The Card Holder with the status \{status\} is invalid for the operation.|
| CARD000009| 400          | We're sorry, but the card could not be generated. Please try again later.|
| CARD000010| 404          | It was not possible to fetch the Person for the person_key \{owner_person_key\}.|
| CARD000033| 403          | Create plastic card is not allowed for program_key \{program_key\}.|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card",
    "event_datetime": "2023-07-24T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
        "program_key": "bf74df61-557a-45cb-914f-41e127a6e18c",
        "status": "created",
        "type": "plastic"
    }
}
```

---

# Creating a virtual card

URL: /en/documentation/cards/create/gerar_cartao_virtual

## Request

ENDPOINT /prepaid/card
METHOD POST

Request Body

```json
{
    "account_key": "5294ed8d-08fc-4397-b15f-6d9aa07b0041",
    "program_key":"7d405c31-ec9a-46c1-8ac8-54bab209bf41",
    "type": "virtual",
    "card_name": "ecommerce",
    "printed_name": "Aurora Catarina",
    "cvv_rotation_interval_hours": 72
}
```

  ### Body params

| Campo                           | Tipo   | Descrição                                                                                      | Caracteres                                |
|---------------------------------|--------|------------------------------------------------------------------------------------------------|-------------------------------------------|
| `account_key` *                 | string | QI Tech Payment Account Identification Key                                       | uuid                                      |
| `program_key` *                 | string | Program identification key to issue a card.                                      | uuid                                      |
| `type` *                        | string | Type of card to be issued (VIRTUAL).                                                        | **[Enumerators](#enumerators-card_type)** |
| `card_name` *                   | string | Card alias, how this card will be identified.                                           | 15                                      |
| `printed_name` *                | string | Name to be printed on the card (numbers and special characters will not be allowed). | 26                                      |
| `cvv_rotation_interval_hours` * | int    | Interval in hours to update the CVV number.                                                | Number                                    |

### Enumerators card_type

| Enumerator | Translate     | 
|------------|---------------|
| plastic    | Physical Card | 
| virtual    | Virtual Card  |

## Response

STATUS 201

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
	"created_at": "2023-02-20T19:28:16Z",
    "status":"created"
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "The type of person is invalid for this program, please try another.",
  "translation": "Invalid Person",
  "code": "CARD000007"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000005| 404          | It was not possible to fetch the Program for the program_key \{program_key\}.|
| CARD000006| 404          | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000007| 400          | The type of person is invalid for this program, please try another.|
| CARD000008| 400          | The Card Holder with the status \{status\} is invalid for the operation.|
| CARD000009| 400          | We're sorry, but the card could not be generated. Please try again later.|
| CARD000010| 404          | It was not possible to fetch the Person for the person_key \{owner_person_key\}.|
| CARD000032| 403          | Create virtual card is not allowed for program_key \{program_key\}.|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card",
    "event_datetime": "2023-07-24T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
        "program_key": "bf74df61-557a-45cb-914f-41e127a6e18c",
        "status": "created",
        "type": "virtual"
    }
}
```

---

# Introduction

URL: /en/documentation/cards/introducao

QI Tech's prepaid card issuance APIs allow their partners' customers to request and issue either physical or virtual prepaid cards.

At QI Tech, we offer our partners the opportunity to become sub-issuers. Through our APIs, partners can provide their own customers with the ability to issue both physical and virtual prepaid cards, thus providing a complete solution for banking services.

To better understand our system, we will make a brief introduction of how the prepaid card ecosystem works, but we remind you that, as with other APIs, the service must be released together with our team and the **[calls are authenticated](/documentation/primeiros_passos/teste_de_autenticacao)**.

### Prepaid Card

The prepaid card is a card linked to a payment account within QI Tech.

All transactions executed through this card will debit the existing balance in the payment account.

If the account does not have a balance, the transaction will be denied.

### Prepaid Account

QI Tech is an authorized financial institution to operate with prepaid payment accounts by the Central Bank of Brazil. A prepaid card is always linked to a prepaid payment account.

Therefore, to create a prepaid card, whether physical or virtual, it is always necessary to open a payment account. Check **[here](/documentation/contas/abertura_de_conta/abertura_de_conta_pf)** our account opening API.

### Program

In order for a partner to issue a prepaid card, they must have an associated and configured program in their integration with QI.

The program is nothing more than the settings and rules necessary for the issuance of the card in accordance with the VISA flag.

Here are some important information about the program:

* **Program type** - Refers to the type of use of the card. In this documentation, it is the Prepaid modality.
* **Brand** - We use the VISA brand for the cards issued by the program.
* **Card layout** - Refers to the design that will be printed on the physical card and that will be presented in the graphical interface of the virtual card. 

:::caution Attention
For configuration of a new program in an integration, the sales team and the QI Tech deployment team must be activated.
:::

### Virtual Card

The QI Tech card API offers the functionality of generating virtual cards, which can be used in online transactions. This solution provides security and convenience to cardholders.

When using a virtual card, cardholders do not need to provide the details of the physical card during online transactions. Instead, they can generate a unique virtual card, with a number and specific information for that particular transaction. This helps reduce the risk of fraud and increases confidence in online transactions.

### Physical Card

The QI Tech Card API offers the option of creating physical cards, giving cardholders the possibility of having a plastic card for use in in-person transactions.

When requesting a physical card, the holder will receive a personalized plastic card.

The availability of the physical card offers cardholders a traditional and widely accepted way of making payments, ensuring convenience and practicality in their face-to-face transactions. In addition, the physical card can also have additional features, such as contactless payment technology to speed up transactions.

QI Tech's prepaid card API enables cardholders to choose between using virtual cards for online transactions and using physical cards for face-to-face transactions, according to their individual needs and preferences.

---

# Retrieve Authorization

URL: /en/documentation/cards/search/buscar_autorizacao

## Request

ENDPOINT /prepaid/card/(card_key)/authorization/(authorization_key)
METHOD GET

## Response

STATUS 200

Response Body

```json
{
    "authorization_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
    "merchant_currency_code": "BRL",
    "original_merchant_amount": 25.32,
    "billing_currency_code": "BRL",
    "original_billing_amount": 25.32,
    "merchant_amount": 25.32,
    "iof_amount": 0,
    "billing_amount": 25.32,
    "processing_datetime": "2023-07-24T12:00:00.000Z",
    "captured_amount": 25.32,
    "authorization_status": "completed",
    "card": {
        "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
        "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
        "type": "virtual",
        "card_name": "ecommerce sample",
        "printed_name": "Aurora Catarina",
        "status": "active",
        "brand": "visa",
        "bin": "123456",
        "last_four_digits": "5695"
    },
    "balance_transactions": [
        {
            "balance_transaction_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
            "balance_transaction_type": "debit",
            "account_transaction_key": "595e08f0-da4e-40f7-8db4-f9a25c820000",
            "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
            "merchant_currency_code": "BRL",
            "merchant_amount": 25.32,
            "billing_currency_code": "BRL",
            "billing_amount": 25.32,
            "processing_datetime": "2023-01-10T13:45:52.000Z",
            "balance_transaction_status": "transacted",
            "transacted_amount": 25.32,
        }
    ],
    "authorization_requests": [
        {
            "authorization_request_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
            "authorization_code": "473890",
            "nsu": "123456",
            "acquirer_reference_number": "12312423",
            "merchant_currency_code": "BRL",
            "merchant_amount": 25.32,
            "billing_currency_code": "BRL",
            "billing_amount": 25.32,
            "processing_datetime": "2023-01-10T13:45:52.000Z",
            "number_of_installments": 1,
            "authorization_request_type": "authorization",
            "authorization_request_response": "authorized"
        }
    ],
    "authorization_events": [
        {
            "merchant_currency_code": "BRL",
            "merchant_amount": 25.32,
            "billing_currency_code": "BRL",
            "billing_amount": 25.32,
            "processing_datetime": "2023-07-24T12:00:00.000Z",
            "authorization_event_type": "authorization"
        }
    ]
}
```

### Authorization Object

| Field | Type | Description |
|---|---| ---|
| authorization_key | string | Authorization unique identifier |
| merchant_currency_code | string | The currency used by the merchant - ISO 4217-alpha |
| original_merchant_amount | decimal | Original amount of the transaction in the merchant currency |
| billing_currency_code | string | The cardholder's billing currency - ISO 4217-alpha |
| original_billing_amount | decimal | Original amount in cardholder's billing currency |
| merchant_amount | decimal | Sum of the current authorized amount in the merchant's currency, from all authorization requests |
| iof_amount | decimal | Sum of the IOF amount for international authorizations on cardholder's billing currency |
| billing_amount | decimal | Sum of the current authorized amount in the cardholder's billing currency, from all authorization requests |
| processing_datetime | datetime UTC | Time of the authorization creation |
| captured_amount | decimal | Sum of the total value captured |
| authorization_status | enumerator | Enumerator of **[Authorization Status](#authorization-status)** |
| card | object |**[Object Card](#object-card)** |
| balance_transactions | list of objects |**[Balance Transaction Object](#balance-transaction-object)** |
| authorization_requests | list of objects |**[Authorization Request Object](#authorization-request-object)** |
| authorization_events | list of objects | **[Authorization Event Object](#authorization-event-object)** |

### Card Object

| Field | Type | Description |
|---| ---| ---|
| card_key | string | Card unique identifier|
| account_key | string | Card linked account unique identifier |
| type | string | Card type |
| card_name | string | Card name |
| printed_name | string | Name printed on card |
| status | string | Current card status |
| brand | string | Card network name |
| bin | string | Card BIN |
| last_four_digits | string | Card's last four digits |

### Balance Transaction Object

The `Balance Transaction` object represents any movement in the cardholder's account balance. They can be *debit* transactions (reducing the account balance), or they can be *credit* transactions (increasing the account balance).

| Field | Type | Description |
|---| ---| ---|
| balance_transaction_key | string | Balance transaction unique identifier |
| balance_transaction_type | enumerator | Possible values (*credit*, *debit*) |
| account_key | string | Card linked account unique identifier |
| merchant_currency_code | string | The currency used by the merchant - ISO 4217-alpha |
| merchant_amount | decimal | Amount of the transaction in the merchant currency |
| billing_currency_code | string | The cardholder's billing currency - ISO 4217-alpha |
| billing_amount | decimal | Amount of the transaction in the cardholder's billing currency |
| processing_datetime | datetime | Transaction's processing and creation datetime |
| balance_transaction_status | enumerator | The status of the balance transaction: pending (`pending_transaction_execution`), partially transacted (`partially_transacted`) or transacted (`transacted`) |
| transacted_amount | decimal | Total amount that was successfully debited/credited from cardholder's account balance |

### Authorization Request Object

Detailed in [Authorization Request](https://docs.qitech.com.br/documentation/cards/autorizacao/)

### Authorization Event Object

The `Authorization Event` object represents the events that occur with an Authorization. See [Use Cases](https://docs.qitech.com.br/documentation/manual_pre_pago/casos_uso/).

| Field | Type | Description |
|---| ---| ---|
| merchant_currency_code | string | The currency used by the merchant - ISO 4217-alpha |
| merchant_amount | decimal | Amount of the event in the merchant currency |
| billing_currency_code | string | The cardholder's billing currency - ISO 4217-alpha |
| billing_amount | decimal | mount of the event in the cardholder's billing currency |
| processing_datetime | datetime | Event's processing datetime |
| authorization_event_type | enumerator | **[Authorization Event Types](#authorization-event-types)** |

### Authorization Status

| Status | Description |
|---|---|
| pending | Authorization request was authorized and no capture or reversal events were processed |
| unauthorized | Authorization request was not approved |
| completed | Authorization with at least one captured value (equal to, less than, or greater than the total authorized amount) |
| reversed | Authorization was voided in full or expired without capture |

### Authorization Event Types

| Type | Description |
|---|---|
| authorization | An authorization request was processed |
| incremental_authorization | An incremental authorization request was processed |
| authorization_reversal | An authorization was fully reversed |
| partial_authorization_reversal | An authorization was partially reversed |
| authorization_expiration | The uncaptured amount of an authorization was expired and reversed to the cardholder's account balance |
| capture | An amount was captured for the authorization |
| refund | The captured amount was fully refunded for the authorization |
| partial_refund | The captured amount was partially refunded for the authorization |

---

# List Authorizations

URL: /en/documentation/cards/search/buscar_autorizacoes

## Request

ENDPOINT /prepaid/card/(card_key)/authorizations
METHOD GET
PARAMETERS from_date, to_date, size, page

## QUERY PARAMS

| Field | Type | Description |
|-----------------|---------|---------------------- ------------------------------------|
| `size` | int | Number of records to be returned. Default 10. |
| `page` | int | Page on which the search will be carried out. Default 1. |
| `from_date` | date | Desired period start date |
| `to_date` | date | Desired period end date |

## Response

STATUS 200

Response Body

```json
{
     "pagination": {
         "current_page": 1,
         "rows_per_page": 10,
         "next_page": 2
     },
     "date": [
         {
             "authorization_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
             "merchant_currency_code": "BRL",
             "original_merchant_amount": 25.31,
             "billing_currency_code": "BRL",
             "original_billing_amount": 25.31,
             "merchant_amount": 25.31,
             "iof_amount": 0,
             "billing_amount": 25.31,
             "processing_datetime": "2023-07-24T12:00:00.000Z",
             "captured_amount": 25.31,
             "authorization_status": "completed"
         },
         {
             "authorization_key": "9a7b2586-7070-4543-99eb-989d9165814e",
             "merchant_currency_code": "BRL",
             "original_merchant_amount": 65,
             "billing_currency_code": "BRL",
             "original_billing_amount": 65,
             "merchant_amount": 65,
             "iof_amount": 0,
             "billing_amount": 65,
             "processing_datetime": "2023-07-24T13:00:00.000Z",
             "captured_amount": 65,
             "authorization_status": "completed"
         }
     ]
```

---

# Search card by key

URL: /en/documentation/cards/search/buscar_cartao_by_key

## Request

ENDPOINT /prepaid/card/ CARD_KEY
METHOD GET

### Path params

| Field         | Type   | Description                        | Characters  |
|---------------|--------|------------------------------------|-------------|   
| `CARD_KEY` *  | string | Card identification key            | uuid        |
 

## Response

STATUS 200

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",    
    "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
    "program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
    "type": "virtual",
    "card_name": "ecommerce",
    "printed_name": "Aurora Catarina",
    "cvv_rotation_interval_hours": 72,
    "created_at": "2023-02-20T19:28:16Z",
    "updated_at": "2023-02-22T19:28:16Z",
    "status": "active",
    "brand": "visa",
    "last_four_digits": "5695",
    "status_events": [
        {
            "status": "created",
            "created_at": "2023-02-20T19:28:16Z"
        },
        {
            "status": "active",
            "created_at": "2023-02-20T19:35:10Z"
        }
    ]
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Not Found Card",
  "code": "CARD000011"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000016| 400          | We're sorry, but the card could not be fetch. Please try again later.|

---

# Search PCI data

URL: /en/documentation/cards/search/buscar_dados_pci

## Request

ENDPOINT /prepaid/card/ CARD_KEY /pci
METHOD GET

### Path params

| Field         | Type   | Description                        | Characters |
|---------------|--------|------------------------------------|------------|   
| `CARD_KEY` *  | string | Card identification key.           | uuid       |

## Response

STATUS 200

Response Body

```json
{
    "printed_name": "Aurora Catarina",
    "valid_until": "2023-02-20T10:04:12Z",
    "expiration_date": "03/24",
    "card_number": "4539347744299311",
    "cvv": "713"
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Not Found Card",
  "code": "CARD000011"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400          | It was not possible to fetch PCI for the card_key \{card_key\}.|

---

# Track card delivery by key

URL: /en/documentation/cards/search/buscar_entrega_by_key

## Request

ENDPOINT /card/ CARD_KEY /tracking
METHOD GET

### Path params

| Field        | Type   | Description                         | Characters |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | Card identification key | uuid       |

## Response

STATUS 200

Response Body

```json
{
  "card_key": "92b4e2bd-4a6f-4c56-859e-17c729e1f0c8",
  "tracking_code": "4F68A72B902317",
  "status": "posted",
  "recipient": "João Silva",
  "address": {
    "zip_code": "1234567",
    "street": "Rua das Flores",
    "number": 123,
    "complement": "Bloco A",
    "neighborhood": "Centro",
    "city": "Cidade Exemplo",
    "state": "SP"
  },
  "event": [
    {
      "created_at": "2024-02-27T08:30:00Z",
      "old_status": "pending",
      "new_status": "posted",
      "description": "Pedido recebido e postado",
      "place": "SAO PAULO"
    }
  ]
}
```

### Enumerator DeliveryStatus

| Enumerator         |
|--------------------|
| pending            |
| posted             |
| prepared           |
| in_transfer        |
| in_delivery_unit   |
| on_route           |
| attempt_failed     |
| awaiting_withdrawal|
| returning          |
| delivered          |
| returned           |
| canceled           |
| failed             |
| resend             |

### Errors

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Tracking for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Not Found",
  "code": "TRACK000011"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| TRACK000011| 404          | It was not possible to fetch the Tracking for the card_key \{card_key\}.|
| TRACK000016| 400          | We're sorry, but the tracking could not be fetch. Please try again later.|

---

# Retrieve PCI Password

URL: /en/documentation/cards/search/buscar_senha

## Request

ENDPOINT /prepaid/card/ CARD_KEY /pci/password
METHOD GET

### Path params

| Campo        | Tipo   | Descrição                 | Caracteres |
|--------------|--------|---------------------------|------------|   
| `CARD_KEY` * | string | Card identification key.  | uuid       |

## Response

STATUS 200

Response Body

```json
{
    "pin": "1234"
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "It was not possible to fetch PCI for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Fetch PCI failed",
  "code": "CARD000012"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400          | It was not possible to fetch PCI for the card_key \{card_key\}.|

---

# List Cards

URL: /en/documentation/cards/search/listar_cartoes

## Request

ENDPOINT /prepaid/card
METHOD GET
PARÂMETROS account_key, size, page

## QUERY PARAMS

| Field            | Type   | Description                                              | Characters  |
|------------------|--------|----------------------------------------------------------|-------------| 
| `account_key` *  | string | QI Tech Payment Account Identification Key.              | uuid        |
| `size`           | int    | Number of records that will be returned. Default 10.     | -           |
| `page`           | int    | Page that will be searched. Default 0.                   | -           |

## Response

STATUS 200

Response Body

```json
{
    "pagination": {
        "current_page": 1,
        "rows_per_page": 0,
        "next_page": 2
    },
    "data": [
        {
            "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",        
            "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
            "program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
            "type": "virtual",
            "card_name": "ecommerce",
            "printed_name": "Aurora Catarina",
            "cvv_rotation_interval_hours": 72,
            "created_at": "2023-02-20T19:28:16Z",
            "updated_at": "2023-02-22T19:28:16Z",
            "status": "active",
            "brand": "visa"
        },
        {
            "card_key": "ee084f00-d72e-4263-87fb-3a3c11a418c6",
            "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
            "program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
            "type": "virtual",
            "card_name": "uber",
            "printed_name": "Aurora Catarina",
            "cvv_rotation_interval_hours": 72,
            "created_at": "2023-02-10T11:28:16Z",
            "updated_at": "2023-02-15T11:28:16Z",
            "status": "canceled",
            "brand": "visa"
        }
    ]
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Account for the account_key 94f982c0-164c-45e3-8a0e-69f54ad7b155.",
  "translation": "Not Found Account",
  "code": "CARD000006"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| CARD000006| 404          | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000021| 400          | Account key can not be null when search for cards.|
| CARD000022| 400          | Invalid integer value for page or size querystring parameters.|

---

# Activate physical card

URL: /en/documentation/cards/status/ativar_cartao

All physical cards need to be activated using an activation code that is sent along with the physical card to the holder.

When receiving the card by mail, the card holder must inform the QI partner so that the partner can activate the card through this endpoint.

:::caution Attention
For security reasons, there is no possibility of consulting the activation code via API on the part of the partner.

This code is sent exclusively to the cardholder at the time of posting the physical card.
:::

## Request

ENDPOINT /prepaid/card/ CARD_KEY /activate
METHOD PATCH

### Path params
| Field        | Type   | Description              | Characters |
|--------------|--------|--------------------------|------------|   
| `CARD_KEY` * | string | Card identification key. | uuid       |

Request Body

```json
{
    "code": "253615"
}
```

  ### Body params
| Field      | Type   | Description                    | Characters |
|------------|--------|--------------------------------|------------|
| `code`  *  | string | Activation code of the card.   | 6          |

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Acceptable",
  "description": "Invalid activation code [1254].",
  "translation": "Unable to activate card",
  "code": "CARD000020"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000017| 406          | The activation operation is not valid for the current card status [\{card_status\}].|
| CARD000018| 400          | We're sorry, but the card could not be activate. Please try again later.|
| CARD000020| 406          | Invalid activation code [\{code\}].|
| CARD000023| 406          | The card type is invalid for this operation. Only plastic cards are allowed.|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card",
    "event_datetime": "2023-07-25T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "type": "plastic",
        "status": "active",
        "old_status": "embossing"
    }
}
```

---

# Update status

URL: /en/documentation/cards/status/update_status_cartao

## Request

ENDPOINT /prepaid/card/ CARD_KEY
METHOD PATCH

### Path params
| Field        | Type   | Description              | Characters |
|--------------|--------|--------------------------|------------|   
| `CARD_KEY` * | string | Card identification key. | uuid       |

Request Body

```json
{
    "status": "blocked"
}
```

  ### Body params

| Campo       | Tipo   | Descrição    | Caracteres                                  |
|-------------|--------|--------------|---------------------------------------------|
| `status`  * | string | Card Status. | **[Enumerators](#enumerators-card_status)** |

### Enumerators card_status
| Enumerators | Translation       | Type            |
|-------------|-------------------|-----------------|
| created     | Requested created | Initial         |
| building    | Under construction| Initial         |
| active      | Ready to trade    | Active          |
| embossing   | In production     | Temporary block |
| blocked     | Blocked           | Temporary block |
| warning     | With suspicion    | Temporary block |
| pending     | Pending           | Temporary block |
| lost        | Lost              | Terminated      |
| robbed      | Robbed            | Terminated      |
| fraud       | Fraud             | Terminated      |
| canceled    | Canceled          | Terminated      |
| theft       | Theft             | Terminated      |

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Acceptable",
  "description": "The operation is not valid for the current status of the card [canceled]",
  "translation": "Unable to transition",
  "code": "CARD000014"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000013| 406          | Unable to transition from \{old_status\} to \{new_status\}.|
| CARD000014| 406          | The operation is not valid for the current status of the card [\{card_status\}].|
| CARD000015| 400          | We're sorry, but the card could not be update. Please try again later|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card",
    "event_datetime": "2023-07-25T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "type": "virtual",
        "status": "active",
        "old_status": "created"
    }
}
```

---

# Contactless Configuration

URL: /en/documentation/cards/update/contactless_cartao

Enable or disable the contactless payment functionality for in-person use.

To enable or disable the contactless payment feature of the card, the card status must be of type **Active** or **Temporary block**. (For information about the status types, refer to [here](../../cards/status/update_status_cartao#enumerators-card_status))

## Request

ENDPOINT /prepaid/card/ CARD_KEY /contactless
METHOD PATCH

### Path params
| Field        | Type   | Description                | Characters |
|--------------|--------|----------------------------|------------|   
| `CARD_KEY` * | string | Card identification key.   | uuid       |

Request Body

```json
{
    "contactless_enabled": false
}
```

### Body params

| Field                     | Type    | Description                             | Characters |
|---------------------------|---------|-----------------------------------------|------------|
| `contactless_enabled`  *  | Boolean | Indicates whether it is enabled or not. | true/false |

## Response

STATUS SUCCESS 200

### Erros
STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "We're sorry, but the card could not be update contactless. Please try again later.",
  "translation": "Unexpected error update contactless card",
  "code": "CARD000026"
}
```

| Code      | Status code  | Description                      |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406          | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000026| 400          | We're sorry, but the card could not be update contactless. Please try again later.|
| CARD000025| 406          | The status \{status\} is invalid for the operation.|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card.updated.contactless

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card.updated.contactless",
    "event_datetime": "2023-07-25T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "contactless_enabled": true
    }
}
```

---

# Update password

URL: /en/documentation/cards/update/password_cartao

Every physical card has a password to authorize transactions, and it can be updated if necessary.

To update the card's password, the card status must be of type **Active** or **Temporary block**. (For information about status types, refer to [here](../../cards/status/update_status_cartao#enumerators-card_status))

:::caution Caution
For security reasons, be careful when updating a password, as it can impact card authorization.

Create rules to enhance password authorization security, such as avoiding using birthdates or repeated numbers (e.g., 3333).
:::

## Request

ENDPOINT /prepaid/card/ CARD_KEY /password
METHOD PATCH

### Path params
| Field        | Type   | Description                | Characters |
|--------------|--------|----------------------------|------------|   
| `CARD_KEY` * | string | Card identification key.   | uuid       |

Request Body

```json
{
    "pin": "2143"
}
```

  ### Body params

| Field     | Type   | Description                               | Characters |
|-----------|--------|-------------------------------------------|------------|
| `pin`  *  | string | Card password to authorize a transaction. | 4          |

## Response

STATUS SUCCESS 200

### Erros
STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "We're sorry, but the card could not be update password. Please try again later.",
  "translation": "Unexpected error update password card",
  "code": "CARD000024"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406          | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000024| 400          | We're sorry, but the card could not be update password. Please try again later.|
| CARD000025| 406          | The status \{status\} is invalid for the operation.|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card.updated.password

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card.updated.password",
    "event_datetime": "2023-07-25T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1"
    }
}
```

---

# Update delivery address

URL: /en/documentation/cards/update/update_delivery_address

The delivery address update serves to correct the address in case any inconsistency is found or the delivery fails three times.

## Request

ENDPOINT /account/ ACCOUNT_KEY /card/ CARD_KEY /address
METHOD POST

### Path parameters

| Field                   | Type   | Description                                                  | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Unique account identification key, in uuid v4 format        | 36         |
| `card_key`              | uuidv4 | Unique card identification key, in uuid v4 format           | 36         |

Request Body

```json
{
    "postal_code": "5425020",
    "street": "Rua Gilberto Sabino",
    "number": 215,
    "complement": "4 andar",
    "neighborhood": "Pinheiros",
    "city": "So Paulo",
    "state": "SP",
    "reference": "Terminal Pinheiros",
    "address_type": "commercial",
    "notes": ["obs1", "obs2"],
    "phones": [
        {"country_code": "55", "area_code": "19", "number": "983151110"},
        {"country_code": "55", "area_code": "16", "number": "992334318"},
    ],
}
```

### Request Body

### Address object

| Field                     | Type   | Description                                        | Characters |
|---------------------------|--------|----------------------------------------------------|------------|
| `street` *                | string | Street                                             | 100        |
| `number`                  | string | Number                                             | 10         |
| `neighborhood` *          | string | Neighborhood                                       | 100        |
| `postal_code` *           | string | Postal code                                        | 8          |
| `city` *                  | string | City                                               | 100        |
| `complement`              | string | Complement                                         | 100        |
| `reference`               | string | Reference point                                    | 100        |
| `notes`                   | string array | Notes related to the address               | 100        |
| `phones`                  | object array | Contact phones | **[Phone object](#phone-object)**  |
| `state` *                 | string | State (UF)       | **[State enumerators](#state-enumerators)** |
| `address_type` *          | string | Address type  | **[Address_type enumerators](#address_type-enumerators)** |

:::caution Attention!
The `number` field is optional. Addresses without a street number can be submitted without this field.
:::

:::caution Attention!
Up to two contact phones and four notes can be sent. If there are no contact phones and/or notes, these fields (`phones` and `notes`) should not be sent.
:::

### Phone object

| Field                           | Type   | Description                                      | Characters |
|---------------------------------|--------|--------------------------------------------------|------------|
| `international_dial_code` *     | string | IDD code (International Direct Dialing)         | 2          |
| `area_code` *                   | string | DDD code (Direct Distance Dialing)              | 2          |
| `number` *                      | string | Complement                                       | 9          |

### Address_type enumerators

| Enumerator         | Description              |
|--------------------|--------------------------|
| residential        | residential address      |
| commercial         | commercial address       |
| other              | other types of address   |

### State enumerators

| Enumerator         | Description           |
|--------------------|-----------------------|
| AC                 | Acre                  |
| AL                 | Alagoas               |
| AM                 | Amazonas              |
| AP                 | Amapá                 |
| BA                 | Bahia                 |
| CE                 | Ceará                 |
| DF                 | Distrito federal      |
| ES                 | Espírito Santo        |
| GO                 | Goiás                 |
| MA                 | Maranhão              |
| MG                 | Minas Gerais          |
| MS                 | Mato Grosso do Sul    |
| MT                 | Mato Grosso           |
| PA                 | Pará                  |
| PB                 | Paraíba               |
| PE                 | Pernambuco            |
| PI                 | Piauí                 |
| PR                 | Paraná                |
| RJ                 | Rio de Janeiro        |
| RN                 | Rio Grande do Norte   |
| RO                 | Rondônia              |
| RR                 | Roraima               |
| RS                 | Rio Grande do Sul     |
| SC                 | Santa Catarina        |
| SE                 | Sergipe               |
| SP                 | São Paulo             |
| TO                 | Tocantins             |
| EX                 | Exception             |

## Response

STATUS 200

Response Body

```json
{
  "card_key": "1e3183f0-1bac-4e59-81e8-2d89db224040",
  "tracking_code": "FD89B071241022",
  "address": {
    "city": "So Paulo",
    "notes": [
      "obs1",
      "obs2"
    ],
    "state": "SP",
    "number": 215,
    "phones": [
      {
        "number": "983151110",
        "area_code": "19",
        "country_code": "55"
      },
      {
        "number": "992334318",
        "area_code": "16",
        "country_code": "55"
      }
    ],
    "street": "Rua Gilberto Sabino",
    "reference": "Terminal Pinheiros",
    "complement": "4 andar",
    "postal_code": "5425020",
    "address_type": "commercial",
    "neighborhood": "Pinheiros"
  }
}

```

### Response Body Params

| Field                   | Type   | Description                                                                                     | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------------------|------------|
| `card_key` *            | uuidv4 | Unique card identification key, in uuid v4 format                                              | 36         |
| `tracking_code` *       | string | Card delivery tracking code                                                                     | 14         |
| `address`               | object | Object of type `address`, similar to what is sent in the request | **[Address object](#address-object)**  |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| HTTP Code<br/>`status` | QI Code<br/>`code` | Title<br/>`title`                                 | Description (eng)<br/>`description`                                                                                       | Description (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 403                      | QIT000005            | Permission Validator Error               | Selected agent and person_key are different | Agente selecionado e person_key são diferentes |
| 400                      | TRACK000004          | Bad Request                 | Invalid status to change delivery address. | Status inválido para mudar o endereço de entrega. |
| 500                      | TRACK000007          | Internal Server Error      | Failed to update delivery address at delivery service provider. Please, try again later!   | Falha ao atualizar endereço de entrega junto à provedora de serviços de delivery. Por favor, tente novamente mais tarde! |
| 404                      | TRACK000012          | Not Found                                 | Tracking not found for the given 'card_key'. | Rastreio não encontrado para a 'card_key' fornecida. |