Cards API

The cards API allows you to securely store payment card details in exchange for a card token. This card token can then be used to create a single charge with the charges API or to create multiple charges over time using the customers API.

Each card object has a property called primary, which says whether the card is the customer’s primary card. Its value is true if the card is its customer’s primary card, false if it is a non-primary card of its customer, and null if it is not associated with a customer record.

A card token can only be used once, to create either a charge or a customer. If no charge or customer is created within one month, the token is automatically expired.

There are two ways of authenticating when using this API to store card details:

  1. In your secure environment, by using HTTP basic access authentication with one of your secret API keys.
  2. In an insecure environment, such as a web browser or mobile application, by using one of your publishable API keys.

This API supports JSONP.

POST /cards

Securely stores a card’s details and returns its token and other information.

Optional publishable_api_key Your publishable API key, if requesting from an insecure environment.
number The card number (e.g. 5520000000000000).
expiry_month The month of expiry (e.g. 12).
expiry_year The year of expiry (e.g. 2024).
cvc The card security code (e.g. 123).
name The name on the card (e.g. Roland Robot).
address_line1 Line 1 of the card’s billing address (e.g. 42 Sevenoaks St).
Optional address_line2 Line 2 of the card’s billing address (e.g. Apt 1).
address_city The city of the card’s billing address (e.g. Lathlain).
Optional address_postcode The postcode of the card’s billing address (e.g. 6454).
Optional address_state The state of the card’s billing address (e.g. WA).
address_country The country of the card’s billing address. Either the full name (e.g. Australia) or the ISO 3166-1 two-letter country code (e.g. AU).

Example

curl https://test-api.pinpayments.com/1/cards -d "publishable_api_key=your-publishable-api-key" \
 -d "number=5520000000000000" \
 -d "expiry_month=05" \
 -d "expiry_year=2024" \
 -d "cvc=123" \
 -d "name=Roland Robot" \
 -d "address_line1=42 Sevenoaks St" \
 -d "address_line2=" \
 -d "address_city=Lathlain" \
 -d "address_postcode=6454" \
 -d "address_state=WA" \
 -d "address_country=Australia"
201 Created
{
  "response": {
    "token": "card_pIQJKMs93GsCc9vLSLevbw",
    "scheme": "master",
    "display_number": "XXXX-XXXX-XXXX-0000",
    "issuing_country": "US",
    "expiry_month": 5,
    "expiry_year": 2024,
    "name": "Roland Robot",
    "address_line1": "42 Sevenoaks St",
    "address_line2": "",
    "address_city": "Lathlain",
    "address_postcode": "6454",
    "address_state": "WA",
    "address_country": "Australia",
    "network_type": null,
    "network_format": null,
    "customer_token": null,
    "primary": null
  },
  "ip_address": "192.0.2.42"
}

Error Responses

422 invalid_resource {...}
{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": [
    {
      "code": "number_invalid",
      "message": "Number can't be blank",
      "param": "number"
    }
  ]
}