Cards

A card in ampliFi is either a debit card or a credit card, represented by a card record in the form of a JSON object. At most, one card can be associated with each account. However, a user with multiple accounts can have multiple cards.

Methods at this endpoint access, modify, or change the status of cards.

Endpoint or Section	Action
Card Object	Description of the card object
/cards	Get an array containing all cards belonging to the current user
GET /cards/:AFiCardId, /card/:AFiCardId	Get a specified card record for the current user
POST /cards/:AFiCardId, /card/:AFiCardId	Modify the properties of the specified card
/cards/:AFiCardId/activate, /card/:AFiCardId/activate	Activate a specified card for the current user
/card/:AFiCardId/pin	Change the PIN for the specified card
/card/:AFiCardId/reissue	Re-issue the specified card
/card/:AFiCardId/restriction	Modify the restrictions set on a specified card
/cards/:AFiCardId/:onoff, /card/:AFiCardId/:onoff	Turn the specified card on (transactions allowed) or off (transactions not allowed)

Card Object

The ampliFi API represents a card by a JSON object. This table lists properties usually included in a card object. Some details may vary depending on the account type.

Property	Description	Schema	Required? (default)	Example Values
AFiCardId	ampliFi ID for the card	string	yes	"qwegal8kgtmysmels"
AFiAccountId	ampliFi ID for this account	string	yes	"qwegal8kgtmysmels"
AFiUserId	ampliFi ID for the user of this card	string	yes	"qweaurl8kgtlv9pc"
id	ID for the card	string	no (AFiCardId)	"qwegal8kgtmysmels"
isSync	True if processing should be synchronous	boolean	no (true)	false
cardIdBO	Card ID at the backoffice	string	yes	"cd_5cg2g8nddz3r9"
accountIdBO	Account ID at the backoffice	string	yes	"cd_5cg2g8nddz3r9"
backOfficeId	Backoffice ID	string	yes	"evolve"
backOfficeName	Backoffice name	string	yes	"evolve"
typeId	The card type	string	yes	"Standard"
name_on_card	Name on the card	string	yes	"JOHN TESTMAN N"
num	16 digit card number (may be masked)	string	yes	"1234000000005678"
currency	3-digit currency code	string	yes	"USD"
image	Name of file containing card image	string (filename)	no (none)	"images/card1.png"
restrictions	Restrictions on the use of the card	object	no (none)	{ "dayOfWeek": { "0": false, //disable the card on Sundays } }
status	Card status ("active", "blocked")	string	yes	"active"
isActive	True if the card is currently active	boolean	no (true)	true
isActivated	True if the card has been activated	boolean	no (true)	true
isClosed	True if the account is closed	boolean	no (false)	false
dtsOpened	The date/time that the card was issued	dts string	yes	"2022-09-27T17:21:47.495Z"
dtsUpdated	The date/time that the card was last updated	dts string	yes	"2023-01-04T20:03:49.205Z"
dtsPreActivated	The date/time that the card was activated	dts string	yes	"2022-09-27T17:21:51.913Z"
dtsExpiry	Expiration date for the card	dts string	yes	"2025-10-01T03:59:59.999Z"

Card Object Example

{
    "card": {
        "_id": "6333312f048865fc7f5dd4b0",
        "AFiCardId": "qwegal8kgtmysmels", //card ID in ampliFi
        "backOfficeId": "evolve", //backoffice ID for this card
        "AFiAccountId": "qwegal8kgtmysmels", //account ID in ampliFi
        "AFiUserId": "qweaurl8kgtlv9pc", //user ID in ampliFi
        "accountIdBO": "cd_5cg2g8nddz3r9", //account ID in backoffice
        "backOfficeName": "evolve", //backoffice name for this card
        "cardIdBO": "cd_5cg2g8nddz3r9", //card ID in the backoffice
        "currency": "USD", //3-digit currency code
        "dtsExpiry": "2025-10-01T03:59:59.999Z", //card expiration date
        "dtsOpened": "2022-09-27T17:21:47.495Z", //date/time when card was opened
        "dtsPreActivated": "2022-09-27T17:21:51.913Z",
        "id": "qwegal8kgtmysmels", //card ID
        "image": "images/card1.png", //name of file containing card image
        "isActivated": true, //true if the card has been activated
        "isActive": true, //true if the card is currently active
        "isClosed": false, //true if the account has been closed
        "name_on_card": "JOHN TESTMAN NKPB", //full name on card
        "num": "1234000000005678", //card number, masked to show only first and last four digits
        "status": "active", //card status
        "typeId": "Standard", //card type
        "dtsUpdated": "2023-01-05T17:53:06.123Z", //date/time that card was last updated
        "name": "Test2" //card name
    },
    "success": true, //action was successful
    "userId": "qweaurl8kgtlv9pc" //user ID in ampliFi
}

Get All Cards

Request method and URL

GET /cards

Description

Returns an array of records for all cards that belong to this user.

The card numbers returned are masked to present only the first four and last four digits.

Request headers

{
    "token": "a long random string" //Authorization token received from /token request
}

Request body None

Response body example

  {
    "cards": [ // array of card objects*
    ],
    "success": true,
    "userId": "qwebar132i0h4xfy" //user ID in ampliFi
  }

See Card Object above

Back to Top

Get Card

Request method and URL

GET /cards/:AFiCardId or

GET /card/:AFiCardId

Description

Returns a record for a single card belonging to this user. The card is identified by a path parameter.

Some fields may vary depending on the requirements of the backoffice. Also, some fields such as name and pin are stored by the backoffice only and are not saved by ampliFi.

The card number returned is masked to present only the first four and last four digits.

Request headers

{
    "token": "a long random string" //Authorization token received from /token request
}

Request body None

Response body example

  { // card object *
  }

See Card Object above

Back to Top

Modify Card

Request method and URL

POST /cards/:AFiCardId or

POST /card/:AFiCardId

Description

Changes the properties of a card. The card is identified by the path parameter.

Only the properties to be changed should be included in the payload. Changes will only be made to properties that are permitted to change.

Request headers

{
    "Content-Type": "application/json"
    "token": "a long random string" //Authorization token received from /token request
}

Request body example

{ // payload object
    "name": "Test1"
}

Response body example

  {
    "success": true
  }

Possible Errors

Status Code	Description of possible error
404	Card was not found, Error calling ampliFi.cards.modify

Back to Top

Activate Card

Request method and URL

POST /cards/:AFiCardId/activate or

POST /card/:AFiCardId/activate

Description

Activates a card if it has not been activated yet. The card is identified by the path parameter.

If the card is already activated this call has no effect and the card record is returned. If the call succeeds, the record for the newly activated card is returned with the status set to "active" and the isActive property set to true.

Request headers

{
    "token": "a long random string" //Authorization token received from /token request
}

Request body None

Response body example

  {
    "success": true,
    "card": {} //record for the activated card *
  }

See Card Object above

Possible Errors

Status Code	Description of possible error
404	Card was not found, Error calling global.ampliFi.cards.activate

Back to Top

Change PIN

Request method and URL

POST /card/:AFiCardId/pin

Description

Changes a card's PIN. The card is identified by a path parameter. The new PIN must be given as 8 digits. However, digits only 3-6 will be extracted and sent to the backoffice as the actual PIN. The PIN is stored by the backoffice and cannot be retrieved.

Property	Description	Schema	Required? (default)	Example Values
pin	The new PIN (4 digits) with two dummy characters at each end, 8 characters total	string	yes	"12345678"

Request headers

{
    "Content-Type": "application/json"
    "token": "a long random string" //Authorization token received from /token request
}

Request body example

{
  "pin": "12345678", //new PIN with two dummy characters at each end
}

Response body example

  {
    "success": true
  }

Possible Errors

Status Code Description of possible error

401 This error will result if the "pin" value given is not 8 characters long

404 Invalid PIN, this error will result if characters 3-6 of the "pin" value (representing the new PIN) are invalid. For example, the actual PIN must be composed of digits so "pin": "123f5678" will throw a 404 error and fail to change the card PIN (because "3f56" is not a valid PIN). However, "pin": "f23456t8" will not throw an error because the "pin" code is 8 characters and the characters that represent the new PIN are all digits ("3456").

Back to Top

Reissue Card

Request method and URL

POST /card/:AFiCardId/reissue

Description

Reissue a card when the existing card is lost, damaged or stolen. The card is identified by a path parameter. The reason for the reissue is given in the request body. the reason can be either "lost" or "stolen".

If "stolen" the card will be given a new number. "lost" means it will be the same card number, but it may get a different expiration date. Unless the card number was compromised one way or another, use "lost".

Request headers

{
    "Content-Type": "application/json"
    "token": "a long random string" //Authorization token received from /token request
}

Request body example

{
  "reason": "lost", //allowed options: ["lost", "stolen"]
}

Response body example

  {
    "success": true
  }

Back to Top

Change Restrictions

Request method and URL

POST /card/:AFiCardId/restriction

Description

Makes changes to the restrictions set on a card. The card is identified by a path parameter. The available restrictions include:

Enable/disable the card on specific days of the week
Enable/disable the card at specific times of day
Allow or disallow transactions for specific Merchant Category Codes (MCCs)

Days of the week are indicated by the values 0 (Sunday) through 6 (Saturday). To enable or disable the card for a specific day, set the day value to true or false.

Time ranges are indicated by the codes xxn1yyn2, where xx and yy are either am or pm, and n1 and n2 are the specific hours that begin and end the range using a 12-hour clock.

Note that the restrictedMCCs property and the allowedMCCs property cannot both be present in the request body simutaneously. Doing so will cause an error to be thrown. If the restrictedMCCs property is present in the request body, the allowedMCCs property will automatically be set to null and vice versa. If you try to add allowedMCCs restrictions to a card that already has restrictedMCCs (and vice versa), an error will be thrown. Also, any MCC code listed in the restrictedMCCs object will be set to restricted (false), regardless of the property value given to that MCC code key in the object.

Property	Description	Schema	Required? (default)	Example Values
dayOfWeek	Restrictions for specific days of the week, 0 (Sunday) through 6 (Saturday)	object	no	{ "0": true, "2": false, ... }
timesOfDay	Restrictions for specific times of the day, xxn1yyn2, where xx and yy are either am or pm, and n1 and n2 are the specific hours that begin and end the range using a 12-hour clock	object	no	{ "am6pm12": false, "pm12pm9": true, "pm9am6": true }
allowedMCCs	List of allowed MCC codes. If present, all other MCC codes will be disallowed. This property cannot be present at the same time as the restrictedMCCs property.	object	no	{ "001": true, "002": true, ... }
restrictedMCCs	List of disallowed MCC codes. If present, all other MCC codes will be allowed. This property cannot be present at the same time as the allowedMCCs property.	object	no	{ "001": false, "002": false, ... }

Request headers

{
    "Content-Type": "application/json"
    "token": "a long random string" //Authorization token received from /token request
}

Request body examples

{
    "dayOfWeek": { 
      "0": false, //disable the card on Sundays
      "6": true //allow transactions on Saturdays (if the card is not OFF)
    }
}

{
  "dayOfWeek": { //optional
    "0": false, //disable the card on Sundays
    "6": true  //allow transactions on Saturdays (if the card is not OFF)
  }, 
  "timesOfDay": { //optional
    "am6pm12": true,
    "pm12pm9": true,
    "pm9am6": false 
  },
  "restrictedMCCs": { //optional. Merchant Category Codes that are prohibited when making transactions 
    "001": false,
    "002": true, //if MCC is listed under restricted MCCs, the restriction will set to false regardless of the value given for this MCC property in the request body
    "003": "true" //if MCC is listed under restricted MCCs, the restriction will set to false regardless of the value given for this MCC property in the request body
  }
}

If .allowedMCCs is given, .restrictedMCCs is dropped and vice versa. If .allowedMCCs is given, transactions from all other MCCs will be rejected. If .restrictedMCCs is given, only transactions from the given MCCs will be rejected.

Response body examples

{
    "success": true,
    "restriction": { //the resulting restriction after the changes are made
        "AFiCardId": "qwegal8kgtmysmels", //card ID in ampliFi
        "dayOfWeek": {
            "0": false,
            "6": true
        }
    }
}

{
    "success": true,
    "restriction": {
        "AFiCardId": "qwegal8kgtmysmels",
        "dayOfWeek": {
            "0": false,
            "6": true
        },
        "timesOfDay": {
            "am6pm12": true,
            "pm12pm9": true,
            "pm9am6": false
        },
        "allowedMCCs": null, //since the request body contained the restrictedMCCs property, the allowedMCCs property defaults to null
        "restrictedMCCs": {
            "001": false,
            "002": false,
            "003": false
        }
    }
}

Possible Errors

Status Code	Description of possible error
404	Not found, Failed modifying card restrictions, Failed calling backoffice, This error will be thrown if both `allowedMCCs` and `restrictedMCCs` are present in the request body simutaneously. This error will also be thrown if a card already has `allowedMCCs` restrictions and an attempt to add `restrictedMCCs`restrictions is made (or vice versa).

Back to Top

Turn Card ON or OFF

Request method and URL

POST /card/:AFiCardId/:onoff

or

POST /cards/:AFiCardId/:onoff

where :onoff should have the value on or off.

Description

Turning a card OFF means no transactions will be authorized. The card status will be set to "blocked" and the isActive property will be set to false.

Turning a card ON means that transactions can be authorized. The card status will be set to "active" and the isActive property will be set to true.

The card is identified by a path parameter. There is no request body.

Request headers

{
    "token": "a long random string" //Authorization token received from /token request
}

Request body None

Response body example

In this example, the card was set to on.

  {
    "success": true, //Success
    "status": "active", // should be active
    "isActive": true, // should be true    
    "card": {}, // record for the card *
    "userId": "qweaurl8kgtlv9pc" //user ID in ampliFi
}

In this example, the card was set to off.

{
    "success": true, //Success
    "status": "blocked", //status is set to blocked and transactions are not allowed
    "isActive": false, //is not currently active
    "card": {}, // record for the card *
    "userId": "qweaurl8kgtlv9pc" //user ID in ampliFi
}

See Card Object above

Possible Errors

Status Code	Description of possible error
404	Wrong input to ampliFi.cards.cardOnOff (error is thrown if the :onoff path parameter is anything other than "on" or "off"), Card not found (:AFiCardId path parameter given is not a valid card ID for the current user)

Back to Top