Create authorization control

Action: POST
Endpoint: /authcontrols

Limit where a user can make transactions to a single merchant or group of merchants. If multiple authorization controls apply to the same user, the limits of all controls are combined.

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier of the authorization control.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.
36 char max
name string Yes The name of the authorization control. 255 char max
active boolean No Indicates whether the authorization control is active. true | false

Default: true
start_time string No The date and time the exception goes into effect. yyyy-MM-ddThh:mm:ssZ
end_time string No The date and time the exception ends. yyyy-MM-ddThh:mm:ssZ
merchant_scope object No Defines the group of vendors to which the authorization control applies.

Populate no more than one field. If no fields are populated, the control applies to all vendors.
association object Yes Defines the group of users to which the authorization control applies.

You must populate one, and only one, field.

The merchant_scope object

Name Type Required? Description Allowable Values
mid string No MID (Merchant ID). The unique identification number of a vendor.

Enter a value to control access to a particular vendor.
36 char max
mcc string No A single MCC (Merchant Category Code). Identifies the type of goods or services provided by the vendor.

Enter a value to control access to a particular type of product or service.
4 char max
mcc_group string No Token indentifying a group of MCCs.

Enter a value to control access to a group of product or service types.
Existing MCC group token.

Issue a GET to /mccgroups to retrieve MCC group tokens.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes Token identifying either a card product or user.

Specify a card product token in the card_product_token field to apply the authorization control to all users holding active cards associated with the card product. Specify a user token in the user_token field to apply the authorization control to a single user.

Pass either card_product_token or user_token, not both.
Existing card product or user token.

Issue a GET to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

{
"merchant_scope": {
"mid": "98765"
},
"association": {
"user_token": "bigbird_token"
},
"token": "my_authcontrol",
"name": "My Auth Control"
}

Sample response body

{
"token": "my_authcontrol",
"name": "My Auth Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mid": "98765"
}
}


Retrieve authorization control

Action: GET
Endpoint: /authcontrols/{token}

Retrieve a specific authorization control.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the authorization control to return. Existing authorization control token.

Issue a GET to /authcontrols to retrieve authorization control tokens.

Sample response body

{
"token": "my_authcontrol",
"name": "My Auth Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mid": "98765"
}
}


Update authorization control

Action: PUT
Endpoint: /authcontrols/{token}

Update a specific authorization control.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the authorization control to update. Existing authorization control token.

Issue a GET to /authcontrols to retrieve authorization control tokens.

Body field details

Name Type Required? Description Allowable Values
name string Yes The name of the authorization control. 255 char max
active boolean No Indicates whether the authorization control is active. true | false

Default: true
start_time string No The date and time the exception goes into effect. yyyy-MM-ddThh:mm:ssZ
end_time string No The date and time the exception ends. yyyy-MM-ddThh:mm:ssZ
merchant_scope object No Defines the group of vendors to which the exception applies.

Specify only one value. If no values are specified, the exception applies to all vendors.
association object Yes Defines the group of users to which the authorization control applies.

You must populate one, and only one, field.

Note: You must include this object in your request even if you don't intend to update its values.

The merchant_scope object

Name Type Required? Description Allowable Values
mid string No MID (Merchant ID). The unique identification number of a vendor.

Enter a value to control access to a particular vendor.
36 char max
mcc string No A single MCC (Merchant Category Code). Identifies the type of goods or services provided by the vendor.

Enter a value to control access to a particular type of product or service.
4 char max
mcc_group string No Token indentifying a group of MCCs.

Enter a value to control access to a group of product or service types.
Existing MCC group token.

Issue a GET to /mccgroups to retreive MCC group tokens.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes Token identifying either a card product or user.

Specify a card product token in the card_product_token field to apply the authorization control to all users holding active cards associated with the card product. Specify a user token in the user_token field to apply the authorization control to a single user.

Pass either card_product_token or user_token, not both.
Existing card product or user token.

Issue a GET to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

{
"merchant_scope": {
"mcc": "5111"
}
}

Sample response body

{
"token": "my_authcontrol",
"name": "My Auth Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mcc": "5111"
}
}


List authorization controls

Action: GET
Endpoint: /authcontrols

List all authorization controls associated with a specific user or card product, or list all authorization controls defined in your program.

Include either a user or a card_product query parameter to indicate the user or card product whose associated authorization controls you want to retrieve (do not include both).

To list all authorization controls for your program, omit the user and card_product query parameters from your request.

This endpoint supports field filtering and pagination.

Query parameters

Name Type Required? Description Allowable Values
user string No The token identifying the user whose associated authorization controls you want to retrieve.

Enter the string "null" to list authorization controls that are not associated with a user.
Existing user token or the string "null".

Issue a GET to /users to retrieve existing tokens.
card_product string No The token identifying the card product whose associated authorization controls you want to retrieve.

Enter the string "null" to list authorization controls that are not associated with a card product.
Existing card product token or the string "null".

Issue a GET to /cardproducts to retrieve existing tokens.

Sample response body

{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "my_authcontrol",
"name": "My Auth Control",
"active": true,
"association": {
"user_token": "bigbird_token"
},
"merchant_scope": {
"mcc": "5111"
}
}
]
}