The customers object

Sensible defaults

Paystand will do its best to default data in such a way that you do not need to include duplicate information.
For example, the root of the customer object should include a specified address. If no address is further specified for the default bank, legal entity, or merchant, then Paystand will use the root address for the default bank, legal entity, and merchant. You will only need to include additional addresses if they are different than the address at the root of the customer object.

Currently, this defaulting applies to:

  • address
  • contact
  • defaultBank

Even though Paystand is making it easier on platforms to create new customers by using sensible defaults, it is still the platform's responsibility to provide accurate information. I.e. if the merchant's business address is different from the bank address which is different from the legal entity address, it is the platform's responsibility to make sure to provide Paystand with the accurate address information for each of these.

Documentation

Request

The set of values available for a Platform to use as planKey when creating customers will be made available upon being given Platform access.

The defaultBank parameter immediately attaches a default bank to the customer. Once verified, the default bank may be used for withdrawing available balance or paying subscription fees. Please note that more banks can be added to the customer at a later time. When added, an additional bank can be made the default bank by using the isDefault flag.

A user can be created alongside your customer upon creation to make for easy access to this customer via the Paystand dashboard. This can be done by providing a username and password in your creation request.

Parameter

Specification

name

Type: String
Length: 1-256

The full name of the customer

email

Type: String
Max Length: 128 characters

A valid email for the customer.

planKey

Type: String
Length: 1-256

The planKey you would like to use for this customer. Valid planKeys will be provided by Paystand.

vanityName

Type: String
Length: 1-128

The vanity name is a unique key used for providing public access to a billing portal. If not provided, it will attempt to default to the customer name without spaces or special characters. e.g. the name "ACME Corporation" will receive a vanity name "acmecorporation", supposing it is available. If not, a random GUID will be assigned. This value can be updated.

description

Type: String
Length: 1-512

An optional description you can attribute to this customer.

settings

Type: JSON Object

Settings

The specified settings for this customer.

address

Type: JSON Object

Address

The address of the customer.

contact

Type: JSON Object

Contact

The contact information for the customer.

defaultBank

Type: JSON Object

Bank

The default bank used for this customer. This can be used for withdrawing funds, and optionally can be used to pay subscription fees.

legalEntity

Type: JSON Object

legalEntity

Detailed information about the legal entity for this customer.

merchant

Type: JSON Object

Merchant

Detailed information about the business this customer represents.

username

Type: String
Length: 1-128 characters

The login name used for an optional user created with this customer.

password

Type: String
Length: 1-128 characters

The password used for an optional user created with this customer.

meta

Type: JSON Object

Meta

Meta information you may want to include for this customer.

Response

📘

API Keys

The publishable and secret API keys will only be made available in the Customer creation response. All subsequent responses will exclude these values. Make sure you save these keys.

The id parameter in the Customer response is the value you will be using for authenticated calls. Use this as the value for the X-CUSTOMER-ID header when making authenticated API requests.

The planStatus object will inform you of what remaining steps may need to be taken to finish verifying a new customer. Once fully verified, your customer will have full access to its plan features.

All of the parameters from the initial request will appear in the response. In addition, the following parameters will also be included in the response:

Parameter

Description

id

The unique identifier for the customer.

object

Will have the value customer indicating this object is a customer response.

status

The current status of the customer. One of: "created", "active", "disabled", "locked"

planStatus

Embedded planStatus object.

keys.publishable

The publishable key associated with the customer. Note: this is only given once during customer creation.

keys.secret

The secret key associated with the customer. Note: this is only given once during customer creation.

created

The date the customer was created.

lastUpdated

The date the customer was lastUpdated

Examples

Customer request

{
  "name": "ACME Corp",
  "email": "[email protected]",
  "planKey": "paystand_lite",
  "description": "your custom description",
  "meta": {..},
  "address": {..},
  "contact": {..},
  "legalEntity": {..},
  "merchant": {..},
  "settings": {..}
}

Customer response

{
  "account": {
    "id": "b41f8286b3d1421db07ef01d",
    "object": "customer",
    "name": "ACME Corp",
    "email": "[email protected]",
    "description": "Your custom description",
    "planId": "e80ffb368e0d45b487a32ea1",
    "planKey": "paystand_lite",
    "planName": "PayStand Lite",
    "meta": {..},
    "address": {..},
    "contact": {..},
    "legalEntity": {..},
    "merchant": {..},
    "settings": {..},
    "keys": {..},
    "planStatus": {..},
    "status": "active",
    "created": "2015-08-08T06:29:47.000Z",
    "lastUpdated": "2015-11-08T06:30:00.000Z"
  }
}