Manage accounts

Create account

To create an account on the Pismo platform, use the Create account application endpoint. This provides all necessary information to create the account and specify at least one customer (the account owner).

Certain attributes are required, depending on the account type. The submit parameter determines whether to create the account immediately (true) or to save it as a work in progress (false).

Required attributes

πŸ“˜

If an attribute is not defined for an account, it is inherited from its program. Certain attributes are required, depending on the account type.

AttributeDescription
program_id or acquisition_channelprogram_id is the unique ID of the program on the Pismo platform.

acquisition_channel is the unique ID of the original source of your customer (such as a referring web page or mobile app). Acquisition channels are configured at the program level. A channel is tied to one program.

If you don't use acquisition_channel, you must use the program_id attribute to validate new account creation.

Tips:
- To get a list of the program IDs registered for your Org, use the List programs endpoint.

- If you have the program_id, you can list its channels by using the List acquisition channels endpoint.
submitFlag that determines whether to create the account immediately (true) or to save it as a work in progress (false).

If submit=false, the application form is not sent for processing and the account is not created. Use the Update account application endpoint to add more information and to submit at a later time.

If submit=true, the account is created and no further changes are allowed.
applicantAttributes and objects of the customer who is the account holder. This object requires a document_number attribute to identify the account holder. The value for this field is usually a government-issued tax ID number.

See Customer objects and Address and phone objects.
due_dateMonthly cycle date. Every account has a starting date for the monthly accounting cycle. For credit cards, this date is the statement's due date. For checking accounts, prepaid cards, and debit cards, this date is usually set to the first day of the month and is used to group together monthly transactions. (Note: This attribute is required for credit full-balance program types.)

Important: The due_date parameter is passed as a numeric value. For example, for a due date 1 (first day of the month) its identifier could be something like 3063. This is the value you should use.

To get a list of due dates available for a particular program, send a GET request to orgs/v1/programs/${programId}/duedates.
granted_limit(Required for credit programs only) Maximum credit limit granted by a credit analysis. For more information, see Account limits.

Additional account attributes

Besides registration data, the Pismo platform enables you to set some additional attributes related to the account:

  • Limits for different financial operations (see Account limits).
  • exchange_mode – Exchange conversion rule for purchases in foreign currencies. Valid values are SAME_DAY for rate conversions at the purchase day or CLOSING for rates applied at the statement's cycle closing date (valid only for credit programs).
  • external_id – A custom account ID string that uniquely identifies the account within your organization.

Relationship between external_id and documentNumber

The external_id parameter is a unique external ID that you can add to an account. This parameter is not validated, so you can set its value according to your business needs.

By default, external_id is not set and the documentNumber parameter is used to identify an account within the program. (By default, there can be only one account per documentNumber within the same program.) However, if you set an external_id, this becomes the account’s unique ID within the Org. In this case, the documentNumber uniqueness rule is deactivated, so you can have multiple accounts in a program that use the same documentNumber.

πŸ“˜

Some older Pismo customers might be using the outdated program parameter ALLOW MULTI ACCOUNTS FOR CREDENTIAL for the same purpose. When this boolean parameter is set to true, the documentNumber uniqueness rule also is deactivated for the program.

Custom account attributes

The Accounts API also allows for persisting custom metadata associated with the customer, using the custom_fields object as a general key-value store. For example, you could store information like:

{
    "preferred-social-network": "facebook",
    "discounts-of-interest": ["restaurants", "movies"]
}

Optional application data

  • birth_date
  • account

Personal and company attributes

See Customer objects.

Address and phone attributes

See Address and phone objects.

Update account

Use the Update account application endpoint to modify an account that has the submit property set to false (meaning the account has been created but not yet activated).

Get account details

Use the Get account details endpoint to get an information summary for an account. The response also includes some financial data, such as the current balance.