Customers API

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.

POST /customers

Creates a new customer and returns its details.

Parameters

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 one of the following:

card

The full details of the payment card to be stored {...}.

{
  "number": "5520000000000000",
  "expiry_month": "05",
  "expiry_year": "2024",
  "cvc": "123",
  "name": "Roland Robot",
  "address_line1": "42 Sevenoaks St",
  "address_city": "Lathlain",
  "address_postcode": "6454",
  "address_state": "WA",
  "address_country": "Australia"
}

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.

Example

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"

201 Created

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

Error Responses

422	invalid_resource	`{...}` `{ "error": "invalid_resource", "error_description": "One or more parameters were missing or invalid", "messages": [ { "param": "email", "code": "email_invalid", "message": "Email is not formatted properly" } ] }`

422

invalid_resource

{...}

{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": [
    {
      "param": "email",
      "code": "email_invalid",
      "message": "Email is not formatted properly"
    }
  ]
}

GET /customers

Returns a paginated list of all customers.

Example

curl https://test-api.pinpayments.com/1/customers -u your-secret-api-key:

200 OK

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

GET /customers/customer-token

Returns the details of a customer.

Example

curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ -u your-secret-api-key:

200 OK

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

Error Responses

404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`

PUT /customers/customer-token

Updates the details of a customer and returns the updated details. You can update the customer’s cards in one of four ways:

You can use the 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.
You can use the 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.
You can use the 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.
You can use none of the above parameters. The customer’s cards will not change.

In addition, you can update the customer’s email address and contact details.

Parameters

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 `{...}`. `{ "number": "5520000000000000", "expiry_month": "05", "expiry_year": "2024", "cvc": "123", "name": "Roland Robot", "address_line1": "42 Sevenoaks St", "address_city": "Lathlain", "address_postcode": "6454", "address_state": "WA", "address_country": "Australia" }` 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.

Example

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"

200 OK

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

Error Responses

404

not_found

{...}

{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

422

invalid_resource

{...}

{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": [
    {
      "param": "email",
      "code": "email_invalid",
      "message": "Email is not formatted properly"
    }
  ]
}

422

too_many_card_parameters

{...}

{
  "error": "too_many_card_parameters",
  "error_description": "You may only supply one of card, card_token and primary_card_token parameters"
}

DELETE /customers/customer-token

Deletes a customer and all of its cards. You will not be able to recover them.

Example

curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ -u your-secret-api-key: -X DELETE

204 No Content

No response body.

Error Responses

404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`

GET /customers/customer-token/charges

Returns a paginated list of a customer’s charges.

Example

curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/charges -u your-secret-api-key:

200 OK

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

Error Responses

404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`

GET /customers/customer-token/cards

Returns a paginated list of a customer’s cards.

Example

curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/cards -u your-secret-api-key:

200 OK

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

Error Responses

404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`

POST /customers/customer-token/cards

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.

Example

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"

201 Created

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

Error Responses

404

not_found

{...}

{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

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

DELETE /customers/customer-token/cards/card-token

Deletes a customer’s non-primary card. You will not be able to recover it.

Example

curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/cards/card_ZFThCjFi7wCNkopytxQVKA -u your-secret-api-key: -X DELETE

204 No Content

No response body.

Error Responses

404

not_found

{...}

{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

400

cannot_delete_primary_card

{...}

{
  "error": "cannot_delete_primary_card",
  "error_description": "You cannot delete a customer's primary card token"
}

GET /customers/customer-token/subscriptions

Retrieves the specified customer's subscriptions.

Example

curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/subscriptions -u your-secret-api-key:

200 OK

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

Error Responses

404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`

DELETE /customers/customer-token/subscriptions/sub-token

Cancels the subscription identified by subscription token. Subscriptions can only be cancelled if they are in trial or active state.

Example

curl https://test-api.pinpayments.com/1/customers/cus_XZg1ULpWaROQCOT5PdwLkQ/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ -u your-secret-api-key: -X DELETE

200 OK

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

Error Responses

400	invalid_state	`{...}` `{ "error": "invalid_state", "error_description": "Cannot cancel subscription when state is cancelled" }`
404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`

API Reference

Customers API

POST /customers

Parameters

Example

GET /customers

Example

GET /customers/customer-token

Example

PUT /customers/customer-token

Parameters

Example

DELETE /customers/customer-token

Example

GET /customers/customer-token/charges

Example

GET /customers/customer-token/cards

Example

POST /customers/customer-token/cards

Example

DELETE /customers/customer-token/cards/card-token

Example

GET /customers/customer-token/subscriptions

Example

DELETE /customers/customer-token/subscriptions/sub-token

Example