> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/v1/buyers/cards/associate

> Associa um cartão tokenizado a um comprador no gateway de pagamentos

Associa um token de cartão (gerado pelo frontend com o SDK do gateway) a um comprador existente no gateway. Após a associação, o ID do cartão é salvo localmente para uso em cobranças recorrentes.

**Fluxo PCI-compliant:**

1. O frontend tokeniza o cartão diretamente no gateway usando a `publishable_key`
2. O frontend envia o `token_id` + `buyer_id` para este endpoint
3. O backend associa o cartão ao comprador no gateway e salva o ID localmente

## Autenticação

Não requer autenticação.

## Corpo da Requisição

**buyer\_id** `string` *required*

ID do comprador no gateway (obtido em [Criar Comprador](https://scaleup-c34c4386.mintlify.site/api-reference/buyers/create.md) ou [Buscar Comprador](https://scaleup-c34c4386.mintlify.site/api-reference/buyers/lookup.md))

**token\_id** `string` *required*

ID do token do cartão gerado pelo frontend no fluxo de tokenização do gateway

## Resposta

**success** `boolean`

Indica se a associação foi bem-sucedida

**card** `object`

Dados do cartão associado

**Propriedades**

**id** `string`

ID do cartão no gateway

**card\_brand** `string`

Bandeira do cartão (ex: `visa`, `mastercard`)

**first4\_digits** `string`

Primeiros 4 dígitos do cartão

**last4\_digits** `string`

Últimos 4 dígitos do cartão

**expiration\_month** `string`

Mês de vencimento (dois dígitos)

**expiration\_year** `string`

Ano de vencimento (quatro dígitos)

**holder\_name** `string`

Nome do titular impresso no cartão

**is\_valid** `boolean`

Indica se o cartão é válido

## Exemplo

```bash cURL theme={null}
curl -X POST "https://api.chargefy.io/api/v1/buyers/cards/associate" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_id": "gw_buyer_abc123",
    "token_id": "tok_xxxxxxxxxxxxxxxxx"
  }'
```

```typescript SDK theme={null}
import { Chargefy } from '@chargefy/sdk';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

const result = await chargefy.buyers.associateCard({
  buyerId: 'gw_buyer_abc123',
  tokenId: 'tok_xxxxxxxxxxxxxxxxx',
});
```

## Resposta de Exemplo

```json theme={null}
{
  "success": true,
  "card": {
    "id": "card_xyz789abc",
    "card_brand": "visa",
    "first4_digits": "4111",
    "last4_digits": "1111",
    "expiration_month": "12",
    "expiration_year": "2028",
    "holder_name": "JOAO SILVA",
    "is_valid": true
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.