PayConexDecryptxShieldConexTECS Platform
API Reference
Request SandboxContact Us

Managing a Subscription

Overview

Here are some other subscription operations relevant after creating a subscription(subscribing to a PayConex™/ShieldConex® tokens or PAN data).

Getting Subscription Details

This request allows a previously configured subscription to be retrieved by issuing an HTTP GET request. The appropriate PayConex™ account and subscriptionId are part of the endpoint URL.

GET /api/v4/accounts/{accountId}/account-updater/subscriptions/{subscriptionId}

*Required Scopes: pcx:account_updater:results:read

{
  "id": "css_d3b97f26b7d641c49fed010ac5b23dfd",
  "records": [
    {
      "id": "cssr_736262bb213647879883715f7d98d8c3",
      "token": "000000002687",
      "createdAt": "2024-07-03T21:05:29.000000Z",
      "updatedAt": "2024-07-04T14:00:21.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-03T21:05:29.000000Z",
  "updatedAt": "2024-07-03T21:05:29.000000Z",
  "templateRef": "8bbdb5c8d07b31196973010daaf908e0"
}

📘

Note

A subscriptionId is returned as part of the API response after a subscription is created. For more information, see our guide on Creating Subscriptions.

Editing a Subscription

Editing a subscription via PATCH involves modifying the following fields.

Request Body Parameters

ParameterTypeRequiredDescription
responseFormatstringNoSee Creating Subscriptions.
periodDatestringNoThis is a UNIX timestamp of the date on which to begin sending the requested card data for updating. Don't forget to set it about ten business days before you need the updated card data as It can take anywhere from five to 10 business days for the card issuers to issue back updated account data.
periodIdstringNoThis is the period, or schedule, that the Account Updater API follows to issue the cards for updating.
enabledbooleanNoIndicates if the token (schedule) should be active (true by default).

Since this is a PATCH method, none of the parameters are required to be in the request body.

Request Example

PATCH /api/v4/accounts/{accountId}/account-updater/subscriptions/{subscriptionId}

{
  "responseFormat": "payconex",
  "periodDate": "1719491006",
  "periodId": "PERIOD_1W"
}

*Required Scopes: pcx:account_updater:schedules:patch

🚧

Note

The records are not allowed to be modified in any shape or form. However, there is a scenario where you can Remove a Record and then add a new one to the existing subscription. Alternatively, you can remove/disable a previous subscription and create a new one.

Removing a Subscription

Using this endpoint, a request can also be sent that removes a subscription that was previously configured. This is accomplished issuing an HTTP DELETE request while the appropriate PayConex™ account and subscriptionId are part of the endpoint URL.

DELETE /api/v4/accounts/{accountId}/account-updater/subscriptions/{subscriptionId}

*Required Scopes: pcx:account_updater:schedules:delete

HTTP response code 204 indicates successful deletion.

Removing Records from a Subscription

This feature allows you to delete records that were previously set up as part of a schedule.

This is accomplished by issuing an HTTP DELETE request while the appropriate PayConex™ account, subscriptionId and recordId are part of the URL.

DELETE /api/v4/accounts/{accountId}/account-updater/subscriptions/{subscriptionId}/records/{recordId}

*Required Scopes: pcx:account_updater:schedules:delete

HTTP response code 204 indicates successful deletion.

📘

Note

A recordId is returned as part of the API response after a subscription is created. For more information, see our guide on Creating Subscriptions.

Adding Additional Records to an Existing Subscription

You can add one or more tokens/cards to an existing subscription without creating a new one. Depending on the responseFormat representing the type of data and subscription (such as PayConex™ tokens, ShieldConex® tokens, or raw PAN data), you can use the corresponding endpoint to add more items.

Adding PayConex™ Tokens to an Existing Subscription

The following request appends the PayConex™ tokens to the existing (PayConex™) subscription.

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

📘

Note

  • {accountId} value in the path is the PayConex™ account ID number.
  • {subscriptionId} value in the path is the identifier of the PayConex™ subscription to add new records to.
[
  {
    "token": "000000254006",
    "enabled": true
  },
  {
    "token": "000000253966",
    "enabled": true
  },
  {
    "token": "000000253886",
    "enabled": true
  }
]

*Required Scopes: pcx:account_updater:schedules:post

🚧

Note

After we get that subscription, we can see that those tokens are appended and turned into records accordingly.

Request Body Parameters

ParameterTypeRequiredDescription
tokenstringYesThe PayConex™ token (transaction_id) to add to the schedule.
enabledbooleanNoIndicates if the token should be active (true by default).

Adding ShieldConex® Tokens to an Existing Subscription

The following request appends the ShieldConex® tokens to the existing (ShieldConex®) subscription.

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

📘

Note

  • {accountId} value in the path is the PayConex™ account ID number.
  • {subscriptionId} value in the path is the identifier of the ShieldConex® subscription to add new records to.
[
  {
    "token": "100001234567",
    "bfid": "djE6MTIwMjAxMTEzMTE1NTA1MTAzMTAzMDQyMXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHw2czdyYXp5djIvMD18U1ZUMjAxOTA0MTgxMkRFVg==",
    "enabled": true,
    "expiry": "1230"
  }
]

*Required Scopes: pcx:account_updater:schedules:post

🚧

Note

After we get that subscription, we can see that this token is appended and turned into a record accordingly.

Request Body Parameters

ParameterTypeRequiredDescription
tokenstringYesA ShieldConex token identifier.
bfidstringYesThe ShieldConex BFID for the token.
enabledbooleanNoIndicates if this token should be active.
expirystringNoThe card's expiry date in MMYY format.

Adding Raw PAN Data to an Existing Subscription

The following request appends the PAN data entry to the existing (PAN) subscription.

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

📘

Note

  • {accountId} value in the path is the PayConex™ account ID number.
  • {subscriptionId} value in the path is the identifier of the PAN subscription to add new records to.
[
  {
    "pan": "4444333322221111",
    "expiry": "1230",
    "enabled": true
  }
]

*Required Scopes: pcx:account_updater:schedules:post

🚧

Note

After we get that subscription, we can see that this token is appended and turned into a record accordingly. In this particular case, ShieldConex® is used to tokenize the PAN data and detokenize it once the merchant makes a request to receive the card update. For example, this is what a PAN record looks like after subscripting the raw data to it.

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

Request Body Parameters

ParameterTypeRequiredDescription
panstringYesThe raw primary account number (card number).
expirystringYesThe card's expiry date in MMYY format.
enabledstringNoIndicates if this card should be active.