How Network Token works

This guide explains the complete flow of network token enrollment and how it integrates seamlessly with your existing payment processing.

Enrollment Flow

The network token enrollment process consists of several steps that happen both synchronously (during your API call) and asynchronously (internal processing):

1. Enrollment Request

You initiate the enrollment by calling the /v1/tokens/enroll endpoint with an existing Firstoken permanent token. This token must already contain valid card information.

POST /v1/tokens/enroll
{
  "transaction_info": {
    "type": "enroll_card"
  },
  "card": {
    "number": "{{ TOKEN_ID: detokenize }}",
    "expiration_date": "{{ TOKEN_ID: detokenize }}"
  },
  "bill_to": {
    "address_1": "Carrera 140",
    "city": "Bogotá DC",
    "state": "Bogotá",
    "postal_code": "110001",
    "country": "CO"
  }
}

2. Network Token Creation

Firstoken communicates with the appropriate card network (Visa Token Service or Mastercard Digital Enablement Service) to request a network token for the stored card.

3. Enrollment Confirmation

You receive an immediate response indicating the enrollment status:

• Enrolled: Network token successfully created

• Already_enrolled: This token was previously enrolled

• Not_enrolled: Network token is unavailable for this card

{
  "status": "success",
  "message": "Network token successfully stored",
  "data": {
    "transaction_info": {
      "status": "Enrolled",
      "reference_code": "bfe68a02-51cd-4d66-b2ad-56fc55527e45"
    }
  }
}

4. Internal Provisioning (Automatic)

After a successful enrollment response, Firstoken performs internal verification to check if the network token was properly provisioned. If provisioning is successful, payment credentials are generated and stored internally.

Important: This step happens automatically in the background. You don't need to take any action or wait for additional notifications.

5. Ready for Payments

Once network payment credentials are provisioned internally, they are automatically used in subsequent payment requests. Your existing payment integration continues to work without any modifications.

Integration with Payments API

No Changes Required

After enrolling a token, you continue using the Payments API exactly as before. The same endpoint, same request format, same response structure:

POST /v1/payments
{
  "transaction_info": {
    "type": "payment",
    "reference_code": "123456789"
  },
  "card": {
    "number": "{{ TOKEN_ID: detokenize }}",
    "expiration_date": "{{ TOKEN_ID: detokenize }}",
    "security_code": "123" // You can use a temporal token for card security code {{ {{token_temp}} : transaction }}
  },
  "order_info": {
    "amount_details": {
      "total_amount": 1000,
      "currency": "COP"
    }
  },
  "bill_to": {
    "first_name": "John",
    "last_name": "Doe",
    "country": "US",
    "address_1": "1 Market St",
    "city": "san francisco",
    "state": "CA",
    "postal_code": "94105"
  }
}

Automatic Credential Selection

Behind the scenes, when you make a payment request with an enrolled token, Firstoken automatically:

1. Checks if payment credentials are available for this token

2. Uses network token payment credentials if they were successfully provisioned

3. Falls back to standard card data if network payment credentials are not available

4. Processes the payment seamlessly in either case

You never need to specify which credentials to use - the system handles this automatically to optimize authorization rates.

Credential Selection Logic

Payment Request
      ↓
Check Token Status
      ↓
   ┌──────────────────┐
   │ Network Payment  │
   │ Credentials      │
   │ Available?       │
   └────┬─────────┬───┘
        │         │
       YES       NO
        │         │
        ↓         ↓
   ┌────────┐ ┌──────────┐
   │ Use    │ │ Use      │
   │Network │ │Standard  │
   │Token   │ │Card Data │
   └────┬───┘ └────┬─────┘
        │          │
        └────┬─────┘
             ↓
      Process Payment

Complete Token Lifecycle

1. Create Firstoken Token
   (Standard tokenization)
         ↓
2. Enroll Token
   (POST /v1/tokens/enroll)
         ↓
3. Receive Enrollment Response
   (status: Enrolled/Already_enrolled/Not_enrolled)
         ↓
4. Internal Provisioning ⚡
   (Automatic - happens in background, 2-5 minutes)
         ↓
