---
updatedAt: 2026-04-24T20:47:13.000Z
agentTools:
  projectIndex: https://docs.clover.com/dev/llms.txt
---

# Create Clover token from an external token

**Description:** Creates a Clover token from an external multi-pay token such as TransArmor<sup>®</sup>.
 **Tutorial:** [Use existing TransArmor tokens](https://docs.clover.com/dev/docs/use-existing-transarmor-tokens).
 **Next steps:** Use this Clover token with endpoints like [create a charge](https://docs.clover.com/reference/createcharge) or [pay for an order](https://docs.clover.com/reference/postordersidpay).

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "TransArmor Tokenization API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "description": "Sandbox token server",
      "url": "https://token-sandbox.dev.clover.com"
    }
  ],
  "paths": {
    "/v1/tokens": {
      "post": {
        "tags": [
          "TOKENS"
        ],
        "operationId": "CreateToken",
        "summary": "Create Clover token from an external token",
        "x-clover-handler": "com.clover.tokenization.handler.CreateTokenHandler",
        "x-clover-is-public": true,
        "description": "**Description:** Creates a Clover token from an external multi-pay token such as TransArmor<sup>®</sup>.\n **Tutorial:** [Use existing TransArmor tokens](https://docs.clover.com/dev/docs/use-existing-transarmor-tokens).\n **Next steps:** Use this Clover token with endpoints like [create a charge](https://docs.clover.com/reference/createcharge) or [pay for an order](https://docs.clover.com/reference/postordersidpay).",
        "parameters": [
          {
            "in": "header",
            "name": "apikey",
            "description": "Public Ecommerce API key associated with a specific merchant and developer app. Use [Retrieve an Ecommerce API key or PAKMS key](https://docs.clover.com/dev/reference/getapikey) to generate this key.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true
          },
          {
            "in": "header",
            "name": "User-Agent",
            "schema": {
              "type": "string"
            },
            "required": true,
            "description": "Identifies the application, operating system, vendor, and/or version of the requesting user agent. Format: `<application>/<version>`"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "encoding": {
                "expand": {
                  "explode": true,
                  "style": "deepObject"
                },
                "items": {
                  "explode": true,
                  "style": "deepObject"
                },
                "metadata": {
                  "explode": true,
                  "style": "deepObject"
                },
                "shipping": {
                  "explode": true,
                  "style": "deepObject"
                }
              },
              "schema": {
                "properties": {
                  "external_token": {
                    "required": [
                      "token_value",
                      "token_type",
                      "transarmor_token_attribute"
                    ],
                    "description": "External token details, including metadata.",
                    "type": "object",
                    "properties": {
                      "token_value": {
                        "type": "string",
                        "description": "Value of the multi-pay token."
                      },
                      "token_type": {
                        "type": "string",
                        "description": "Type of the multi-pay token such as TransArmor.",
                        "enum": [
                          "TRANSARMOR"
                        ]
                      },
                      "transarmor_token_attribute": {
                        "type": "object",
                        "required": [
                          "exp_month",
                          "exp_year"
                        ],
                        "properties": {
                          "exp_month": {
                            "type": "string",
                            "description": "Card expiration month in 2-digit format.\n Format: mm"
                          },
                          "exp_year": {
                            "type": "string",
                            "description": "Card expiration year in 2- or 4-digit format.\n Format: Format: yy or yyyy"
                          },
                          "name": {
                            "type": "string",
                            "description": "Cardholder's full name on the card."
                          },
                          "brand": {
                            "type": "string",
                            "description": "Card brand.",
                            "enum": [
                              "VISA",
                              "MC",
                              "AMEX",
                              "DISCOVER",
                              "DINERS_CLUB",
                              "JCB"
                            ]
                          },
                          "first6": {
                            "type": "string",
                            "description": "First 6 numbers of the primary account number."
                          },
                          "last4": {
                            "type": "string",
                            "description": "Last 4 numbers of the primary account number."
                          },
                          "address_line1": {
                            "type": "string",
                            "description": "First line of the address. Can include the street address, PO box, or company name."
                          },
                          "address_line2": {
                            "description": "Second line of the address. Can include the apartment, suite, unit, or building number.",
                            "type": "string"
                          },
                          "address_city": {
                            "description": "City of the customer address. Can include district, suburb, town, or village.",
                            "type": "string"
                          },
                          "address_state": {
                            "description": "State of the customer address. Can include county, province, or region.",
                            "type": "string"
                          },
                          "address_zip": {
                            "description": "Postal or ZIP code of the customer's address.",
                            "type": "string"
                          },
                          "address_country": {
                            "description": "Billing address country, if provided.",
                            "type": "string"
                          },
                          "transactionId": {
                            "description": "Initial transaction identifier received from Rapid Connect transaction response.",
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Clover token generated using an external token.",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "id": {
                      "description": "Unique identification.",
                      "maxLength": 128,
                      "type": "string"
                    },
                    "token": {
                      "description": "Public source token provided by Clover.",
                      "maxLength": 128,
                      "type": "string"
                    },
                    "card": {
                      "description": "Card details, including metadata of the tokenized card.",
                      "properties": {
                        "number": {
                          "description": "Card number.",
                          "type": "string"
                        },
                        "encrypted_pan": {
                          "description": "Encrypted card primary account number (PAN) provided by TransArmor®.",
                          "type": "string"
                        },
                        "exp_month": {
                          "description": "Card expiration month in 2-digit format.\n Format: mm",
                          "type": "string"
                        },
                        "exp_year": {
                          "description": "Card expiration year in 2- or 4- digit.\n Format: yy or yyyy",
                          "type": "string"
                        },
                        "cvv": {
                          "description": "Card verification value.",
                          "type": "string"
                        },
                        "last4": {
                          "description": "Last 4 numbers of the primary account number.",
                          "type": "string"
                        },
                        "first6": {
                          "description": "First 6 numbers of the primary account number.",
                          "type": "string"
                        },
                        "country": {
                          "description": "2-character country code.",
                          "type": "string"
                        },
                        "brand": {
                          "description": "Card brand.",
                          "type": "string",
                          "enum": [
                            "VISA",
                            "MC",
                            "AMEX",
                            "DISCOVER",
                            "DINERS_CLUB",
                            "JCB"
                          ]
                        },
                        "id": {
                          "description": "Unique identifier.",
                          "type": "string"
                        },
                        "object": {
                          "description": "Object type. Objects with the same type have the same value.",
                          "type": "string"
                        },
                        "name": {
                          "description": "Cardholder's full name.",
                          "type": "string"
                        },
                        "address_line1": {
                          "description": "First line of the address. Can include the street address, PO box, or company name.",
                          "type": "string"
                        },
                        "address_line2": {
                          "description": "Second line of the address. Can include the apartment, suite, unit, or building number.",
                          "type": "string"
                        },
                        "address_city": {
                          "description": "City of the customer address. Can include district, suburb, town, or village.",
                          "type": "string"
                        },
                        "address_state": {
                          "description": "State of the customer address. Can include county, province, or region.",
                          "type": "string"
                        },
                        "address_zip": {
                          "description": "Postal or ZIP code of the customer's address.",
                          "type": "string"
                        },
                        "address_country": {
                          "description": "Billing address country, if provided.",
                          "type": "string"
                        },
                        "cvc_check": {
                          "description": "Results of the card verification code (CVC) check when a card payment is submitted to a card network for authorization. The card issuer checks the CVC against the information on file for the cardholder.",
                          "type": "string",
                          "enum": [
                            "pass",
                            "fail",
                            "unavailable",
                            "unchecked"
                          ]
                        }
                      }
                    },
                    "client_ip": {
                      "description": "Internet protocol (IP) address of the client generating the token.",
                      "maxLength": 45,
                      "type": "string"
                    },
                    "created": {
                      "description": "Time the token object was created.",
                      "format": "unix-time",
                      "type": "integer"
                    },
                    "livemode": {
                      "description": "Indicates whether the token object is live in production.\n Values: \n True - Token object is in production. \n False - Token object is in sandbox.",
                      "type": "boolean"
                    },
                    "type": {
                      "description": "Token type.",
                      "type": "string"
                    },
                    "used": {
                      "description": "Indicates whether the token is already used. Note that tokens can be used only once.",
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "description": "An error response from the API.",
                  "properties": {
                    "type": {
                      "description": "Error type.",
                      "enum": [
                        "api_connection_error",
                        "api_error",
                        "authentication_error",
                        "card_error",
                        "idempotency_error",
                        "invalid_request_error",
                        "rate_limit_error",
                        "validation_error"
                      ]
                    },
                    "code": {
                      "description": "Error codes. Additional information about the error that users can use to identify the issue.",
                      "enum": [
                        "amount_too_large",
                        "amount_too_small",
                        "api_key_expired",
                        "card_declined",
                        "charge_already_captured",
                        "charge_already_refunded",
                        "charge_disputed",
                        "charge_exceeds_source_limit",
                        "charge_expired_for_capture",
                        "country_unsupported",
                        "email_invalid",
                        "expired_card",
                        "incorrect_address",
                        "incorrect_cvc",
                        "incorrect_number",
                        "incorrect_zip",
                        "invalid_card_type",
                        "invalid_charge_amount",
                        "invalid_cvc",
                        "invalid_expiry_month",
                        "invalid_expiry_year",
                        "invalid_number",
                        "missing",
                        "order_creation_failed",
                        "order_required_settings",
                        "order_status_invalid",
                        "parameter_invalid_empty",
                        "parameter_invalid_integer",
                        "parameter_invalid_string_blank",
                        "parameter_invalid_string_empty",
                        "parameter_missing",
                        "parameter_unknown",
                        "postal_code_invalid",
                        "processing_error",
                        "rate_limit",
                        "resource_missing",
                        "token_already_used",
                        "invalid_request"
                      ]
                    },
                    "message": {
                      "description": "Detailed information about the error code.",
                      "type": "string"
                    },
                    "decline_code": {
                      "description": "Displays when a card issuer declined the transaction. This includes the reason for the decline if specified by the card issuer.",
                      "type": "string"
                    },
                    "charge": {
                      "description": "Displays for card-related errors. Unique identifier (ID) of the failed charge.",
                      "type": "string"
                    },
                    "doc_url": {
                      "description": "Link (URL) for more information about the reported error code.",
                      "type": "string"
                    },
                    "param": {
                      "description": "Displays for card parameter errors. The error message can inform users entering card information of a specific problem with their entry.",
                      "type": "string"
                    }
                  }
                }
              }
            },
            "description": "Bad request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "description": "An error response from the API.",
                  "properties": {
                    "type": {
                      "description": "Error type.",
                      "enum": [
                        "api_connection_error",
                        "api_error",
                        "authentication_error",
                        "card_error",
                        "idempotency_error",
                        "invalid_request_error",
                        "rate_limit_error",
                        "validation_error"
                      ]
                    },
                    "code": {
                      "description": "Error codes. Additional information about the error that users can use to identify the issue.",
                      "enum": [
                        "amount_too_large",
                        "amount_too_small",
                        "api_key_expired",
                        "card_declined",
                        "charge_already_captured",
                        "charge_already_refunded",
                        "charge_disputed",
                        "charge_exceeds_source_limit",
                        "charge_expired_for_capture",
                        "country_unsupported",
                        "email_invalid",
                        "expired_card",
                        "incorrect_address",
                        "incorrect_cvc",
                        "incorrect_number",
                        "incorrect_zip",
                        "invalid_card_type",
                        "invalid_charge_amount",
                        "invalid_cvc",
                        "invalid_expiry_month",
                        "invalid_expiry_year",
                        "invalid_number",
                        "missing",
                        "order_creation_failed",
                        "order_required_settings",
                        "order_status_invalid",
                        "parameter_invalid_empty",
                        "parameter_invalid_integer",
                        "parameter_invalid_string_blank",
                        "parameter_invalid_string_empty",
                        "parameter_missing",
                        "parameter_unknown",
                        "postal_code_invalid",
                        "processing_error",
                        "rate_limit",
                        "resource_missing",
                        "token_already_used",
                        "invalid_request"
                      ]
                    },
                    "message": {
                      "description": "Detailed information about the error code.",
                      "type": "string"
                    },
                    "decline_code": {
                      "description": "Displays when a card issuer declines the transaction. This includes the reason for the decline if specified by the card issuer.",
                      "type": "string"
                    },
                    "charge": {
                      "description": "Displays for card-related errors. Unique identifier (ID) of the failed charge.",
                      "type": "string"
                    },
                    "doc_url": {
                      "description": "Link (URL) for more information about the reported error code.",
                      "type": "string"
                    },
                    "param": {
                      "description": "Displays for card parameter errors. The error message can inform users entering card information of a specific problem with their entry.",
                      "type": "string"
                    }
                  }
                }
              }
            },
            "description": "Authorization information is missing or invalid."
          },
          "5XX": {
            "content": {
              "application/json": {
                "schema": {
                  "description": "An error response from the API.",
                  "properties": {
                    "type": {
                      "description": "Error type.",
                      "enum": [
                        "api_connection_error",
                        "api_error",
                        "authentication_error",
                        "card_error",
                        "idempotency_error",
                        "invalid_request_error",
                        "rate_limit_error",
                        "validation_error"
                      ]
                    },
                    "code": {
                      "description": "Error codes. Additional information about the error that users can use to identify the issue.",
                      "enum": [
                        "amount_too_large",
                        "amount_too_small",
                        "api_key_expired",
                        "card_declined",
                        "charge_already_captured",
                        "charge_already_refunded",
                        "charge_disputed",
                        "charge_exceeds_source_limit",
                        "charge_expired_for_capture",
                        "country_unsupported",
                        "email_invalid",
                        "expired_card",
                        "incorrect_address",
                        "incorrect_cvc",
                        "incorrect_number",
                        "incorrect_zip",
                        "invalid_card_type",
                        "invalid_charge_amount",
                        "invalid_cvc",
                        "invalid_expiry_month",
                        "invalid_expiry_year",
                        "invalid_number",
                        "missing",
                        "order_creation_failed",
                        "order_required_settings",
                        "order_status_invalid",
                        "parameter_invalid_empty",
                        "parameter_invalid_integer",
                        "parameter_invalid_string_blank",
                        "parameter_invalid_string_empty",
                        "parameter_missing",
                        "parameter_unknown",
                        "postal_code_invalid",
                        "processing_error",
                        "rate_limit",
                        "resource_missing",
                        "token_already_used",
                        "invalid_request"
                      ]
                    },
                    "message": {
                      "description": "Detailed information about the error code.",
                      "type": "string"
                    },
                    "decline_code": {
                      "description": "Displays when a card issuer declines the transaction. This includes the reason for the decline if specified by the card issuer.",
                      "type": "string"
                    },
                    "charge": {
                      "description": "Displays for card-related errors. Unique identifier (ID) of the failed charge.",
                      "type": "string"
                    },
                    "doc_url": {
                      "description": "Link (URL) for more information about the reported error code.",
                      "type": "string"
                    },
                    "param": {
                      "description": "Displays for card parameter errors. The error message can inform users entering card information of a specific problem with their entry.",
                      "type": "string"
                    }
                  }
                }
              }
            },
            "description": "Unexpected error."
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  }
}
```