Creating Subscriptions

This section provides request examples for the various operations that are available for subscribing cards with the service.

Request Parameters

Each end-point below accepts a JSON object as the request body and will require the following parameters to be present. End-point-specific parameters will be outlined in the relevant examples.

Parameter NameDescription
responseFormatThis is the format you want to receive the updated card information.

Currently, there are two values allowed:

payconex: This option will return all card updates as an updated token_id value that can be used for PayCoenx recurring or reissue transactions.

pan: This option will return all card updates as raw pan data.
periodDateThis is a UNIX timestamp of the date to begin sending the requested card data for updating.
periodIdThis is the period, or schedule, that the Account Updater API will follow to issue the cards for updating. For a list of allowed periodId values please see the table below.

🚧

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 please let us know during your integration.

Using PayConex Tokens

To subscribe a PayConex token (or tokens) to be updated the following end-point can be used.

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

In addition to the parameters above, the request body would also include a token parameter. This parameter is an array of PayConex transaction_id values to include in the subscription request.

Example Request Body:

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

An HTTP response code of 201 indicates a successful request and the response body would be a JSON object.

An example response would appear something like this:

Example Response Body:

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

Using PAN Data

To subscribe a card's PAN data for account updates the following end-point can be used.

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

In addition to the parameters above, the request body would also include a cards parameter. This parameter is an array of card data values to include in the subscription request. Each element of the array would include the card number in the pan parameter and the expiration date for the card in the expiry parameter.

Example Request Body:

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

An HTTP response code of 201 indicates a successful request and the response body would be a JSON object.

An example response would appear something like this:

Example Response Body:

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

Response Parameters

ParameterDescription
idThe id value returned in the response is the scheduleId parameter that can be used for the GET results end-point.
periodIdThis is the period, or schedule, that the Account Updater API will follow to issue the cards for updating. For a list of allowed periodId values please see the table below.
periodDateThis is a UNIX timestamp of the date to begin sending the requested card data for updating.
responseFormatThe response format that was sent as part of the original subscription request.
enabledThe current status of the subscription.
createdAtThe date/time this subscription was created.
updatedAtThe date/time of the last update for this subscription.
tokens or cardsThis is a JSON array containing the details of each token or card that was submitted as part of the request.

Period ID Definitions

Period IDDescription
PERIOD_1WSets the schedule to be run on a weekly basis.
PERIOD_2WSets the schedule to be run every two weeks.
PERIOD_1MSets the schedule to be run on a monthly basis.
PERIOD_2MSets the schedule to be run every two months.
PERIOD_3MSets the schedule to be run every three months.
PERIOD_6MSets the schedule to be run every six months.
PERIOD_1YSets the schedule to be run annually.
MONTHLY_1_15Sets the schedule to be run every month on the 1st & 15th.
MONTHLY_5_20Sets the schedule to be run every month on the 5th & 20th.
MONTHLY_FIRSTSets the schedule to be run on the first day of each month.
MONTHLY_LASTSets the schedule to be run on the last day of each month.
QUARTERLY_1Sets the schedule to be run on the first day of each fiscal quarter.
QUARTERLY_LASTSets the schedule to be run on the last day of each fiscal quarter.
YEARLY_Q1_1Sets the schedule to be run annually on the first day of the first fiscal quarter.
YEARLY_Q2_1Sets the schedule to be run annually on the first day of the second fiscal quarter.
YEARLY_Q3_1Sets the schedule to be run annually on the first day of the third fiscal quarter.

What’s Next

Check out code examples and more in the following articles!