Integration Flows

This page provides visual diagrams of the complete network token enrollment and lifecycle management workflows, including webhook notifications and credential retrieval scenarios.

Understanding the Diagrams

Each diagram shows the interaction between:

• Client: Your application

• Firstoken API (FT): Firstoken's API endpoints

• Network Token Provider (NT): Card network tokenization service

• Webhook Firstoken (WHK_FT): Firstoken's webhook system

• Webhook Client (WHK_CLI): Your webhook endpoint

---

Enrollment Flows

1. Successful Enrollment (Happy Path)

This is the complete flow when a token is successfully enrolled and provisioned:

Key points:

• Enrollment returns status: "Enrolled" immediately (200 OK)

• Provisioning happens asynchronously

• Webhook notification with status: "ACTIVE" confirms provisioning is complete

• Only call GET /payment-credentials AFTER receiving the webhook notification with status: "ACTIVE"

• Calling GET /payment-credentials before provisioning completes returns "No active network token found" (404)

Example Request:

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",
    "city": "Bogotá DC",
    "state": "Bogotá",
    "postal_code": "110001",
    "country": "CO"
  }
}'

Example Response:

{
  "status": "success",
  "message": "Network token successfully stored",
  "data": {
    "transaction_info": {
      "type": "enroll_card_response",
      "reference_code": "ffca6f02-6d58-414e-bc92-ace48431d16d",
      "request_id": "0001772042454742522802",
      "status": "Enrolled",
      "created_at": "2026-02-25T18:00:56.988Z"
    }
  }
}

---

2. Token Already Enrolled

What happens when you attempt to enroll a token that was previously enrolled:

Key points:

• Returns status: "Already_enrolled" (200 OK)

• No new provisioning needed

• Credentials are already available via GET /payment-credentials

• This is informational only - no action required

Example Response:

{
  "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"
    }
  }
}

---

3. Network Token Unavailable

When the card network doesn't support tokenization for this card:

Key points:

• Returns status: "Not_enrolled" with error_info.reason: "Unprovisioned" (200 OK)

• Common for prepaid cards, certain card types, or issuers without network tokenization

• GET /payment-credentials returns "No active network token found" (404)

• Continue using standard card credentials with Firstoken Payments API

Example Response:

{
  "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"
    }
  }
}

---

4. Workflow Not Implemented

Internal error when the workflow is not recognized:

Key points:

• Returns status: "fail" with message: "workflow not implemented" (200 OK)

• This is an internal error scenario

• Contact support if this occurs repeatedly

Example Response:

{
  "status": "fail",
  "message": "workflow not implemented",
  "data": {
    "transaction_info": {
      "type": "enroll_card_response",
      "reference_code": "f5d6dfdc-673d-4fbc-b6b0-f2df9d098280",
      "request_id": "0001771875982344085171",
      "status": "not_enrolled"
    }
  }
}

---

Webhook Notification Flows

Firstoken sends webhook notifications when network token status changes. Configure your webhook endpoint to receive these notifications.

Webhook Payload Structure

All webhook notifications follow this structure:

{
  "eventName": "networkTokenEvents",
  "eventDate": "2026-02-26T22:15:16.747Z",
  "token": "46229431x5xZ6478",
  "network_token_info": {
    "status": "ACTIVE|SUSPENDED|DELETED",
    "card": {
      "number": "489537******1624",
      "brand": "visa",
      "expiration_date": "12/2034"
    }
  },
  "eventId": "e21ca70e-e078-4b9a-970c-79b2c280a159"
}

---

1. Token Provisioned / Active

Sent when network payment credentials are successfully provisioned after enrollment or when a suspended token is reactivated:

Key points:

• Webhook payload: status: "ACTIVE"

• This webhook indicates credentials are ready

• After receiving this webhook, you can call GET /payment-credentials

• If using external processors, this is your signal to retrieve credentials

• This event is sent for:

  • Initial provisioning after enrollment

  • Token updates via lifecycle management

  • Reactivation of previously suspended tokens

Example Webhook Payload:

{
  "eventName": "networkTokenEvents",
  "eventDate": "2026-02-26T22:15:16.747Z",
  "token": "46229431x5xZ6478",
  "network_token_info": {
    "status": "ACTIVE",
    "card": {
      "number": "489537******1624",
      "brand": "visa",
      "expiration_date": "12/2034"
    }
  },
  "eventId": "e21ca70e-e078-4b9a-970c-79b2c280a159"
}

Example GET /payment-credentials Response:

{
  "status": "success",
  "message": "Network token successfully provisioned",
  "data": {
    "transaction_info": {
      "type": "get_payment_credentials_response",
      "reference_code": "ee3318b6-b7e3-4cd8-a264-3dbb43180ea1",
      "request_id": "0001772043765351822103",
      "status": "Provisioned",
      "created_at": "2026-02-25T18:22:45.826Z"
    },
    "network_token_info": {
      "status": "ACTIVE",
      "card": {
        "number": "4323126880477166",
        "brand": "visa",
        "cryptogram": "AwAAAAAFPnOQ04YF9eD8gjgAAAA=",
        "expiration_month": "12",
        "expiration_year": "2031",
        "expiration_date": "12/2031"
      },
      "eci": "07",
      "issuer": {
        "shortDescription": "shortDescription",
        "longDescription": "longDescription",
        "email": "[e-mail]",
        "phoneNumber": "987654321",
        "url": "www.test.com"
      }
    }
  }
}

---

2. Token Suspended

