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.

POST /cards

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

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.

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. 2025).
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=2025" \
 -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": "AU",
    "expiry_month": 5,
    "expiry_year": 2025,
    "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"
    }
  ]
}

GET /cards/card-token

Returns the details of a card.

Example

curl https://test-api.pinpayments.com/1/cards/card_pIQJKMs93GsCc9vLSLevbw -u your-secret-api-key:
200 OK
{
  "response": {
    "token": "card_pIQJKMs93GsCc9vLSLevbw",
    "scheme": "master",
    "display_number": "XXXX-XXXX-XXXX-0000",
    "issuing_country": "AU",
    "expiry_month": 5,
    "expiry_year": 2025,
    "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
  }
}

Error Responses

404 not_found {...}
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}
Pin Payments acknowledges the Traditional Owners and Custodians of the Country throughout Australia and recognises their continuing connection to land, water and community.
We pay our respects to Aboriginal and Torres Strait Islander cultures, and to Elders past and present.