# Escolher a adquirente

> O campo acquirer, as adquirentes habilitadas na conta, os limites de cada uma e o que fazer quando o valor passa do máximo.

Fonte: https://app.thronecorporate.com/docs/cartao/escolher

## O campo acquirer

Uma conta pode ter mais de uma adquirente de cartão habilitada. Nesse caso, cada site (source) escolhe a dela com o campo `acquirer` no `POST /elements/checkout`. Assim a mesma conta, com a mesma chave, vende pela Sterling num site, pela NovaCorp em outro, pela Eminence num terceiro, pela Apex num quarto e pela ShadowBank num quinto.

```bash
curl -X POST https://app.thronecorporate.com/api/v1/elements/checkout \
  -H "Authorization: Bearer $THRONE_PK:$THRONE_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amount_cents": 4990, "currency": "chf", "acquirer": "novacorp" }'
```

- **Sem o campo**, vale a adquirente padrão da conta, como sempre foi. Integrações que já estão no ar continuam iguais. A única exceção é o [roteamento por valor](#roteamento-por-valor), que vem desligado.
- Os valores são `sterling`, `imperium`, `novacorp`, `eminence`, `apex`, `shadowbank` e `vortex`, em minúsculas.
- Só vale uma adquirente **habilitada na sua conta**. Se pedir outra, a chamada volta `422 acquirer_not_enabled` com a lista das habilitadas e nada é criado.
- **Com o campo, o Throne nunca troca a adquirente que você pediu por outra.** Se ela não aceitar o valor ou estiver indisponível, a resposta é um erro, e você decide o que fazer.
- Valor fora da lista: `422 invalid_acquirer`.
- A resposta traz `acquirer` com a adquirente que ficou com a venda. A venda fica nela até o fim: pagamento, estorno e contestação. O `GET /transactions/{id}` também traz o `acquirer`.

## Adquirentes habilitadas e limites

As adquirentes habilitadas na sua conta aparecem no painel, em **Documentação da API**, e também na API:

```bash
curl "https://app.thronecorporate.com/api/v1/elements/acquirers?currency=chf" \
  -H "Authorization: Bearer $THRONE_PK:$THRONE_SK" \
  -H "Accept: application/json"
```

```json
{
  "data": [
    {
      "acquirer": "sterling",
      "name": "Sterling",
      "default": true,
      "available": true,
      "limits": { "currency": "CHF", "min_amount_cents": 80, "max_amount_cents": 500000 }
    },
    {
      "acquirer": "novacorp",
      "name": "NovaCorp",
      "default": false,
      "available": true,
      "limits": { "currency": "CHF", "min_amount_cents": 80, "max_amount_cents": 31890 }
    },
    {
      "acquirer": "eminence",
      "name": "Eminence",
      "default": false,
      "available": true,
      "limits": { "currency": "CHF", "min_amount_cents": 80, "max_amount_cents": 500000 }
    },
    {
      "acquirer": "apex",
      "name": "Apex",
      "default": false,
      "available": true,
      "limits": { "currency": "CHF", "min_amount_cents": 80, "max_amount_cents": 500000 }
    },
    {
      "acquirer": "shadowbank",
      "name": "ShadowBank",
      "default": false,
      "available": true,
      "limits": { "currency": "CHF", "min_amount_cents": 80, "max_amount_cents": 500000 }
    }
  ]
}
```

Os números acima são só um exemplo.

| Campo | O que é |
|---|---|
| `acquirer` | O valor para mandar no campo `acquirer` do checkout |
| `name` | O nome para mostrar |
| `default` | `true` na adquirente que vale quando o campo não é enviado |
| `available` | `false` quando a adquirente está em pausa ou indisponível no momento. Criar nela volta `503 temporarily_unavailable` |
| `limits` | Só com `?currency=`. Mínimo e máximo por venda **na moeda pedida**, pela cotação do momento. Vem nulo quando a cotação dessa moeda está indisponível agora |

Os limites são indicativos: a cotação muda ao longo do dia, e a criação confere o valor de novo na hora. Moeda fora da lista volta `422 currency_not_supported`. A chave precisa da permissão `transactions:write`, a mesma de criar o checkout. Lista vazia: a conta não tem cartão habilitado; fale com o suporte.

## Quando o valor passa do máximo

Cada adquirente tem um máximo por venda, que varia com a moeda e com a cotação do dia. Acima dele, nada é criado e a resposta é:

```json
{
  "error": "invalid_amount",
  "message": "Valor acima do máximo aceito nesta adquirente: CHF 318,90.",
  "max_amount_cents": 31890,
  "currency": "CHF",
  "alternatives": ["sterling"]
}
```

- `max_amount_cents` é o máximo na moeda que você mandou, pela cotação do momento.
- `alternatives` lista as outras adquirentes habilitadas na sua conta que aceitam esse valor. Lista vazia: nenhuma aceita.
- **Não repita o mesmo valor na mesma adquirente.** Crie com o `acquirer` de uma das `alternatives`, ou divida o pedido em vendas menores.

Abaixo do mínimo, a resposta é a mesma `422 invalid_amount`, com o mínimo na sua moeda no `message` e em `min_amount_cents`.

Em casos raros a adquirente recusa um valor acima do máximo que ela ainda não tinha informado. A resposta é a mesma `422 invalid_amount`, sem `max_amount_cents`: trate igual, com as `alternatives`.

## Roteamento por valor

Sem o campo `acquirer`, a venda vai para a adquirente padrão. Contas com o **roteamento por valor** ligado têm uma regra a mais: se o valor passa do máximo da padrão, o Throne cria a venda na próxima adquirente habilitada que aceita o valor.

- O roteamento vem desligado. Para ligar, fale com o suporte. Taxa e perfil de aprovação mudam entre adquirentes.
- A resposta traz em `acquirer` a adquirente que ficou com a venda. Guarde junto do `transaction_id`.
- Com o campo `acquirer`, o roteamento não vale: o Throne nunca troca a adquirente pedida.

## Adquirente em pausa ou sem capacidade

Uma adquirente pode ficar indisponível por alguns minutos: pausa de manutenção, instabilidade ou pico de criação. Nesse caso, a criação responde:

```json
{
  "error": "temporarily_unavailable",
  "message": "A adquirente novacorp está temporariamente indisponível. Tente em instantes ou use outra habilitada: sterling.",
  "retryable": true
}
```

com o header `Retry-After` em segundos. Nada foi criado. Espere o `Retry-After` e repita com uma `Idempotency-Key` nova, ou crie com o `acquirer` de outra adquirente habilitada. Uma adquirente em pausa ou indisponível aparece em `GET /elements/acquirers` com `available: false`.

## Webhook e consulta

O webhook e a consulta são iguais nas seis. Para saber em qual adquirente uma venda foi feita, use o `acquirer` da resposta de criação ou do `GET /transactions/{id}`.