Escolher a adquirente

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.

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, 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:

curl "https://app.thronecorporate.com/api/v1/elements/acquirers?currency=chf" \
  -H "Authorization: Bearer $THRONE_PK:$THRONE_SK" \
  -H "Accept: application/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.

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 é:

{
  "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:

{
  "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}.