API Reference
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:
- 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.
| 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. 2026).
|
| 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=2026" \
-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"{
"response": {
"token": "card_pIQJKMs93GsCc9vLSLevbw",
"scheme": "master",
"display_number": "XXXX-XXXX-XXXX-0000",
"issuing_country": "AU",
"expiry_month": 5,
"expiry_year": 2026,
"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 |
{...}
|
|---|
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:{
"response": {
"token": "card_pIQJKMs93GsCc9vLSLevbw",
"scheme": "master",
"display_number": "XXXX-XXXX-XXXX-0000",
"issuing_country": "AU",
"expiry_month": 5,
"expiry_year": 2026,
"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 |
{...}
|
|---|
