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 Name | Description |
---|---|
responseFormat | This 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. |
periodDate | This is a UNIX timestamp of the date to begin sending the requested card data for updating. |
periodId | This 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 FormatUsing 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
Parameter | Description |
---|---|
id | The id value returned in the response is the scheduleId parameter that can be used for the GET results end-point. |
periodId | This 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. |
periodDate | This is a UNIX timestamp of the date to begin sending the requested card data for updating. |
responseFormat | The response format that was sent as part of the original subscription request. |
enabled | The current status of the subscription. |
createdAt | The date/time this subscription was created. |
updatedAt | The date/time of the last update for this subscription. |
tokens or cards | This is a JSON array containing the details of each token or card that was submitted as part of the request. |
Period ID Definitions
Period ID | Description |
---|---|
PERIOD_1W | Sets the schedule to be run on a weekly basis. |
PERIOD_2W | Sets the schedule to be run every two weeks. |
PERIOD_1M | Sets the schedule to be run on a monthly basis. |
PERIOD_2M | Sets the schedule to be run every two months. |
PERIOD_3M | Sets the schedule to be run every three months. |
PERIOD_6M | Sets the schedule to be run every six months. |
PERIOD_1Y | Sets the schedule to be run annually. |
MONTHLY_1_15 | Sets the schedule to be run every month on the 1st & 15th. |
MONTHLY_5_20 | Sets the schedule to be run every month on the 5th & 20th. |
MONTHLY_FIRST | Sets the schedule to be run on the first day of each month. |
MONTHLY_LAST | Sets the schedule to be run on the last day of each month. |
QUARTERLY_1 | Sets the schedule to be run on the first day of each fiscal quarter. |
QUARTERLY_LAST | Sets the schedule to be run on the last day of each fiscal quarter. |
YEARLY_Q1_1 | Sets the schedule to be run annually on the first day of the first fiscal quarter. |
YEARLY_Q2_1 | Sets the schedule to be run annually on the first day of the second fiscal quarter. |
YEARLY_Q3_1 | Sets the schedule to be run annually on the first day of the third fiscal quarter. |
Updated almost 2 years ago
Check out code examples and more in the following articles!