Purses
Purses API Overview
Purses APIs empower financial program platforms to offer flexible savings tools within user accounts. It supports goal-based savings experiences by allowing users to create, manage, and monitor custom purse containers tied to their account balances.
- ✅ Enables personalized savings features, increasing user engagement.
- 📊 Supports tracking of goal progression and interest earned, improving financial transparency.
Purses APIs specifically enable developers to manage savings purses within customer accounts, allowing for creation, retrieval, updates, closure, and interest calculation of purse balances.
Purses API Endpoints
POST /programs/{programCode}/accounts/{accountIdentifier}/purses
Creates a new savings purse for an account.
A savings purse can only be created if the customer’s account status is normal.
Interest Rate Tier information is included if provided. Returns the created purse details.
GET /programs/{programCode}/accounts/{accountIdentifier}/purses
Retrieves all purses and balances for an account, including available and ledger balances. Returns purse details and transfer status.
Purse Descriptions
The following characters can be used in purse descriptions.
Note: Forward and Backward slashes are not allowed.
| Character | Example |
|---|---|
| Uppercase or Capital Letters | A-Z |
| Lowercase Letters | a-z |
| Numbers or Digits | 0-9 only |
| Space | |
| Comma | , |
| Dash/hyphen | - |
| Colon | : |
| Parenthesis | () |
| Ampersand | & |
| Period | . |
| Apostrophe | ‘ |
| Exclamation | ! |
| Dollar Sign | $ |
| Percent | % |
| Asterisk | * |
| At Sign | @ |
| Pound or Hashtag | # |
| Plus Sign | - |
PUT /programs/{programCode}/accounts/{accountIdentifier}/purses/{purseIdentifier}
Updates the details of a specific purse, such as description, goal amount, icon, and round-up settings. Returns the updated purse details.
Restricted Accounts
Partners can update purses on accounts that are restricted with a cure (kycGate) by calling the above endpoint:
See KYC in the Enrollments APIs for more information about KYC verification.
Response Codes
| Scenario | Code | subCode | Description |
|---|---|---|---|
| A savings purse can only be created if the customer’s account status is normal. If the account status is not normal, the following will be returned. | 5 | 100 | An account must be in a normal status to add a purse. |
| Account status is restricted without a cure. | 5 | 100 | An account must be in an eligible status to add a purse. |
Response Codes
| Scenario | HTTP Status Code | code | subCode | Description |
|---|---|---|---|---|
| Purse being updated is not in normal status | 200 | 5 | 100 | An account must be in a normal status to update a purse. |
| There is an existing purse with the same name | 200 | 5 | 1020 | The purseName already exists. |
| Purse being updated is not a savings purse | 200 | 5 | 352 | Only a saving purse can be updated. |
| IconName more than 50 | 400 | 5 | 602 | The iconName should not be more than 50 chars. |
| Description more than 100 | 400 | 5 | 602 | The description should not be more than 100 chars. |
| Invalid goal amount | 400 | 5 | 354 | The goalAmount is invalid. |
| Invalid description chars | 400 | 5 | 640 | The description should only contain alphanumeric chars [Aa-Zz] [0-9]. |
| Invalid Identifier | 400 | 5 | 602 | Invalid Identifier. |
| Purse not found | 200 | 5 | 1000 | The purse does not exist. |
| Account not found | 404 | 10 | 0 | Account not found. |
DELETE /programs/{programCode}/accounts/{accountIdentifier}/purses/{purseIdentifier}
Closes an empty, non-spending savings purse for an account. Only allowed for purses with zero balance. Returns the status of the close operation.
GET /programs/{programCode}/accounts/{accountIdentifier}/purses/{purseIdentifier}/interest
Calculates interest earned for a purse over a specified date range. Dates must be in YYYY-MM-DD format and the end date must be in the past. Returns the calculated interest amount.
Updated 7 days ago