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

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": "2025",
  "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]=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"
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": "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 {...} 
{
  "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": "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:
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": "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 {...} 
{
  "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": "2025",
  "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]=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"
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": "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 {...} 
{
  "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": "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 {...} 
{
  "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": "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 {...} 
{
  "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. 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"
201 Created 
{
  "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 {...} 
{
  "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": "2024-12-21T11:53:02Z",
      "active_interval_started_at": "2024-12-21T11:53:02Z",
      "active_interval_finishes_at": "2024-12-21T11:53:02Z",
      "cancelled_at": null,
      "created_at": "2024-12-21T11:53:02Z",
      "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": "2024-12-21T11:53:02Z",
    "active_interval_finishes_at": "2024-12-21T11:53:02Z",
    "cancelled_at": "2024-12-21T11:53:02Z",
    "created_at": "2024-12-21T11:53:02Z",
    "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."
}
Pin Payments acknowledges the Traditional Owners and Custodians of the Country throughout Australia and recognises their continuing connection to land, water and community.
We pay our respects to Aboriginal and Torres Strait Islander cultures, and to Elders past and present.