Joint Accounts API
Joint Account API Endpoint
Create Joint Account
This API changes an individual account to become a joint account.
Certain other APIs are affected by or return differently for joint account scenarios and are detailed after this endpoint section.
Route
POST /programs/{ProgramCode}/accounts/{AccountIdentifier}/AccountHolderRoute Parameters
Parameter name | Type | Value | Description |
|---|---|---|---|
ProgramCode | string | wf | This property identifies the program type of the account to be created. |
AccountIdentifier | string | GUID | The individual account identifier |
Headers
Parameter name | Type | Value | Description |
|---|---|---|---|
| X-GD-RequestId | uuid | varies | This property is used to uniquely identify each request. |
Authorization | bearer token | varies | the token get from GD |
Request
{
"requestPhysicalCard": boolean,
"currency": "string",
"termsAcceptances": [
{
"termsIdentifier": "string",
"termsAcceptanceDateTime": "string",
"termsAcceptanceFlag": true
}
],
"userProfile": {
"version": "string",
"ephemeralPublicKey": "string",
"publicKeyHash": "string",
"data": "string"
}
}Property name | Required | Value | Description |
|---|---|---|---|
productMaterialType | N | pvc | This property identifies the type of material to use for the card. |
currency | Y | USD | This property identifies the currency type of the account. Uses Alpha-3 ISO-4217 Currency code. |
termsAcceptances[].termsIdentifier | Y | See “Allowed Terms and Conditions” section below for values | This property identifies a terms document that the user has accepted. |
termsAcceptances[].termsAcceptanceDateTime | Y | "2024-07-17T03:08:28.067Z" | This property identifies the dateTime stamp of when the customer accepted the terms document. Uses ISO-8601 in UTC format “YYYY-MM-DDTHH:MM:SS.SSSZ“. |
termsAcceptances[].termsAcceptanceFlag | Y | true or false | This property identifies the election of a legal terms document accepted by the user. (See “Allowed Terms and Conditions“ below) For any of the |
requestPhysicalCardFlag | Y | true or false | This property identifies if the client wants a physical card issued immediately as part of the enrollment process. To create an account with a virtual payment instrument only, this flag must be set to “false”. Partner can use lifeCycleEvent API to request initialPhysicalCard later |
userProfile | Y | object | Encrypted data.
Unencrypted User Data Parameters can be found below. |
Allowed termsIdentifier values
Description | “termsIdentifier” value | “termsAcceptanceFlag“ value |
|---|---|---|
Deposit Account Agreement | daa | true |
Privacy Policy | privPlcy | true |
Electronic Communications Agreement | eca | true |
| TCPA Promotional Messaging Express Written Consent | TcpaPromo | true or false |
TCPA Informational Messaging Express Consent | TcpaInfo | true |
Sample Request
{
"requestHeader": {
"requestId": "8a218080-cd0b-e948-18cb-8ec919a0b3d4"
},
"userProfile": {
"version": "EC_v1",
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE3ju/a8kC8G8IIzIbhWtfNmkkOs+DmCAp1vCqnX2FrmpyWiRwLt+q4slTf40ICGWCbK4tcon1aGLcS6R3TkMxTw==",
"publicKeyHash": "PiRV5ko8JYGxAtcNb9WV4aVg7aXIp8EsstmeUqqWzT8=",
"data": "kFNmPZi3KoR3pSV7EO3I1/M4Ss4zd5Zhia2dJhI9DGu03d5M9pwrMSVlmG21NqvR9cN9pSi592dgkQOmQhY01nU/IzV1FnKcdVmnhManjtsrwAe4u2S464gAraBtTWaVMbnHirTEJDE4WgKu/kIh+FpCE8kuzf/A+6XRJdsUraF/iu38fn+IzkwIGqiIjyAc92TM7hTA/pPToRL4dXhi/9dpBsr3F+6kjKbezoC9cMlHQMBG+Ulzb7R3ksLihfiI586X2EXYQ197zb1cZ3P4qcAr3a3tyKx1/6XJs8i+hB5mZHWy0108/XBi4RGg3et8H+h4RtVogqNMptw4oxzNR72UxAg65+LqZZx96M+ITPme33Jgjz2LWk3G3X4cx4Zox60PHh4siWPCW4OvuwtnuqpL/EldWavhR6ZVPoM1DU5p/VCnIPZy4Ilvh3XJFv0hmsOHDZnRQvrceH88KU/iyD3yweUtQbhJOIl0ZpL2KSuSMi42/kv0aOnYKgPTdCjgqJd99Sb1UBtpmqi3JU3OITTWjvUNjaZe0k3EuncTYfBDLsHXbCbORqRkMaMIgoCenhFF1g2bBBiQ6Yn/47cxthZBMmdpNkhsO+YDNNuxdghwR3Eqm2VMDa/HgkiDSgZEoisUWO6LfcMlcPC6Mb/fwWt1rKkIeQnQroFTTBhd8qxdH/Dxmmxpx3WlD8TtrLVB9eJ5VU7oNmmv1QYPTROuyFMgKg=="
},
"productMaterialType": "pvc",
"requestPhysicalCard": false,
"currency": "USD",
"termsAcceptances": [
{
"termsIdentifier": "termsAndConditions",
"termsAcceptanceDateTime": "2025-01-16T05:53:52.184Z",
"termsAcceptanceFlag": true
},
{
"termsIdentifier": "privPlcy",
"termsAcceptanceDateTime": "2025-01-16T05:53:52.184Z",
"termsAcceptanceFlag": true
},
{
"termsIdentifier": "daa",
"termsAcceptanceDateTime": "2025-01-16T05:53:52.184Z",
"termsAcceptanceFlag": true
},
{
"termsIdentifier": "eca",
"termsAcceptanceDateTime": "2025-01-16T05:53:52.184Z",
"termsAcceptanceFlag": true
}
]
}Sample Encrypted User Data
This object is to be serialized as a string, and then encrypted using the public key provided by Green Dot Corporation.
{
"DateOfBirth": "1988-02-02",
"FirstName": "Second JWFA0ur4",
"MiddleName": "Second",
"LastName": "Second HSFrUNde",
"Addresses": [
{
"AddressLine1": "16506 Cornell Rd",
"AddressLine2": "SUITE 652",
"City": "Cincinnati",
"State": "OH",
"ZipCode": "40983",
"Type": "home",
"IsDefault": true,
"IsVerified": true
}
],
"email": {
"emailAddress": "[email protected]",
"isDefault": true,
"IsVerified": true
},
"phoneNumbers": [
{
"number": "2153415457",
"type": "Mobile",
"isDefault": true,
"IsVerified": true
}
],
"ssn": "103553311"
} Response
{
"accountIdentifier": "16c6252f-0677-4fcd-8983-9d5375316a14",
"status": "normal",
"accountHolders": [
{
"firstName": "First IlVSPY4",
"lastName": "First KqNGAL4",
"userIdentifier": "e2c747de-8798-441f-9b8c-970d2ccfd406",
"kycStateData": {
"ofacStatus": "passed",
"kycStatus": "passed",
"kycPendingGate": "healthy"
}
},
{
"firstName": "Second Srb77Y6z",
"lastName": "Second VLaHlcXE",
"userIdentifier": "ae7a58b0-9ae1-44de-b163-e91aec6023f1",
"kycStateData": {
"ofacStatus": "passed",
"kycStatus": "passed",
"kycPendingGate": "healthy"
}
}
],
"accountStatusReasons": [
"healthy"
],
"responseDetails": [
{
"code": 0,
"subCode": 0,
"description": "API operation was successful.",
"url": "http://tbd"
}
]
}Unencrypted User Data Parameters
Object or property name | Type | Is Required | Description |
|---|---|---|---|
firstName | property | required | Must be 1-35 characters only. Refer to the “Valid Characters for Names, Cities, and Addresses” table for allowed characters. |
middleName | property | optional | Max 100 characters, if provided. |
lastName | property | required | Must be 2-35 characters only. Refer to the “Valid Characters for Names, Cities, and Addresses” table for allowed characters. |
addresses | object array | required | This object identifies the full residential address for the user. A home address must be provided, and it must be set as the default address in the |
addresses.type | property | required | This property identifies the type of the address. Must set value as “home” for tax products. |
addressLine1 | property | required | This property identifies the street address of the user. Must contain 2-40 characters only. Cannot be a PO Box or non-U.S. address. All U.S. Protectorates, U.S. Military (by state codes AA, AB, AP), or Canadian addresses are not allowed. Warning: Must not include |
addressLine2 | property | required | This property identifies the apartment, unit, suite, etc, associated with the user’s address. Max length 40 characters, if provided. |
city | property | required | This property identifies the city of the address. |
state | property | required | This property identifies the state of the address. Must be a two-character state code. Acceptable codes are limited to the 50 U.S. states plus the District of Columbia (DC). All U.S. Protectorates and Military state codes (AA, AB, AP) are not allowed. Canadian province codes are not allowed. |
zipCode | property | required | This property identifies the ZIP code of the address. Must be only 5 digits. No extended zip codes allowed. |
isDefault | property | required | This property identifies the default object to use used for email, phone, or address items. |
ssn | property | required | This property identifies the full Social Security number (SSN) of the user. |
dateOfBirth | property | required | This property identifies the Date of Birth (DOB) of the user. Must be between 1901 and current date and provided in the form YYYY-MM-DD. |
object | required | This object identifies the email address of the user, along with its verification status. | |
emailAddress | property | required | This property identifies the email address of the user. String value with a max length of 255 characters. Note: In the Partner Integration Environment (PIE), a lower environment, enrollment requests allow email addresses containing a “+” character in the username portion. In production environments this is not allowed. If the username portion of an email address being attempted for enrollment contains a “+” character, then that request will fail. In production, the partner’s front-end application should use a mechanism that looks for that character and returns guidance to the customer to change the requested email address and remove any disallowed characters. |
phoneNumbers | object | required | This object identifies the phone number of a user. |
number | property | required | This property identifies the phone number of the user.
|
phoneNumbers.type | property | required | This property identifies the type of
|
isVerified | property | optional | This property identifies the verification status for ownership and possession of the contact channel. E.g. if a One-Time Passcode is sent as a Multi-Factor Authentication via SMS, and has successfully been submitted back to the partner, then a mobile device is considered verified. |
Related APIs Affected by Joint Accounts
This is an existing API and no contract changes, but will return two account holders for a joint account.
This is an existing API and no contract changes, but will return two account holders for a joint account.
This is an existing API and no contract changes, but will return two account holders' payment instruments for a joint account.
This is an existing API and no contract changes for non-Joint Accounts, but has an added request validation on joint accounts. When the transfer type is achPull / achOut for joint accounts, userIdentifier field is required. If this field is missing, this property will get an error response.
This is an existing API, wherein the property userIdentifier is now added in the request body. When calling add BillPay payment for joint accounts, userIdentifier is required only for Joint Accounts and, if missing, this property will get error response.
This is an existing API that for joint accounts has a response that is enhanced to include the userIdentifier who initiated the transaction.
For joint account, there is one more property userIdentifier to the webhooks request payload posted in certain scenarios. See link for more.
Updated about 24 hours ago