Get Payment Credentials

Retrieves the network payment credentials for an enrolled Firstoken token. This endpoint allows you to obtain the network token details to use with external processors that support network tokens.

Use Case: This endpoint is designed for scenarios where you want to process payments with a processor that accepts external network tokens. For example, you can use Cybersource TMS to provision the network token and then pass those credentials to processors like Rede, Credibanco, or other processors that support external network tokenization.

Endpoint

GET /v1/tokens/{ft_token}/payment-credentials

Environments

Production:

https://api.firstoken.co/v1/tokens/{ft_token}/payment-credentials

Sandbox (Testing):

https://api.firstoken-staging.co/v1/tokens/{ft_token}/payment-credentials

Authentication

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

x-api-key: <YOUR_API_KEY>

Prerequisites

1. Create API key with Payment Request permissions (see Enroll Card authentication section)

2. Activate Network Token service - Contact Firstoken team

3. Enroll the token - The token must be successfully enrolled using the Enroll Card endpoint

4. Wait for provisioning - Network payment credentials must be provisioned. You will receive a webhook notification with status: "ACTIVE" when provisioning is complete

Path Parameters

Parameter	Type	Required	Description
ft_token	string	Yes	The Firstoken permanent token

Request Example

curl --location 'https://api.firstoken-staging.co/v1/tokens/75899d7f-f138-4647-a247-5ba24a40ec01/payment-credentials' \
--header 'x-api-key: <YOUR_API_KEY>'

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 ("get_payment_credentials_response")
data.transaction_info.reference_code	string	Unique reference code for the request
data.transaction_info.request_id	string	Internal request identifier
data.transaction_info.status	string	Credential status ("Provisioned" or "Not_found")
data.transaction_info.created_at	string	ISO 8601 timestamp of the request
data.network_token_info.status	string	Network token status ("ACTIVE", "SUSPENDED", "DELETED")
data.network_token_info.card.number	string	Network token number (DPAN - Device/Network PAN)
data.network_token_info.card.brand	string	Card brand (visa, mastercard, etc.)
data.network_token_info.card.cryptogram	string	Token cryptogram/TAVV generated at payment time
data.network_token_info.card.expiration_month	string	Token expiration month
data.network_token_info.card.expiration_year	string	Token expiration year
data.network_token_info.card.expiration_date	string	Token expiration date (MM/YYYY format)
data.network_token_info.eci	string	Electronic Commerce Indicator
data.network_token_info.issuer	object	Issuer information (optional)

Network Token Data Mapping

The following table shows the network payment credential data returned by the Get Payment Credentials endpoint:

Field	Path in Response	Typically Required	Description
Network Token Number (DPAN)	network_token_info.card.number	Yes	Device/Network PAN tokenized by card network
Token Expiration Month	network_token_info.card.expiration_month	Yes	Network token expiration month
Token Expiration Year	network_token_info.card.expiration_year	Yes	Network token expiration year
Cryptogram (TAVV)	network_token_info.card.cryptogram	Yes (CIT), Optional (MIT)	Token cryptogram generated at payment time
ECI	network_token_info.eci	Varies by network	Electronic Commerce Indicator (required for Visa and Elo)

Note: Field requirements and mappings vary by processor. The fields above are the network token credentials provided by Cybersource TMS. Your processor may require additional standard payment data (amount, currency, cardholder name, etc.) which you provide from your application. Always consult your specific processor's documentation for complete integration requirements.

Response Examples

Success Response (200 OK)

{
  "status": "success",
  "message": "Network token successfully provisioned",
  "data": {
    "transaction_info": {
      "type": "get_payment_credentials_response",
      "reference_code": "141249f9-b304-4943-8401-b84a869e5b4d",
      "request_id": "0001771948935660795383",
      "status": "Provisioned",
      "created_at": "2026-02-24T16:02:17.139Z"
    },
    "network_token_info": {
      "status": "ACTIVE",
      "card": {
        "number": "4895370019163853",
        "brand": "visa",
        "cryptogram": "AwAAAABOhVCN5isF9eD8gjcAAAA=",
        "expiration_month": "12",
        "expiration_year": "2027",
        "expiration_date": "12/2027"
      },
      "eci": "07",
      "issuer": {
        "shortDescription": "shortDescription",
        "longDescription": "longDescription",
        "email": "[e-mail]",
        "phoneNumber": "987654321",
        "url": "www.test.com"
      }
    }
  }
}

Not Found Response (404)

{
  "status": "fail",
  "message": "No active network token found",
  "data": {
    "transaction_info": {
      "type": "get_payment_credentials_response",
      "reference_code": "1948de70-de73-4c06-a3ea-02ebfa617d4a",
      "request_id": "0001771876180371509596",
      "status": "Not_found",
      "created_at": "2026-02-23T19:49:40.554Z"
    }
  }
}

Error Handling

Status Code	Description	Common Causes	Action Required
200	Success - credentials retrieved	Network token is provisioned and active	Use credentials with your external processor
404	No active network token found	Token not enrolled, provisioning pending, or token not eligible	Verify token is enrolled; wait 2-5 minutes for provisioning; check enrollment status

Usage Example with External Processor

Once you retrieve the network payment credentials, you can use them with external processors that support network tokens. Here's an example with Rede (Brazil):

// Step 1: Get network payment credentials from Firstoken
const credentialsResponse = await fetch(
  'https://api.firstoken.co/v1/tokens/75899d7f-f138-4647-a247-5ba24a40ec01/payment-credentials',
  {
    headers: {
      'x-api-key': '<YOUR_API_KEY>'
    }
  }
);

const credentials = await credentialsResponse.json();
const networkToken = credentials.data.network_token_info;

// Step 2: Use network token credentials with Rede (external processor)
// Note: Only the fields marked with /* from network token */ come from Cybersource
// All other fields are standard payment data you already have
const redePayment = await fetch('https://api.rede.com.br/v2/transactions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <REDE_AUTH_TOKEN>'
  },
  body: JSON.stringify({
    // Network token data from Cybersource:
    cardNumber: networkToken.card.number,              /* from network token */
    expirationMonth: networkToken.card.expiration_month, /* from network token */
    expirationYear: networkToken.card.expiration_year,   /* from network token */
    tokenCryptogram: networkToken.card.cryptogram,       /* from network token */
    securityAuthentication: {
      sai: networkToken.eci                              /* from network token */
    },
    
    // Standard payment data (you already have this):
    amount: 10000,                  // Your transaction amount
    currency: 'BRL',                // Your transaction currency
    cardholderName: 'John Doe',     // From your customer data
    // ... other processor-specific required fields
  })
});

Important: The network token credentials from Cybersource are:

• cardNumber (DPAN)

• expirationMonth and expirationYear (token expiration)

• tokenCryptogram (TAVV)

• eci (Electronic Commerce Indicator)

All other transaction data (amount, currency, cardholder info, etc.) comes from your application and is not related to the network token.

Important Notes

• Security: Network payment credentials are sensitive. Handle them securely and never log or store them permanently

• Cryptogram: The cryptogram (TAVV) is generated at the time of credential retrieval and should be used immediately

• Token Status: Only ACTIVE network tokens return credentials. SUSPENDED or DELETED tokens will return 404

• Processor Compatibility: Verify your processor supports external network tokens before implementation

• Field Requirements: Different processors may have different required fields. Always consult your processor's documentation