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:

In your secure environment, by using HTTP basic access authentication with one of your secret API keys.
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" } ] }`

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"
    }
  ]
}

API Reference

Cards API

POST /cards

Example

Error Responses