Create an Inbound - POST

To use this request, you have to create an Inbound Route first, to obtain the Inbound Route id. (To know how to create an Inbound in Firstoken Customer Portal go to our Descoping Components Guide

cUrl

POST /:id
curl -X POST https://api.firstoken.co/routes/:id \
-H "Content-Type: application/json"

Params of the request

• id: string A valid Inbound Route ID. (You previously have to create an Inbound in our module of Customer Portal)

Note: In case, you have to make some sandbox tests you must be called from the base URL https://api.firstoken-staging.co/routes

Example Inbound Request Body

{
    "card": {
        "number": "4242424242424242",
        "name": "John Smith",
        "exp": {
            "month": "01",
            "year": "2027"
        }
    }
}

Example Inbound Response Body

{
    "card": {
        "number": "dc33160d-79e0-4073-b374-6345298c9c84",
        "name": "John Smith",
        "exp": "dc33160d-79e0-4073-b374-6345298c9c84"
    }
}

If you need to specify that you're using a card with an 8-digit BIN, you can add the optional isEightDigitsBin property to the request body:

Example Inbound Request with 8-Bin cards

{
    "isEightDigitsBin": true,
    "card": {
        "number": "4242424242424242",
        "name": "John Smith",
        "exp": {
            "month": "01",
            "year": "2027"
        }
    }
}

The isEightDigitsBin property is optional. When included and set to true, it informs the API that the card being tokenized has an 8-digit BIN instead of the standard 6-digit BIN. This property should only be added to the request body when dealing with cards that have 8-digit BINs.

Configuration Options

Metadata Return: In the Inbound Route configuration on the portal, you can activate an option to return metadata in the API response. You can assign a name to this field where the API will return the card's metadata. The metadata can include the truncated PAN, BIN, last four digits, and token.

Permanent Token: In the portal configuration, you can set up the tokenization to use a permanent token. By selecting the "permanent token" option and activating the "persistent" setting, you ensure that the same card number always generates the same token.

Example Inbound Response with Metadata

{
    "isEightDigitsBin": true,
    "card": "926ba19f-ebeb-4c08-b072-6f44e1b23bbf",
    "CustomField": {
        "card": {
            "card_truncated": "424242******4242",
            "bin": "42424242",
            "last_four": "4242",
            "token": "926ba19f-ebeb-4c08-b072-6f44e1b23bbf"
        }
    }
}

Token Verification:

• Permanent tokens: Check via Customer Portal (Tokens section) or TaaS API.

• Temporal tokens: Use Transactions API with the transaction ID from the inbound request.