5. Make Payment Requests
   (POST /v1/payments - no changes needed)
         ↓
6. Automatic Credential Selection
   (Network payment credentials or standard data)
         ↓
7. Payment Processed
   (Improved authorization rates)
         ↓
8. Automatic Lifecycle Management 🔄
   (Card updates handled automatically by issuer)

Understanding Enrollment Responses

Success: Enrolled (200 OK)

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

What happens next:

• Firstoken provisions network payment credentials internally

• Future payments with this token will automatically use network payment credentials when available

• You don't need to do anything - continue using your payment integration as normal

Action required: None

---

Success: Already Enrolled (409)

{
  "status": "success",
  "message": "Network token already exists",
  "data": {
    "transaction_info": {
      "status": "Already_enrolled",
      "reference_code": "126e084f-5537-4d6c-8e6c-b6877b431b25"
    }
  }
}

What this means:

• This token was previously enrolled successfully

• Network payment credentials are already provisioned and active

• Future payments already benefit from network tokenization

Action required: None - this is informational only

---

Not Enrolled: Network Token Unavailable (409)

{
  "status": "success",
  "message": "Network token is unavailable",
  "data": {
    "transaction_info": {
      "status": "Not_enrolled"
    },
    "error_info": {
      "reason": "Unprovisioned",
      "message": "INVALID_REQUEST"
    }
  }
}

What this means:

• The card network doesn't support tokenization for this card

• Common reasons: prepaid cards, certain card types, issuer restrictions

What happens with payments:

• Payments continue to work normally using standard card credentials

• Authorization rates remain the same as before enrollment attempt

• No negative impact on your payment processing

Action required: None - continue using the token normally

---

Not Enrolled: Workflow Not Implemented (409)

{
  "status": "success",
  "message": "Workflow not implemented",
  "data": {
    "transaction_info": {
      "status": "Not_enrolled"
    },
    "error_info": {
      "reason": "Unprovisioned",
      "message": "INVALID_REQUEST"
    }
  }
}

What this means:

• The specific card type or network workflow isn't supported yet

• May be temporary based on card network capabilities

What happens with payments:

• Payments continue to work normally using standard card credentials

• No impact on your existing payment processing

Action required: None - continue using the token normally

---

Error: Bad Request (400)

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

Common causes:

• Missing required fields (card.number, card.expiration_date, billing address)

• Invalid Firstoken token reference

• Token doesn't exist or isn't a permanent token

• Incorrect detokenize syntax

Action required:

• Verify the token ID is correct and exists

• Ensure all required billing fields are included

• Check token reference format: {{ TOKEN_ID: detokenize }}

---

FAQ

Question	Answer
Do I need to change my payment requests after enrolling tokens?	No. Your payment requests remain exactly the same. The system automatically uses network payment credentials when available.
How long does provisioning take after enrollment?	Provisioning happens automatically in the background and typically completes within 2-5 minutes. You don't need to wait for it - just continue making payment requests normally. The system will use network payment credentials once they're ready.
What if enrollment fails? Can I still process payments?	Yes, absolutely. Enrollment failures don't affect your ability to process payments. The token will use standard card credentials.
Should I retry enrollment if I get "Not_enrolled"?	Don't retry immediately - the result won't change right away. However, eligibility may change over time depending on the card issuer or acquirer. You can attempt enrollment again at a later date. In the meantime, continue using the token normally with standard credentials.
Can I force a payment to use standard credentials instead of network payment credentials?	No. Credential selection is automatic and optimized for best authorization rates. You cannot manually override this behavior.
Do I need to re-enroll tokens periodically?	No. Once enrolled, network payment credentials remain active and are automatically updated through lifecycle management. When card information changes (new expiration date or card number), the network token is updated automatically by the card issuer without requiring re-enrollment.
What happens if a card is replaced (new expiration date or card number)?	Network tokens are automatically updated through lifecycle management when card details change. The card issuer sends updates to the card network, which updates your network payment credentials automatically. You don't need to create a new token or re-enroll.
Will I be charged extra for network tokenization?	Contact your Firstoken account representative for pricing information related to network tokenization services.