Sent when a token is temporarily suspended:

Key points:

• Webhook payload: status: "SUSPENDED"

• Token can be reactivated later by issuer

• Do not send payment authorizations with suspended tokens

• GET /payment-credentials returns "No active network token found" (404)

• Contact cardholder or have them contact issuer to reactivate

Example Webhook Payload:

{
  "eventName": "networkTokenEvents",
  "eventDate": "2026-02-26T22:15:16.747Z",
  "token": "46229431x5xZ6478",
  "network_token_info": {
    "status": "SUSPENDED",
    "card": {
      "number": "489537******1624",
      "brand": "visa",
      "expiration_date": "12/2034"
    }
  },
  "eventId": "e21ca70e-e078-4b9a-970c-79b2c280a159"
}

---

3. Token Deleted

Sent when a token is permanently deleted:

Key points:

• Webhook payload: status: "DELETED"

• This is a final state - token cannot be reactivated

• Typically occurs when account is closed or per cardholder instruction

• GET /payment-credentials returns "No active network token found" (404)

• Request new credentials from cardholder

Example Webhook Payload:

{
  "eventName": "networkTokenEvents",
  "eventDate": "2026-02-26T22:15:16.747Z",
  "token": "46229431x5xZ6478",
  "network_token_info": {
    "status": "DELETED",
    "card": {
      "number": "489537******1624",
      "brand": "visa",
      "expiration_date": "12/2034"
    }
  },
  "eventId": "e21ca70e-e078-4b9a-970c-79b2c280a159"
}

---

When to Call GET /payment-credentials

Call GET /payment-credentials when:

• You receive a webhook with status: "ACTIVE" after enrollment

• You receive a webhook with status: "ACTIVE" (indicating an update or reactivation)

• You're about to process a payment with an external processor

• You're polling and provisioning has completed (check via GET /payment-credentials returning 200 OK)

Don't call GET /payment-credentials when:

• You receive a webhook with status: "SUSPENDED" or status: "DELETED"

• Enrollment returned status: "Not_enrolled"

• You're using Firstoken Payments API exclusively (credentials are used automatically)

---

Integration Patterns

Pattern 1: Using Webhooks (Recommended)

Webhook-based flow:

1. Configure webhook endpoint in Firstoken Console (Integrations > Webhooks)

   • Set URL destination to your webhook receiver

   • Enable "Network Token Events" permission

2. Enroll token via POST /v1/tokens/enroll

3. Receive enrollment confirmation (status: "Enrolled")

4. Wait for webhook notification with status: "ACTIVE"

5. If using external processor: Retrieve credentials via GET /payment-credentials and use with your processor

6. If using Firstoken Payments API: No action needed - credentials are used automatically

Benefits:

• Real-time notification when credentials are ready

• No polling required

• Immediate notification of lifecycle changes (updates, suspensions, deletions)

• Most efficient integration approach

---

Pattern 2: Polling (Without Webhooks)

Polling-based flow:

1. Enroll token via POST /v1/tokens/enroll

2. Wait before first attempt (recommended: start polling after 1 minute)

3. Attempt to retrieve credentials via GET /payment-credentials

4. If 404 (Not found), retry with exponential backoff

5. Once credentials retrieved, use with external processor

Retry strategy example:

async function getCredentialsWithRetry(tokenId, maxRetries = 5) {
  let retryCount = 0;
  let delay = 60000; // Start with 60 seconds
  
  while (retryCount < maxRetries) {
    try {
      const response = await fetch(
        `https://api.firstoken.co/v1/tokens/${tokenId}/payment-credentials`,
        {
          headers: { 'x-api-key': '<YOUR_API_KEY>' }
        }
      );
      
      if (response.status === 200) {
        return await response.json();
      } else if (response.status === 404) {
        // Provisioning not complete yet
        retryCount++;
        console.log(`Retry ${retryCount}/${maxRetries} - waiting ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
        delay *= 1.5; // Exponential backoff
      } else {
        throw new Error(`Unexpected status: ${response.status}`);
      }
    } catch (error) {
      console.error('Error retrieving credentials:', error);
      throw error;
    }
  }
  
  throw new Error('Max retries reached - provisioning may have failed');
}

---

Troubleshooting

Scenario	What Happened	What to Do
| GET /payment-credentials returns 404 immediately after enrollment	Provisioning not complete yet	Wait for webhook with status: "ACTIVE" before calling GET /payment-credentials
Webhook shows status: "SUSPENDED"	Token temporarily suspended by issuer	Do not process payments; contact cardholder to resolve with issuer
Webhook shows status: "DELETED"	Token permanently deleted	Request new payment method from cardholder; cannot reactivate
Webhook shows status: "ACTIVE" but GET /payment-credentials returns 404	Sync delay between systems	Wait 10-30 seconds and retry; contact support if persists
Enrollment returns status: "Not_enrolled"	Card not eligible for network tokenization	Use standard credentials; network token unavailable for this card
No webhook received after 10+ minutes	Provisioning may still be in progress, or webhook delivery failed	Token may be enrolled but not yet provisioned - continue waiting. Check webhook endpoint configuration and verify endpoint is accessible. If webhook endpoint is working correctly, provisioning may take longer for certain cards.

---

Need Help?

• Webhook not working? Verify your endpoint is publicly accessible and returns 200 OK

• Credentials not provisioning? Check if card is eligible for network tokenization

• Status transitions unclear? Review the webhook payload structure and status values

• Integration questions? Contact Firstoken support team