Use existing TransArmor tokens

North America—United States and Canada

Use your existing TransArmor token with create a charge and pay for an order in the Clover Ecommerce network.

Prerequisites

  1. Set up a sandbox developer account.
  2. Create an app in the sandbox. See also Ecommerce app permissions.
  3. Existing TA token.

Steps

  1. Generate a PAKMS key.
  2. Send a POST request to the v1/tokens endpoint.
  3. Expand the external_token object.
  4. Enter information in the required fields.
    In the response, a multi-pay TransArmor token returns. This token is alphanumeric and begins with clv_. Example: clv_1ABCDefgHI23jKL4m5nOPqR

External token fields

FieldDescriptionRequire/Optional
token_valueValue of the TransArmor token.Required
exp_monthCard expiration month in 2-digit format.
Format: mm
Required
exp_yearCard expiration year in 2- or 4-digit format.
Format: yy or yyyy
Required
apikeyUniversally unique identifier (ID) of the API.
The public API key is associated with the specific merchant and developer app.
Required
nameCardholder's full name on the card.Optional
brandCard brand.Optional
first6First 6 numbers of the primary account number.Optional
last4Last 4 numbers of the primary account number.Optional
address_line1First line of the address. Can include the street address, PO box, or company name.Optional
address_line2Second line of the address. Can include the apartment, suite, unit, or building number.Optional
address_cityCity of the customer address. Can include district, suburb, town, or village.Optional
address_stateState of the customer address. Can include county, province, or region.Optional
address_zipState of the customer address. Can include county, province, or region.Optional
address_countryBilling address country, if provided.Optional
transactionIdInitial transaction identifier received from Rapid connect transaction response.Optional

Request example

curl --request POST \
     --url 'https://token-sandbox.dev.clover.com/v1/tokens' \
     --header 'apikey: xxx' 
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "external_token": {
    "transarmor_token_attribute": {
      "exp_month": "12",
      "exp_year": "2027"
    },
    "token_value": 1234567890
  }
}
'

Response example

{  
    "id": "clv_1ABCDefgHI23jKL4m5nOPqR",  
    "object": "token",  
    "": {  
        "last4": ""  
    }  
}

Use Create a charge with an existing TA token

Send a POST request to the v1/charges endpoint.

  1. Enter values in the following required parameters in the request:
    1. amount
    2. currency
    3. source
  2. Under the stored_credentials object, select SUBSEQUENT in sequence.
    In the response, a multi-pay TransArmor token returns. You can use this token for recurring and multi-pay transactions.

Request example

curl --request POST \
     --url 'https://scl-sandbox.dev.clover.com/v1/charges' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer ab86****-****-****-****-*****9867833' \
     --header 'Content-Type: application/json' \
     --header 'x-forwarded-for: {client_ip}' \
     --data '{
    "ecomind":"ecom"
    "amount": 122,
    "currency": "USD",
    "capture": false,
    "source": "clv_1ABCDefgHI23jKL4m5nOPqR",
    "stored_credentials": {
        "initiator": "MERCHANT",
        "sequence": "SUBSEQUENT",
        "is_scheduled": false
     }'

Response example

{
  "id": "ABDFEFG1HIJK2", 
  "amount": 122,
  "payment_method_details": "card",
  "amount_refunded": 0,
  "currency": "usd",
  "created": 123456789123,
  "captured": true,
  "ref_num": 987654321,
  "auth_code": 123456,
  "outcome": {
    "network_status": "approved_by_network",
    "type": "authorized"
  },
  "paid": true,
  "status": "succeeded",
  "source": {
    "id": "clv_1********************kgN",
    "brand": "DISCOVER",
    "exp_month": 12,
    "exp_year": 2025,
    "first6": 112233,
    "last4": 1111
  },
  "stored_credentials": {
        "initiator": "MERCHANT",
        "sequence": "SUBSEQUENT",
        "is_scheduled": false
     }'
  "ecomind": "ecom"
}

Use Pay for an order with an existing TA token

Send a POST request to v1/orders/{orderId}/pay endpoint.

  1. Enter values in the following required parameters in the request:
    1. orderId
    2. source
  2. Under the stored_credentials object, select SUBSEQUENT in sequence.
    In the response, a multi-pay TransArmor token returns. You can use this token for recurring and multi-pay transactions.

Request example

curl --location 'https://scl-dev1.dev.clover.com/v1/orders/3NHSD5ESJE0JE/pay' \
--header 'Authorization: Bearer XXX' \
--header 'X-Clover-Merchant-Id: A2J94WZSZW851' \
--header 'Content-Type: application/json' \
--data '{
    "source": "clv_1ABCDefgHI23jKL4m5nOPqR",
    "stored_credentials": {
        "initiator": "MERCHANT",
        "sequence": "FIRST",
        "is_scheduled": false
    }
}'

Response example

{
    "id": "3NHSD5ESJE0JE",
…
    "saved_credentials_on_file": {
        "tokenType": "TRANSARMOR",
        "value": "122754**********"
    }
…
}