Platform Docs

Build Payment Solutions

With the Developer Pay API (US and Canada), you can build payment solutions using the Clover REST API.

Getting Information for the Pay Endpoint

GET /v2/merchant/{mId}/pay/key

This endpoint returns the key and prefix you'll need for the pay endpoint. Prepend the prefix to the credit card number, then use RSA/OAEP/SHA1 encryption on the resulting string using the provided modulus and exponent.

Permissions required: Payments Read

Parameters: No URL parameters

Request: No Request Data Needed.


  "pem" : String
  "prefix" : String
  "modulus" : String
  "exponent" : String
  "id" : String

Authorizing & Capturing a Payment

POST /v2/merchant/{mId}/pay

This endpoint authorizes and captures a credit card per the merchant configuration. An orderId for an existing order from the Clover API must be included in the payload sent to this endpoint. If this is the first time you're using the card with this specific merchant, you must encrypt the card data with the results from the GET /v2/merchant/{mId}/pay/key endpoint. Once you've made a payment with a card, you'll get a token that can be used for subsequent transactions in place of the cardEncrypted, first6, last4, cvv, expMonth, expYear, and zip parameters.


In order to use the Developer Pay API to process credit cards, you will need an OAuth-generated API token. Merchant-generated API tokens are not supported.

Permissions required: Payments Write, Process Credit Cards

Parameters: No URL parameters


Returns an object that includes a result status, the ID for the payment object, and a token you can use for subsequent transactions for this particular card and merchant.

  "orderId": "HCFFREA222N02", 
  "taxAmount": 9, 
  "zip": "94041", 
  "expMonth": 1, 
  "cvv": "111", 
  "amount": 100, 
  "currency": "usd", 
  "last4": "1111", 
  "expYear": 2015, 
  "first6": "411111", 
  "cardEncrypted": "X8UeKej+AEG1h0wD9Xw=="
  "authCode" : String
  "failureMessage" : String
  "token" : String
  "result" : (APPROVED|DECLINED)
  "paymentId" : String

Example payment flow

  1. To get the encryption information you'll need for the pay endpoint, send a GET request to /v2/merchant/{mId}/pay/key.
  2. Encrypt the card information:
    • Prepend the card number with the prefix from the GET /v2/merchant/{mId}/pay/key call.
    • Generate an RSA public key using the modulus and exponent provided by GET /v2/merchant/{mId}/pay/key.
    • Encrypt the card number and prefix from step 1 with the public key.
    • Base64 encode the resulting encrypted data into a string which you will send to Clover in the cardEncrypted field.


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

  1. To pay for the order, send a POST request to /v2/merchant/{mId}/pay. Pass the encrypted card data and order information to Clover in the request.

When the order is paid, the order and payment data are automatically synchronized between the Clover Server and the merchant's Clover devices.

Example Code

The following code is from the Java Example App.

public static PublicKey getPublicKey(final BigInteger modulus, final BigInteger exponent) {
    try {
      final KeyFactory factory = KeyFactory.getInstance("RSA");
      final PublicKey publicKey = factory.generatePublic(new RSAPublicKeySpec(modulus, exponent));
      return publicKey;
    } catch (GeneralSecurityException e) {
      throw new BaseException(e);
public static String encryptPAN(final String prefix, final String pan, PublicKey publicKey) {
   byte[] input = String.format("%s%s", prefix, pan).getBytes();
   try {
     Cipher cipher = Cipher.getInstance("RSA/None/OAEPWithSHA1AndMGF1Padding", "BC");
     cipher.init(Cipher.ENCRYPT_MODE, publicKey, RANDOM);
     byte[] cipherText = cipher.doFinal(input);
     return DatatypeConverter.printBase64Binary(cipherText);
   } catch (GeneralSecurityException ignore) {
     return null;


Customer transactions appear with URLs in their credit card statements. We highly recommend that you set a 13 characters limit on the site URL for your app. Any additional characters will not appear in statements.

To provide consistent customer experiences while keeping the site URL length in check, you can use URL shortening services.

Build Payment Solutions

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.