API Reference
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
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. |
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]=2025" \
-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": "2023-06-22T06:27:33Z",
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
}
}
}
Error Responses
422 | invalid_resource |
{...}
|
---|
GET /customers
Returns a paginated list of all customers.
Example
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": "2023-06-22T06:27:33Z",
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "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:
{
"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": "2023-06-22T06:27:33Z",
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
}
}
}
Error Responses
404 | not_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 {...} .
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]=2025" \
-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": "2023-06-22T06:27:33Z",
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
}
}
}
Error Responses
404 | not_found |
{...}
|
---|---|---|
422 | invalid_resource |
{...}
|
422 | too_many_card_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
Error Responses
404 | not_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:
{
"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": "2023-06-20T03:10:49Z",
"status_message": "Success",
"error_message": null,
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
},
"transfer": [
{
"state": "paid",
"paid_at": "2023-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": "2023-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 |
{...}
|
---|
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:
{
"response": [
{
"token": "card_nytGw7koRg23EEp9NTmz9w",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": true
},
{
"token": "card_ZFThCjFi7wCNkopytxQVKA",
"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": "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 |
{...}
|
---|
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. 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 ).
|
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=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"
{
"response": {
"token": "card_ZFThCjFi7wCNkopytxQVKA",
"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": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"primary": false
},
"ip_address": "192.0.2.42"
}
Error Responses
404 | not_found |
{...}
|
---|---|---|
422 | invalid_resource |
{...}
|
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
Error Responses
404 | not_found |
{...}
|
---|---|---|
400 | cannot_delete_primary_card |
{...}
|
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:
{
"response": [
{
"state": "active",
"next_billing_date": "2024-12-09T20:20:38Z",
"active_interval_started_at": "2024-12-09T20:20:38Z",
"active_interval_finishes_at": "2024-12-09T20:20:38Z",
"cancelled_at": null,
"created_at": "2024-12-09T20:20:38Z",
"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 |
{...}
|
---|
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
{
"response": {
"state": "cancelled",
"next_billing_date": null,
"active_interval_started_at": "2024-12-09T20:20:38Z",
"active_interval_finishes_at": "2024-12-09T20:20:38Z",
"cancelled_at": "2024-12-09T20:20:38Z",
"created_at": "2024-12-09T20:20:38Z",
"token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
"plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
"customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"card_token": "card_nytGw7koRg23EEp9NTmz9w"
}
}
Error Responses
400 | invalid_state |
{...}
|
---|---|---|
404 | not_found |
{...}
|