Carte (Visa e Mastercard)

Panoramica

Accetta pagamenti con carte di credito e debito tramite l'API Cost+ utilizzando il metodo di pagamento credit-card.

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

Circuiti di Carte Supportati

Circuito	Tipo
Amex	Credito
Mastercard	Credito / Debito
Maestro	Debito
Visa	Credito / Debito
V Pay	Debito

Opzioni di Configurazione

Descrittore Dinamico

Usa il campo dynamic_descriptor per impostare un testo personalizzato che appare sull'estratto conto bancario o della carta del cliente.

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

Usare il Nome del Cliente come Nome del Titolare della Carta

Imposta use_customer_name_as_cardholder_name a true per utilizzare automaticamente il nome del cliente dall'ordine come nome del titolare della carta.

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

Modulo di Inserimento Carta Personalizzato

Se vuoi creare il tuo modulo di inserimento carta invece di utilizzare la pagina di pagamento ospitata, segui questi quattro passaggi.

Passaggio 1: Creare un Ordine con un Token di Configurazione

Crea un ordine e includi setup_token: true nei payment_method_details della transazione. Questo indica a Cost+ di generare un token di configurazione che puoi usare per tokenizzare in modo sicuro i dati della carta.

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"
  }'

La risposta includerà un valore setup_token nei payment_method_details della transazione:

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

Passaggio 2: Tokenizzare i Dati della Carta

Invia il PAN della carta, la data di scadenza e il token di configurazione all'endpoint dei token. Questo archivia la carta in modo sicuro nel vault e restituisce un 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..."
  }'

Risposta:

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

Passaggio 3: Autenticare la Transazione

Invia il vault_token e il cvc all'endpoint di autenticazione. Se il 3D Secure è richiesto, riceverai un redirect_url per reindirizzare il cliente alla pagina di autenticazione della sua banca.

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"
  }'

Risposta:

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

Reindirizza il cliente al redirect_url per completare l'autenticazione 3D Secure. Dopo che il cliente completa (o annulla) l'autenticazione, verrà reindirizzato al tuo return_url.

Passaggio 4: Verificare lo Stato dell'Ordine

Dopo che il cliente ritorna dal 3D Secure, interroga l'ordine per verificare lo stato finale.

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

Lo status dell'ordine passerà a uno dei seguenti:

Stato	Significato
`completed`	Pagamento riuscito
`cancelled`	Il cliente ha annullato o l'autenticazione è fallita
`error`	Si è verificato un errore durante l'elaborazione
`expired`	L'ordine è scaduto prima del completamento

Per i flussi di autorizzazione e cattura manuale con pagamenti con carta, consulta la guida Autorizzazione / Cattura / Annullamento.

On this page