Use existing TransArmor tokens

North America—United States and Canada

TransArmor token overview Create a TransArmor token Use existing TransArmor tokens

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

Prerequisites

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

Steps

Generate a PAKMS key.
Send a POST request to the v1/tokens endpoint.
Expand the external_token object.
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

Field	Description	Require/Optional
`token_value`	Value of the TransArmor token.	Required
`exp_month`	Card expiration month in 2-digit format. Format: mm	Required
`exp_year`	Card expiration year in 2- or 4-digit format. Format: yy or yyyy	Required
`apikey`	Universally unique identifier (ID) of the API. The public API key is associated with the specific merchant and developer app.	Required
`name`	Cardholder's full name on the card.	Optional
`brand`	Card brand.	Optional
`first6`	First 6 numbers of the primary account number.	Optional
`last4`	Last 4 numbers of the primary account number.	Optional
`address_line1`	First line of the address. Can include the street address, PO box, or company name.	Optional
`address_line2`	Second line of the address. Can include the apartment, suite, unit, or building number.	Optional
`address_city`	City of the customer address. Can include district, suburb, town, or village.	Optional
`address_state`	State of the customer address. Can include county, province, or region.	Optional
`address_zip`	State of the customer address. Can include county, province, or region.	Optional
`address_country`	Billing address country, if provided.	Optional
`transactionId`	Initial 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.

Enter values in the following required parameters in the request:
1. amount
2. currency
3. source
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.

Enter values in the following required parameters in the request:
1. orderId
2. source
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**********"
    }
…
}

Updated 11 days ago