Creating Subscriptions

This section provides example requests for the various operations that are available for subscribing cards with the PayConex™ V4 API.

Requirements

• Registered Account: You need an active PayConex™ or ShieldConex® account.

• ShieldConex® Use Case: You need an active ShieldConex® account linked to your PayConex™ account if you are requesting a shieldconex or pan response.

  • 🚧

    Note

    The template reference associated with your ShieldConex® account must be also valid for PayConex™ tokenization and detokenization.

Request Parameters

Each endpoint below accepts a JSON object as the request body. This requires the following parameters to be present. Endpoint-specific parameters are outlined in the relevant examples.

For the comprehensive reference on these parameters, check out API Reference.

🚧

Note on the pan Response Format

Using this option currently requires an account on our ShieldConex® platform. If this option is something you would like to make use of, let us know during your integration.

Using ShieldConex® Tokens

The endpoint below is used to subscribe a ShieldConex® bfid and token representing the transationId. The bfid is usually extracted from the response of the PayConex™ CIT transaction. For more, see ShieldConex® Token.
Once there is an update, ShieldConex® generates and sends back the new bfid along with the tokenized card data for reissuing transactions.

Request

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

{
  "responseFormat": "shieldconex",
  "tokens": [
    {
      "bfid":"djI6MTIwMjQwN...",
      "token": "000000002687",
      "expiry": "1225"
    }
  ],
  "periodDate": "1719491006",
  "periodId": "PERIOD_1W"
}

*Required Scopes: pcx:account_updater:*, pcx:account_updater:schedules:create

Response

{
  "id": "css_d3b97f26b7d641c49fed010ac5b23dfd",
  "records": [
    {
      "id": "cssr_736262bb213647879883715f7d98d8c3",
      "token": "000000002687",
      "createdAt": "2024-07-26T11:23:31.000000Z",
      "updatedAt": "2024-07-26T11:23:31.000000Z",
      "type": "shieldconex",
      "enabled": true,
      "expiry": "1225",
      "cardSyncScheduleId": "css_d3b97f26b7d641c49fed010ac5b23dfd",
      "bfid": "djI6MTIwMjQwN..."
    }
  ],
  "periodId": "PERIOD_1W",
  "periodDate": "2024-06-27",
  "responseFormat": "shieldconex",
  "enabled": true,
  "createdAt": "2024-07-26T11:23:31.000000Z",
  "updatedAt": "2024-07-26T11:23:31.000000Z",
  "templateRef": "shieldconex_template_reference"
}

Using PayConex™ Tokens

The endpoint below is used to subscribe updates to a PayConex™ token (or tokens).

The tokens parameter is an array of PayConex™ transactionId values to include in the subscription request. The PAN data associated with that transaction is used to generate a new transactionId for reissuing transactions once there is an update. The updated transactionId(token_id) is then used to modify the recurring payment schedule via SLAPI or for reissuing transactions via QSAPI.

Request

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

{
  "responseFormat": "payconex",
  "tokens": [
    {
      "token": "000000000007"
    }
  ],
  "periodDate": "1719491006",
  "periodId": "PERIOD_1W"
}

*Required Scopes: pcx:account_updater:*, pcx:account_updater:schedules:create

Response

{
  "id": "css_c139326a47d84f338253b4fa9fee109b,
  "records": [
    {
      "id": "cssr_72cd887bc5f54a9799b528b396db1737",
      "token": "000000000007",
      "createdAt": "2024-07-26T11:00:22.000000Z",
      "updatedAt": "2024-07-26T11:00:22.000000Z",
      "type": "payconex",
      "enabled": true,
      "expiry": "1230",
      "cardSyncScheduleId": "css_c119326a46d84f338263b4fa6fee109b"
    }
  ],
  "periodId": "PERIOD_1W",
  "periodDate": "2024-06-27",
  "responseFormat": "payconex",
  "enabled": true,
  "createdAt": "2024-07-26T11:00:22.000000Z",
  "updatedAt": "2024-07-26T11:00:22.000000Z"
}

Using PAN Data

The endpoint below is used to subscribe a card's PAN data for account updates.

In addition to the parameters above, the request body also includes a cards parameter. This parameter is an array of card data values to include in the subscription request. Each element of the array includes the card number in the pan parameter and the expiration date for the card in the expiry parameter. ShieldConex® is used to tokenize the PAN data and detokenize it once the merchant makes a request to receive the card update. The updated data can be used for the QSAPI transactions and, for example, storing the new card data.

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

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

*Required Scopes: pcx:account_updater:*, pcx:account_updater:schedules:create

Response

{
  "id": "css_085a06dc9bbb408fa16c2e9d433abf1e",
  "records": [
    {
      "id": "cssr_689d01c3a10a41088a036e88c61a5174",
      "token": "5850459886792406",
      "createdAt": "2024-07-26T11:18:33.000000Z",
      "updatedAt": "2024-07-26T11:18:33.000000Z",
      "type": "shieldconex",
      "enabled": true,
      "expiry": "9929",
      "cardSyncScheduleId": "css_085a06dc9bbb408fa16c2e9d433abf1e",
      "bfid": "djI6MTIwMjQwN..."
    }
  ],
  "periodId": "PERIOD_1W",
  "periodDate": "2024-06-27",
  "responseFormat": "pan",
  "enabled": true,
  "createdAt": "2024-07-26T11:18:33.000000Z",
  "updatedAt": "2024-07-26T11:18:33.000000Z",
  "templateRef": "shieldconex_template_reference"
}

Response Parameters

Period ID Definitions