Enroll Card

Enrolls a Firstoken permanent token in the card network's tokenization program.

Endpoint

POST /v1/tokens/enroll

Important: This endpoint requires a previously created Firstoken permanent token. The token must contain valid card information before enrollment.

Environments

Production:

https://api.firstoken.co/v1/tokens/enroll

Sandbox (Testing):

https://api.firstoken-staging.co/v1/tokens/enroll

Authentication

All requests require the x-api-key header with your API key:

x-api-key: <YOUR_API_KEY>

Creating an API Key

To use the Network Token Enrollment API, you need to create an API key in the Firstoken Console:

1. Access the Console: Log into your Firstoken Console

2. Navigate to Keys: Go to the Keys module in the left sidebar

3. Create New Key: Click "Create Access Key"

4. Configure Key:

   • Enter a name for your key (e.g., "Network Token API Key")

   • Add an optional description

   • Important: Select the "Payment Request" permission under the Request section

5. IP Whitelist: Add your server's IP addresses to the whitelist for security

6. Create Key: Click "Create Access Key" to generate your key

Service Activation

After creating your API key with Payment Request permissions, contact our team to activate the Network Token service for your API key. The service activation is required before you can start using the enrollment endpoint.

Note: Make sure your API key has the correct permissions and your IP addresses are whitelisted before requesting service activation.

Request Parameters

Parameter	Type	Required	Description
transaction_info.type	string	Yes	Must be "enroll_card"
card.number	string	Yes	Firstoken token reference (use detokenize syntax)
card.expiration_date	string	Yes	Card expiration date (use detokenize syntax)
bill_to.address_1	string	Yes	Primary billing address
bill_to.address_2	string	No	Secondary billing address
bill_to.city	string	Yes	Billing city
bill_to.state	string	Yes	Billing state/province
bill_to.postal_code	string	Yes	Billing postal code
bill_to.country	string	Yes	Billing country code (ISO 3166-1 alpha-2)

Request Example

curl --location 'https://api.firstoken-staging.co/v1/tokens/enroll' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data '{
  "transaction_info": {
    "type": "enroll_card"
  },
  "card": {
    "number": "{{ TOKEN_ID: detokenize }}",
    "expiration_date": "{{ TOKEN_ID: detokenize }}"
  },
  "bill_to": {
    "address_1": "Carrera 140",
    "address_2": "Carrera 140",
    "city": "Bogotá DC",
    "state": "Bogotá",
    "postal_code": "110001",
    "country": "CO"
  }
}'

Response Parameters

Parameter	Type	Description
status	string	Response status ("success" or "fail")
message	string	Human-readable response message
data.transaction_info.type	string	Response type ("enroll_card_response")
data.transaction_info.reference_code	string	Unique reference code for the enrollment request
data.transaction_info.request_id	string	Internal request identifier
data.transaction_info.status	string	Enrollment status (see status values below)
data.transaction_info.created_at	string	ISO 8601 timestamp of the request
data.error_info.reason	string	Error reason code (only present in error responses)
data.error_info.message	string	Error message (only present in error responses)

Enrollment Status Values

Status	Description
Enrolled	Card successfully enrolled in network tokenization
Not_enrolled	Card enrollment failed (see error_info for details)
Already_enrolled	Card was previously enrolled

Response Examples

Success Response (200 OK)

{
  "status": "success",
  "message": "Network token successfully stored",
  "data": {
    "transaction_info": {
      "type": "enroll_card_response",
      "reference_code": "bfe68a02-51cd-4d66-b2ad-56fc55527e45",
      "request_id": "0001770745387125160590",
      "status": "Enrolled",
      "created_at": "2026-02-10T17:43:07.407Z"
    }
  }
}

Already Enrolled Response (409 Conflict)

{
  "status": "success",
  "message": "Network token already exists",
  "data": {
    "transaction_info": {
      "type": "enroll_card_response",
      "reference_code": "126e084f-5537-4d6c-8e6c-b6877b431b25",
      "request_id": "0001770744802919290552",
      "status": "Already_enrolled",
      "created_at": "2026-02-10T17:33:23.660Z"
    }
  }
}

Network Token Unavailable (409 Conflict)

{
  "status": "success",
  "message": "Network token is unavailable",
  "data": {
    "transaction_info": {
      "type": "enroll_card_response",
      "reference_code": "fd43e006-e6ad-48d8-beea-11bcda414af2",
      "request_id": "0001770745085323008850",
      "status": "Not_enrolled",
      "created_at": "2026-02-10T17:38:05.913Z"
    },
    "error_info": {
      "reason": "Unprovisioned",
      "message": "INVALID_REQUEST"
    }
  }
}

Workflow Not Implemented (409 Conflict)

{
  "status": "success",
  "message": "Workflow not implemented",
  "data": {
    "transaction_info": {
      "type": "enroll_card_response",
      "reference_code": "fd43e006-e6ad-48d8-beea-11bcda414af2",
      "request_id": "0001770745085323008850",
      "status": "Not_enrolled",
      "created_at": "2026-02-10T17:38:05.913Z"
    },
    "error_info": {
      "reason": "Unprovisioned",
      "message": "INVALID_REQUEST"
    }
  }
}

Bad Request (400)

{
  "status": "fail",
  "message": "Invalid request",
  "data": {
    "description": "Some fields are missing in the request",
    "path": "card.number"
  }
}

Internal Server Error (500)

{
  "status": "fail",
  "message": "Internal server error",
  "data": {
    "description": "An unexpected error occurred while processing the request"
  }
}

Error Handling

Status Code	Description	Action Required
200	Enrollment successful	Network token is provisioned and ready to use
400	Invalid request	Check request parameters and try again
409	Conflict (already enrolled, unavailable, or not implemented)	Check the specific message and error_info for details
500	Internal server error	Contact support if the issue persists