The customers API allows you to store a customer’s email address and payment card details. A customer can then be used with the charges API to create multiple charges over time.
A customer can have multiple cards. At any given time, one will be
considered the customer’s primary card. The card
property
of a customer object represents this primary card. Each card
object has a primary
property, which is true
for a customer’s primary card and false
for its other
cards.
Creates a new customer and returns its details.
The email address of the customer. | |
Optional first_name | The customer’s first name. |
Optional last_name | The customer’s surname. |
Optional phone_number | The customer’s contact number. |
Optional company | The company associated with the customer. |
Optional notes | Internal notes for the customer. |
and one of the following:
card |
The full details of the payment card to be stored {...} .
See the cards API for a description of each card parameter.
|
---|---|
card_token | The token of the card to be stored, as returned from the cards API or customers API. |
curl https://test-api.pinpayments.com/1/customers -u your-secret-api-key: \
-d "email=roland@pinpayments.com" \
-d "first_name=Roland" \
-d "last_name=Robot" \
-d "phone_number=1300 364 800" \
-d "company=Pin Payments" \
-d "notes=Account manager at Pin Payments" \
-d "card[number]=5520000000000000" \
-d "card[expiry_month]=05" \
-d "card[expiry_year]=2024" \
-d "card[cvc]=123" \
-d "card[name]=Roland Robot" \
-d "card[address_line1]=42 Sevenoaks St" \
-d "card[address_line2]=" \
-d "card[address_city]=Lathlain" \
-d "card[address_postcode]=6454" \
-d "card[address_state]=WA" \
-d "card[address_country]=Australia"
{
"response": {
"token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"email": "roland@pinpayments.com",
"first_name": "Roland",
"last_name": "Robot",
"phone_number": "1300 364 800",
"company": "Pin Payments",
"notes": "Account manager at Pin Payments",
"created_at": "2012-06-22T06:27:33Z",
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
}
}
}
422 | invalid_resource |
{...}
|
---|
Returns a paginated list of all customers.
curl https://test-api.pinpayments.com/1/customers -u your-secret-api-key:
{
"response": [
{
"token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"email": "roland@pinpayments.com",
"first_name": "Roland",
"last_name": "Robot",
"phone_number": "1300 364 800",
"company": "Pin Payments",
"notes": "Account manager at Pin Payments",
"created_at": "2012-06-22T06:27:33Z",
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
}
}
],
"count": 1,
"pagination": {
"current": 1,
"previous": null,
"next": null,
"per_page": 25,
"pages": 1,
"count": 1
}
}
Returns the details of a customer.
curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ -u your-secret-api-key:
{
"response": {
"token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"email": "roland@pinpayments.com",
"first_name": "Roland",
"last_name": "Robot",
"phone_number": "1300 364 800",
"company": "Pin Payments",
"notes": "Account manager at Pin Payments",
"created_at": "2012-06-22T06:27:33Z",
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
}
}
}
404 | not_found |
{...}
|
---|
Updates the details of a customer and returns the updated details. You can update the customer’s cards in one of four ways:
card[...]
parameters to store a new
card that will replace the customer’s primary card. The customer’s
current primary card will be removed from storage and you will not
be able to recover it.
card_token
parameter to replace the
customer’s primary card with a previously stored card. The card
token must either be already associated with this customer
record or unused. The customer’s current primary card will be
removed from storage and you will not be able to recover it.
primary_card_token
parameter to
switch the customer’s primary card to a previously stored card.
The card token must either be already associated with this
customer record or unused. The current primary card will become a
non-primary card of the customer.
In addition, you can update the customer’s email address and contact details.
Any of the following:
Optional email | The email address of the customer. |
---|---|
Optional first_name | The customer’s first name. |
Optional last_name | The customer’s surname. |
Optional phone_number | The customer’s contact number. |
Optional company | The company associated with the customer. |
Optional notes | Internal notes for the customer. |
And at most one of the following:
card |
The full details of the payment card to be stored {...} .
See the cards API for a description of each card parameter.
|
---|---|
card_token | The token of the card to be stored, as returned from the cards API or customers API. |
primary_card_token | The token of the card to become the customer’s primary card, as returned from the cards API or customers API. |
curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ -u your-secret-api-key: -X PUT \
-d "email=roland@pinpayments.com" \
-d "first_name=Roland" \
-d "last_name=Robot" \
-d "phone_number=1300 364 800" \
-d "company=Pin Payments" \
-d "notes=Account manager at Pin Payments" \
-d "card[number]=5520000000000000" \
-d "card[expiry_month]=05" \
-d "card[expiry_year]=2024" \
-d "card[cvc]=123" \
-d "card[name]=Roland Robot" \
-d "card[address_line1]=42 Sevenoaks St" \
-d "card[address_line2]=" \
-d "card[address_city]=Lathlain" \
-d "card[address_postcode]=6454" \
-d "card[address_state]=WA" \
-d "card[address_country]=Australia"
{
"response": {
"token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"email": "roland@pinpayments.com",
"first_name": "Roland",
"last_name": "Robot",
"phone_number": "1300 364 800",
"company": "Pin Payments",
"notes": "Account manager at Pin Payments",
"created_at": "2012-06-22T06:27:33Z",
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
}
}
}
404 | not_found |
{...}
|
---|---|---|
422 | invalid_resource |
{...}
|
422 | too_many_card_parameters |
{...}
|
Deletes a customer and all of its cards. You will not be able to recover them.
curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ -u your-secret-api-key: -X DELETE
404 | not_found |
{...}
|
---|
Returns a paginated list of a customer’s charges.
curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/charges -u your-secret-api-key:
{
"response": [
{
"token": "ch_lfUYEBK14zotCTykezJkfg",
"success": true,
"amount": 400,
"currency": "AUD",
"description": "test charge",
"email": "roland@pinpayments.com",
"ip_address": "203.192.1.172",
"created_at": "2012-06-20T03:10:49Z",
"status_message": "Success",
"error_message": null,
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
},
"transfer": [
{
"state": "paid",
"paid_at": "2012-06-27T03:10:49Z",
"token": "tfer_j_u-Ef7aO0Y4CuLnGh92rg"
}
],
"amount_refunded": 0,
"total_fees": 42,
"merchant_entitlement": 358,
"refund_pending": false,
"authorisation_token": null,
"authorisation_expired": false,
"authorisation_voided": false,
"captured": true,
"captured_at": "2012-06-20T03:10:49Z",
"settlement_currency": "AUD",
"active_chargebacks": false,
"metadata": {
"OrderNumber": "123456",
"CustomerName": "Roland Robot"
}
}
],
"count": 1,
"pagination": {
"current": 1,
"previous": null,
"next": null,
"per_page": 25,
"pages": 1,
"count": 1
}
}
404 | not_found |
{...}
|
---|
Returns a paginated list of a customer’s cards.
curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/cards -u your-secret-api-key:
{
"response": [
{
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
},
{
"token": "card_ZFThCjFi7wCNkopytxQVKA",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": false
}
],
"count": 2,
"pagination": {
"current": 1,
"previous": null,
"next": null,
"per_page": 25,
"pages": 1,
"count": 2
}
}
404 | not_found |
{...}
|
---|
Creates an additional card for the specified customer and returns its details. The customer’s primary card will not be changed by this operation.
There are two ways to call this. One way is to specify the card details directly using these parameters:
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 ).
|
The other way, if you’ve already created a card through the cards API, is to send the card token using this parameter:
card_token | The token of the card to be associated with the customer, as returned from the cards API or customers API. |
---|
curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/cards -u your-secret-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"
{
"response": {
"token": "card_ZFThCjFi7wCNkopytxQVKA",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": false
},
"ip_address": "192.0.2.42"
}
404 | not_found |
{...}
|
---|---|---|
422 | invalid_resource |
{...}
|
Deletes a customer’s non-primary card. You will not be able to recover it.
curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/cards/card_ZFThCjFi7wCNkopytxQVKA -u your-secret-api-key: -X DELETE
404 | not_found |
{...}
|
---|---|---|
400 | cannot_delete_primary_card |
{...}
|
Retrieves the specified customer's subscriptions.
curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/subscriptions -u your-secret-api-key:
{
"response": [
{
"state": "active",
"next_billing_date": "2023-05-31T20:13:45Z",
"active_interval_started_at": "2023-05-31T20:13:45Z",
"active_interval_finishes_at": "2023-05-31T20:13:45Z",
"cancelled_at": null,
"created_at": "2023-05-31T20:13:45Z",
"token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
"plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
"customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"card_token": "card_nytGw7koRg23EEp9NTmz9w"
}
],
"count": 1,
"pagination": {
"current": 1,
"previous": null,
"next": null,
"per_page": 25,
"pages": 1,
"count": 1
}
}
404 | not_found |
{...}
|
---|
Cancels the subscription identified by subscription token. Subscriptions can only be cancelled if they are in trial or active state.
curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ -u your-secret-api-key: -X DELETE
{
"response": {
"state": "cancelled",
"next_billing_date": null,
"active_interval_started_at": "2023-05-31T20:13:45Z",
"active_interval_finishes_at": "2023-05-31T20:13:45Z",
"cancelled_at": "2023-05-31T20:13:45Z",
"created_at": "2023-05-31T20:13:45Z",
"token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
"plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
"customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"card_token": "card_nytGw7koRg23EEp9NTmz9w"
}
}
400 | invalid_state |
{...}
|
---|---|---|
404 | not_found |
{...}
|