Credit Cards

Credit cards can be accessed through the API via the credit_cards base URL:

$ curl https://app.handshake-app.com/api/v2/credit_cards

• Supported list methods: GET POST
• Supported detail methods: GET PUT DELETE

Credit cards are also frequently accessed as sub-resources of either orders or customers.

Security & Decryption

Credit cards are the most sensitive information stored in Handshake and there is an extra layer of security around them as a result. All the card numbers and CVVs you store in Handshake are encrypted using a key that is itself safeguarded by your security token.

• When writing new card numbers into Handshake via POST or PUT, you do not need to provide your security token, as they can be encrypted just fine without it.
• When reading existing card numbers out via GET, you will need to provide your security token so that they can be decrypted. If you do not provide your security token, the numbers and CVVs will all be returned as empty strings.

To provide your security token, simply base64-encode it and use it as the password in the HTTP basic authentication (as discussed here) instead of using the normal 'X'.

For example, if your API key was "abcd1234" and the security token on your account was "c4tchm3ifyouc4n", then the basic authentication your would provide would be abcd1234:YzR0Y2htM2lmeW91YzRu.

Fields

card.type (string)

The type of this credit card, as selected from the available choices.

card.lastFour (string)

The last four digits on this credit card.

card.month (string)

The two-digit month portion of the expiry date.

card.year (string)

The four-digit year portion of the expiry date.

card.expiry (readonly string)

Returns the expiry date in the standard slash-separated format, e.g. "09/14".

card.name (string)

The person's name on this credit card.

card.number (encrypted string)

The full 15 or 16 digit card number. As discussed above, when reading resources via GET this will be a blank string unless you have provided your security token.

card.cvv (encrypted string)

The 3 or 4 digit CVV code. As discussed above, when reading resources via GET this will be a blank string unless you have provided your security token.

Example

{
    "cdate": "2012-04-22", 
    "ctime": "2012-04-22T20:26:19Z", 
    "customer": "/api/v2/customers/2013", 
    "cvv": "", 
    "entityType": "CreditCard", 
    "lastFour": "1234", 
    "month": "12", 
    "mtime": "2012-04-22T20:26:20Z", 
    "name": "Jay Gatsby", 
    "number": "", 
    "objID": 109269, 
    "owner": "Demo", 
    "resource_uri": "/api/v2/credit_cards/109269", 
    "type": "DISCOVER", 
    "uuid": "9234e0c5-1464-41d3-b837-49ad0bacb64a", 
    "year": "12"
}

Note: This is obviously an unrealistic example, because the real Jay Gatsby wouldn't be seen dead with a Discover card. Platinum Amex all the way in West Egg.