# 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. ```bash 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 ```json { "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 will receive a webhook notification with `status: "ACTIVE"` when provisioning is complete. You don't need to take any action. #### 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 #### 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 ``` ### Integration Options After successfully enrolling a token and completing provisioning, you have two options for using the network payment credentials: #### Option 1: Use with Firstoken Payments API (Recommended) **When to use:** * You process payments through Firstoken's Payments API * You want automatic credential selection and management * You prefer a fully managed solution with no additional integration work **How it works:** ```bash # Continue using the same payment endpoint - no changes needed POST /v1/payments { "transaction_info": { "type": "payment", "reference_code": "123456789" }, "card": { "number": "{{ TOKEN_ID: detokenize }}", "expiration_date": "{{ TOKEN_ID: detokenize }}", "security_code": "123" }, "order_info": { "amount_details": { "total_amount": 1000, "currency": "COP" } } } ``` **Benefits:** * ✅ Zero code changes required * ✅ Automatic credential selection (network token or standard card data) * ✅ Automatic lifecycle management * ✅ Seamless fallback if network credentials unavailable * ✅ Improved authorization rates automatically *** #### Option 2: Use with External Processors **When to use:** * You process payments with an external processor that supports network tokens (e.g., Rede, Credibanco) * You want to leverage Cybersource TMS for network token provisioning but process with another gateway * You need direct access to network payment credentials **How it works:** **Step 1: Retrieve network payment credentials** ```bash GET /v1/tokens/{token_id}/payment-credentials ``` **Step 2: Use credentials with your processor** ```javascript // Example: Using retrieved credentials with Rede const credentialsResponse = await fetch( 'https://api.firstoken.co/v1/tokens/75899d7f-f138-4647-a247-5ba24a40ec01/payment-credentials', { headers: { 'x-api-key': '' } } ); const credentials = await credentialsResponse.json(); const networkToken = credentials.data.network_token_info; // Send to external processor (example: Rede) const payment = await processWithExternalProcessor({ cardNumber: networkToken.card.number, expirationMonth: networkToken.card.expiration_month, expirationYear: networkToken.card.expiration_year, tokenCryptogram: networkToken.card.cryptogram, eci: networkToken.eci, amount: 10000 }); ``` **Requirements:** * ⚠️ Your processor must support external network tokenization * ⚠️ You must handle credential mapping to your processor's format * ⚠️ You are responsible for secure credential handling * ⚠️ Field requirements vary by processor - consult their documentation **Benefits:** * ✅ Flexibility to use your preferred payment processor * ✅ Access to full network token data * ✅ Control over how credentials are used * ✅ Support for processors with specific network token requirements *** #### Comparison | Feature | Firstoken Payments API | External Processor | | ------------------------- | ---------------------------- | ------------------------------- | | **Setup complexity** | None - automatic | Moderate - requires integration | | **Code changes** | None required | Custom integration needed | | **Credential management** | Fully automatic | Manual handling required | | **Lifecycle updates** | Automatic | Depends on processor | | **Fallback handling** | Automatic | Manual implementation | | **Best for** | Firstoken payment processing | Custom processor integrations | *** ### Complete Token Lifecycle #### When Using Firstoken Payments API ``` 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) ``` #### When Using External Processors ``` 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. Retrieve Payment Credentials (GET /v1/tokens/{token_id}/payment-credentials) ↓ 6. Map Credentials to Processor Format (cardNumber, cryptogram, eci, etc.) ↓ 7. Send Payment to External Processor (Using processor's API with network token data) ↓ 8. Payment Processed by External Processor (Improved authorization rates) ↓ 9. Automatic Lifecycle Management 🔄 (Card updates handled by issuer - retrieve new credentials as needed) ``` ### Understanding Enrollment Responses #### Success: Enrolled (200 OK) ```json { "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) ```json { "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) ```json { "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) ```json { "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) ```json { "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, if you use Firstoken's Payments API. Your payment requests remain exactly the same and the system automatically uses network payment credentials when available. If you use external processors, you'll need to retrieve credentials using the Get Payment Credentials endpoint. | | **How long does provisioning take after enrollment?** | Provisioning happens automatically in the background. You will receive a webhook notification with `status: "ACTIVE"` when provisioning is complete. 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 use network tokens with processors other than Firstoken?** | Yes. Use the Get Payment Credentials endpoint to retrieve the network token data and send it to external processors that support network tokenization (e.g., Rede, Credibanco). Verify your processor supports external network tokens before implementation. | | **Can I force a payment to use standard credentials instead of network payment credentials?** | No, when using Firstoken's Payments API. 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. If using external processors, retrieve the updated credentials using the Get Payment Credentials endpoint. | | **How do I know when to retrieve updated credentials for external processors?** | If you're using external processors, retrieve credentials each time before processing a payment to ensure you have the most current data. The Get Payment Credentials endpoint always returns the latest provisioned credentials. | | **Will I be charged extra for network tokenization?** | Contact your Firstoken account representative for pricing information related to network tokenization services. |