Cards (Visa & Mastercard)

Overview

Accept credit and debit card payments through the Cost+ API using the credit-card payment method.

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

Supported Card Brands

Brand	Type
Amex	Credit
Mastercard	Credit / Debit
Maestro	Debit
Visa	Credit / Debit
V Pay	Debit

Configuration Options

Dynamic Descriptor

Use the dynamic_descriptor field to set a custom statement text that appears on your customer's bank or card statement.

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

Use Customer Name as Cardholder Name

Set use_customer_name_as_cardholder_name to true to automatically use the customer's name from the order as the cardholder name.

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

Custom Card Entry Form

If you want to build your own card entry form instead of using the hosted payment page, follow these four steps.

Step 1: Create an Order with a Setup Token

Create an order and include setup_token: true in the transaction's payment_method_details. This tells Cost+ to generate a setup token you can use to securely tokenize card details.

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

The response will include a setup_token value in the transaction's payment_method_details:

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

Step 2: Tokenize Card Details

Send the card PAN, expiry date, and the setup token to the token endpoint. This securely vaults the card and returns a 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..."
  }'

Response:

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

Step 3: Authenticate the Transaction

Submit the vault_token and cvc to the authenticate endpoint. If 3D Secure is required, you will receive a redirect_url to redirect the customer to their bank's authentication page.

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

Response:

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

Redirect the customer to redirect_url to complete 3D Secure authentication. After the customer completes (or cancels) authentication, they will be redirected back to your return_url.

Step 4: Poll Order Status

After the customer returns from 3D Secure, poll the order to check the final status.

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

The order status will transition to one of:

Status	Meaning
`completed`	Payment was successful
`cancelled`	Customer cancelled or authentication failed
`error`	An error occurred during processing
`expired`	The order expired before completion

On this page