Making simple charges (SDK)

Complete the following steps to accept a simple payment using an Ecommerce SDK.

Creating a card token

Apps using an SDK must provide the card token Clover uses to process secure payments. See the FAQ for information about using gift cards with the API.

🚧

IMPORTANT

While your app can generate tokens, storing and processing non-tokenized card data on the server side may increase your PCI compliance burden. Clover recommends using the hosted iframe to collect card data on the client side instead. The following steps should only be used when client-side tokenization is not feasible or possible.

Encrypting card data

The card object in the create() method contains the details of the card being tokenized. To tokenize an encrypted card, use the encrypted_pan property.

{
    card={
        'encrypted_pan': '{encrypted_card_number}',
        'first6': '601136',
        'last4': '6668',
        'exp_month': '12',
        'exp_year': '2021',
        'cvv': '123',
        'brand': 'DISCOVER'
    }
}
  1. To get the encryption information required for encrypted_pan, send a GET request to /v2/merchant/{mId}/pay/key.
{
    "modulus": "{modulus}", // base-10
    "exponent": "{exponent}",
    "prefix": "{prefix}" 
}
  1. Encrypt the card information. Follow the encryption example code from the Java example app.
    • Prepend the prefix value to the card number.
    • Generate an RSA public key using the modulus and exponent values.
    • Using the public key, encrypt the combined prefix and card number.
    • Base64 encode the resulting encrypted data into a string. This string is the encrypted_pan value in the /v1/tokens request.

In response, an encrypted card number is generated. All encrypted_pan values are alphanumeric and end with ==.

📘

NOTE

The modulus returned by Clover is in base 10. Various libraries expect moduli in different bases.

Tokenizing encrypted card data

To create a token, call the create() method and pass in the minimum required card information:

  • encryted_pan
  • first6
  • last4
  • brand
  • exp_month
  • exp_year
  • cvv
from clover import Token

token = clover.Token.create(
    card={
        'encrypted_pan': '{encrypted_card_number}',
        'first6': '601136',
        'last4': '6668',
        'exp_month': '12',
        'exp_year': '2021',
        'cvv': '123',
        'brand': 'DISCOVER'
    }
)
require('dotenv').config();
const Clover = require("clover-ecomm-sdk");

let ACCESS_TOKEN = process.env.ACCESS_TOKEN;
let ENVIRONMENT = process.env.ENVIRONMENT;

const cloverInst = new Clover(ACCESS_TOKEN, {
  environment: ENVIRONMENT
});

let token = cloverInst.charges.create({
  card: {
       'encrypted_pan': '{encrypted_card_number}',
       'first6': '601136',
       'last4': '6668',
       'exp_month': '12',
       'exp_year': '2021',
       'cvv': '123',
       'brand': 'DISCOVER'
  },
  'apiKey': API_KEY
});

This returns a token object in JSON. The id value will be used in later steps to complete the payment.

{
  'id': 'clv_1TSTSpbfbN6Jh5CqCm3bMQne',
  'object': 'token',
  'card': {
    'exp_month': '12',
    'exp_year': '2021', 
    'last4': '6668', 
    'brand': 'DISCOVER'
  }
}

Clover provides several sandbox test cards that can be used when developing your app.

Creating a charge

Once you have a token, you can charge the customer's card for the required amount. To do so, call the associated create() method and pass in the minimum required order data:

  • amount
  • currency
  • source
from clover import Charge

charge = Charge.create(
    amount=1358,
    currency='usd',
    tax_rate_uuid='{tax_uuid}',
    source='clv_1TSTSpbfbN6Jh5CqCm3bMQne'
)
require('dotenv').config();
const Clover = require("clover-ecomm-sdk");

let ACCESS_TOKEN = process.env.ACCESS_TOKEN;
let API_KEY = process.env.API_KEY;
let ENVIRONMENT = process.env.ENVIRONMENT;

const cloverInst = new Clover(ACCESS_TOKEN, {
  environment: ENVIRONMENT
});

let charge = cloverInst.charges.create({
  amount: 1358,
  currency: 'usd',
  tax_rate_uuid: '{tax_uuid}',
  source: 'clv_1TSTSpbfbN6Jh5CqCm3bMQne'
});

In this example, tax is set using the tax_rate_uuid object. You can set tax values for your charge amount in two ways.

Tax object

Description

Tax as UUID (recommended)

To set the tax based on merchant tax information, use tax_rate_uuid. This is the recommended approach.

Taxes are set under Setup > Taxes & Fees on the Merchant Dashboard. You can retrieve this merchant tax information with /v3/merchants/{mId}/tax_rates.

Tax as amount

To set a flat fee, use tax_amount.

📘

NOTE

When adding taxes in your charge request, the amount must be the sum of the items and any tax or tip. For example, if the cost of the item is $10 and the tax is $1. the amount value must be 1100 ($11).

In response, a charge id is created. See the REST API Reference for complete information about the returned values.

{
  'id': 'CEDW57FP91ZB6',
  'amount': 1358, // (item cost + tax)
  'tax_amount': 135,
  'amount_refunded': 0,
  'currency': 'usd', 
  'created': 1580408081825,
  'captured': false,
  'ref_num': '015600501490',
  'auth_code": "OK0433',
  'outcome': {
    'network_status': 'approved_by_network',
    'type': 'authorized'
  },
  'paid': True,
  'refunded': False,
  'status': 'succeeded',
  'source': {
    'id': 'clv_1TSTSpbfbN6Jh5CqCm3bMQne',
    'brand': 'DISCOVER', 
    'cvc_check': 'pass',
    'exp_month': '12',
    'exp_year': '2021',
    'last4': '6668'
  }
}

Adding a tip to your charge

You can use the tip_amount (in cents) value to add a tip before paying for a charge.

from clover import Charge

charge = Charge.create(
    amount=1358,
    tip_amount=200,
    currency='usd',
    source='clv_1TSTSpbfbN6Jh5CqCm3bMQne'
)
require('dotenv').config();
const Clover = require("clover-ecomm-sdk");

let ACCESS_TOKEN = process.env.ACCESS_TOKEN;
let API_KEY = process.env.API_KEY;
let ENVIRONMENT = process.env.ENVIRONMENT;

const cloverInst = new Clover(ACCESS_TOKEN, {
  environment: ENVIRONMENT
});

let charge = cloverInst.charges.create({
  amount: 1358,
  tip_amount: 200,
  currency: 'usd',
  source: 'clv_1TSTSpbfbN6Jh5CqCm3bMQne'
});

Calculations with tips

Always submit the charge amount and tip separately. In the above Python example, for a subtotal of $13.58 and a tip of $2:

Subtotal

Tip

Correct

amount=1358

tip_amount=200

Incorrect

amount=1558

tip_amount=200

📘

NOTE

Tipping is available only for card-present transactions.


Did this page help you?