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