Cartões (Visa e Mastercard)

Visão Geral

Aceite pagamentos com cartão de crédito e débito através da API da Cost+ utilizando o método de pagamento credit-card.

{
  "transactions": [
    {
      "payment_method": "credit-card"
    }
  ]
}

Bandeiras de Cartão Suportadas

Bandeira	Tipo
Amex	Crédito
Mastercard	Crédito / Débito
Maestro	Débito
Visa	Crédito / Débito
V Pay	Débito

Opções de Configuração

Descritor Dinâmico

Utilize o campo dynamic_descriptor para definir um texto personalizado que aparece no extrato bancário ou do cartão do seu cliente.

{
  "transactions": [
    {
      "payment_method": "credit-card",
      "payment_method_details": {
        "dynamic_descriptor": "My Store Order 123"
      }
    }
  ]
}

Utilizar o Nome do Cliente como Nome do Titular do Cartão

Defina use_customer_name_as_cardholder_name como true para utilizar automaticamente o nome do cliente da encomenda como nome do titular do cartão.

{
  "transactions": [
    {
      "payment_method": "credit-card",
      "payment_method_details": {
        "use_customer_name_as_cardholder_name": true
      }
    }
  ]
}

Formulário Personalizado de Introdução de Cartão

Se quiser construir o seu próprio formulário de introdução de cartão em vez de utilizar a página de pagamento alojada, siga estes quatro passos.

Passo 1: Criar uma Encomenda com um Setup Token

Crie uma encomenda e inclua setup_token: true nos payment_method_details da transação. Isto indica à Cost+ para gerar um setup token que pode utilizar para tokenizar os dados do cartão de forma segura.

curl -X POST https://api.costplus.online/v1/orders \
  -u your-api-key: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 5000,
    "merchant_order_id": "order-001",
    "transactions": [
      {
        "payment_method": "credit-card",
        "payment_method_details": {
          "setup_token": true
        }
      }
    ],
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook"
  }'

A resposta incluirá um valor setup_token nos payment_method_details da transação:

{
  "id": "order-uuid",
  "transactions": [
    {
      "id": "txn-uuid",
      "payment_method": "credit-card",
      "payment_method_details": {
        "setup_token": "st_abc123..."
      }
    }
  ]
}

Passo 2: Tokenizar os Dados do Cartão

Envie o PAN do cartão, a data de validade e o setup token para o endpoint de tokens. Isto armazena o cartão de forma segura e devolve um vault_token.

curl -X POST https://api.costplus.online/v1/tokens/ \
  -H "Content-Type: application/json" \
  -d '{
    "pan": "4111111111111111",
    "expiry_date": "1228",
    "setup_token": "st_abc123..."
  }'

Resposta:

{
  "vault_token": "vt_xyz789..."
}

Passo 3: Autenticar a Transação

Submeta o vault_token e o cvc para o endpoint de autenticação. Se o 3D Secure for necessário, receberá um redirect_url para redirecionar o cliente para a página de autenticação do seu banco.

curl -X POST https://api.costplus.online/v1/orders/{order_id}/transactions/{transaction_id}/authenticate/ \
  -u your-api-key: \
  -H "Content-Type: application/json" \
  -d '{
    "vault_token": "vt_xyz789...",
    "cvc": "123"
  }'

Resposta:

{
  "redirect_url": "https://3ds.bank.example.com/auth?id=..."
}

Redirecione o cliente para o redirect_url para completar a autenticação 3D Secure. Após o cliente completar (ou cancelar) a autenticação, será redirecionado de volta para o seu return_url.

Passo 4: Consultar o Estado da Encomenda

Após o cliente regressar do 3D Secure, consulte a encomenda para verificar o estado final.

curl -X GET https://api.costplus.online/v1/orders/{order_id} \
  -u your-api-key:

O status da encomenda transitará para um dos seguintes:

Estado	Significado
`completed`	O pagamento foi bem-sucedido
`cancelled`	O cliente cancelou ou a autenticação falhou
`error`	Ocorreu um erro durante o processamento
`expired`	A encomenda expirou antes de ser concluída

Para fluxos de autorização e captura manual com pagamentos por cartão, consulte o guia de Autorização / Captura / Anulação.

On this page