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.



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.

nameType: String
Length: 1-256

The full name of the customer
emailType: String
Max Length: 128 characters

A valid email for the customer.
planKeyType: String
Length: 1-256

The planKey you would like to use for this customer. Valid planKeys will be provided by Paystand.
vanityNameType: 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.
descriptionType: String
Length: 1-512

An optional description you can attribute to this customer.
settingsType: JSON Object


The specified settings for this customer.
addressType: JSON Object


The address of the customer.
contactType: JSON Object


The contact information for the customer.
defaultBankType: JSON Object


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


Detailed information about the legal entity for this customer.
merchantType: JSON Object


Detailed information about the business this customer represents.
usernameType: String
Length: 1-128 characters

The login name used for an optional user created with this customer.
passwordType: String
Length: 1-128 characters

The password used for an optional user created with this customer.
metaType: JSON Object


Meta information you may want to include for this customer.



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:

idThe unique identifier for the customer.
objectWill have the value customer indicating this object is a customer response.
statusThe current status of the customer. One of: "created", "active", "disabled", "locked"
planStatusEmbedded planStatus object.
keys.publishableThe publishable key associated with the customer. Note: this is only given once during customer creation.
keys.secretThe secret key associated with the customer. Note: this is only given once during customer creation.
createdThe date the customer was created.
lastUpdatedThe date the customer was lastUpdated


Customer request

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

Customer response

  "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",