PayConexDecryptxShieldConexTECS Platform
Guides
Request SandboxContact Us

Creating Subscriptions

Suggest Edits

This section outlines how to subscribe cards for account updates via the available API endpoints. Each endpoint uses a JSON request body and accepts a common set of parameters, as well as some endpoint-specific parameters. Examples of requests and responses are provided below.

Common Request Parameters

All endpoints require a JSON request body that includes the following parameters. Additional endpoint-specific parameters will be listed in their respective sections.

ParameterDescription
responseFormatDefines the format of the returned card data updates:

- payconex returns updated card data as a token_id for use in a PayConex recurring or reissue transaction.
- shieldconex returns updated card data as a ShieldConex bfid token.
- pan returns updated card data as raw PAN information.
periodDateA UNIX timestamp (in seconds) or an ISO 8601 date string indicating when to begin sending the card data for updates.
periodIdA predefined schedule that the Account Updater service follows to run updates. For allowed values, please see the Period ID Definitions table.

🚧

Note on the shieldconex and pan Response Format

Using these options currently requires a PayConex gateway to be configured to work with the Bluefin ShieldConex platform. If this option is something you would like to make use of please let us know during your integration.

Subscribing PayConex Tokens

To subscribe PayConex tokens for updates, use the following endpoint:

POST /api/v4/accounts/{accountId}/account-updater/payconex/subscribe

In addition to the common parameters, include the tokens parameter. This is an array of objects, each containing a token (the PayConex transaction_id).

Example Request:

{
  "responseFormat": "payconex",
  "tokens": [
    {
      "token": "100001234567"
    }
  ],
  "periodDate": "2022-02-01",
  "periodId": "PERIOD_1W"
}

A 201 HTTP status code indicates a successful subscription. The response contains details about the new subscription.

Example Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "periodId": "PERIOD_1W",
  "periodDate": "2022-10-04",
  "responseFormat": "payconex",
  "enabled": true,
  "createdAt": "string",
  "updatedAt": "string",
  "tokens": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "token": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "type": "payconex",
      "enabled": true,
      "expiry": "1230"
    }
  ]
}

Subscribing Cards Using PAN Data

To subscribe cards using their PAN data, use the following endpoint:

POST /api/v4/accounts/{accountId}/account-updater/pan/subscribe

In addition to the common parameters, include the cards parameter. This is an array of objects, each containing a pan (the full card number) and expiry (the card’s expiration date, formatted as MMYY).

Example Request:

{
  "responseFormat": "payconex",
  "cards": [
    {
      "pan": "4444333322221111",
      "expiry": "1230"
    }
  ],
  "periodDate": "1643673600",
  "periodId": "PERIOD_1W"
}

A 201 HTTP status code indicates a successful subscription. The response includes details about the subscription and the submitted cards.

Example Response:

{
  "id": "cssr_5cd5614dd4514735ae2d274597824c5e",
  "periodId": "PERIOD_1W",
  "periodDate": "2022-10-11",
  "responseFormat": "payconex",
  "enabled": true,
  "createdAt": "2022-10-11T02:20:21.643Z",
  "updatedAt": "2022-10-11T02:20:21.643Z",
  "tokens": [
    {
      "id": "cssr_5cd5614dd4514735ae2d274597824c5e",
      "token": "string",
      "createdAt": "2022-10-11T02:20:21.643Z",
      "updatedAt": "2022-10-11T02:20:21.643Z",
      "type": "payconex",
      "enabled": true,
      "expiry": "1230"
    }
  ]
}

Subscribing ShieldConex Tokens

To subscribe ShieldConex tokens for updates, use the following endpoint:

POST /api/v4/accounts/{accountId}/account-updater/shieldconex/subscribe

In addition to the common parameters, include the tokens parameter. This is an array of objects, each containing a ShieldConex bfid token.

Example Request:

{
  "responseFormat": "payconex",
  "tokens": [
    {
      "bfid": "djE6MTIwMjAxMTEzMTE1NTA1MTAzMTAzMDQyMXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHw2czdyYXp5djIvMD18U1ZUMjAxOTA0MTgxMkRFVg=="
    }
  ],
  "periodDate": "1643673600",
  "periodId": "PERIOD_1W",
  "enabled": true
}

A 201 HTTP status code indicates a successful subscription.

Example Response:

{
  "id": "css_de45079dfc7b472881dad0fef9500a59",
  "records": [
    {
      "id": "cssr_a9956ceba9f543aba20d8106b2644a76",
      "token": "100001234567",
      "createdAt": "2022-12-08T10:24:07.000000Z",
      "updatedAt": "2022-12-08T10:24:07.000000Z",
      "type": "shieldconex",
      "enabled": true,
      "expiry": "1230",
      "cardSyncScheduleId": "css_de45079dfc7b472881dad0fef9500a59",
      "bfid": "djE6MTIwMjAxMTEzMTE1NTA1MTAzMTAzMDQyMXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHw2czdyYXp5djIvMD18U1ZUMjAxOTA0MTgxMkRFVg=="
    }
  ],
  "periodId": "PERIOD_1W",
  "periodDate": "2022-02-01T10:24:07.000000Z",
  "responseFormat": "payconex",
  "enabled": null,
  "createdAt": "2022-12-08T10:24:07.000000Z",
  "updatedAt": "2022-12-08T10:24:07.000000Z",
  "templateRef": "1318651c261ad0f7aa2617e70041d54c"
}

Response Parameters

ParameterDescription
idThe schedule identifier for the subscription. Use this id with the GET results endpoint to retrieve updates.
periodIdThe schedule period used by the Account Updater. For allowed values, see Period ID Definitions.
periodDateThe start date for sending card updates, represented as a UNIX timestamp or an ISO 8601 date.
responseFormatThe specified format (payconex, shieldconex, or pan) chosen at subscription time.
enabledIndicates whether the subscription is currently active (true or false).
createdAtThe timestamp of when the subscription was created.
updatedAtThe timestamp of the most recent subscription update.
tokens or cardsA JSON array listing the subscribed tokens or cards along with their details (e.g., id, token, bfid, expiry).

Period ID Definitions

Period IDDescription
PERIOD_1WRun the schedule weekly.
PERIOD_2WRun the schedule every two weeks.
PERIOD_1MRun the schedule monthly.
PERIOD_2MRun the schedule every two months.
PERIOD_3MRun the schedule every three months.
PERIOD_6MRun the schedule every six months.
PERIOD_1YRun the schedule annually.
MONTHLY_1_15Run the schedule monthly on the 1st and 15th.
MONTHLY_5_20Run the schedule monthly on the 5th and 20th.
MONTHLY_FIRSTRun the schedule on the first day of each month.
MONTHLY_LASTRun the schedule on the last day of each month.
QUARTERLY_1Run on the first day of each fiscal quarter.
QUARTERLY_LASTRun on the last day of each fiscal quarter.
YEARLY_Q1_1Run annually on the first day of the first fiscal quarter.
YEARLY_Q2_1Run annually on the first day of the second fiscal quarter.
YEARLY_Q3_1Run annually on the first day of the third fiscal quarter.

Updated 5 days ago

What’s Next

Check out code examples and more in the following articles!