Overview

The Enrollments API allows partners to enroll a new user into a product, create an account, and create a payment instrument (card) with one single call.

It also stores encrypted data and supports upgrading an account from a GPR (General Purpose Reloadable) account to a DDA (Direct Deposit Account) when the upgradeFlag parameter is set to true.

Note: Partners who are not configured for encryption will have encrypted data omitted from the data objects in their responses.

Types of Encrypted Data

Primary Purse

By default, every user automatically has one primary purse that is designated for a primary spending balance. A purse can be thought of as a balance container.

Example: When money is added to a user’s account through direct deposit, the amount is automatically credited to their primary purse.

A new user's initial status depends on the Know Your Customer (KYC) requirements and the Office of Foreign Assets Control (OFAC) requirements of the program

Processor Enrollment Retry Logic

After an enrollment passes OFAC and KYC, Green Dot sends it to the processor to create the card information. If, after 30 minutes, the processor does not return the card proxy and other information, Green Dot performs up to three additional attempts, with 30 minutes between each. If all four attempts to receive the information fail, Green Dot responds with a failure webhook.

Sample Webhook Response

AccountIdentifier":"6d12d546-be7f-4040-a1dc-9afb34C9e82a
CallerFilePath:C:\BuildAgent\work\ddd132225e437bb8\PN\Services\PublishNotification\PublishNotification.Logic\Publishers\PublisherBase.cs
CallerLineNumber":"422
CallerMemberName":"ProcessResponseMessage
ElapsedTimeToPost":"56 ms
EventType":"AccountUpdated
PostBackUrl":"https"::"partner
RequestMessage":{
	"account":{
		"accountIdentifier":"6d16d946-be7f-4040-a1dc-9afb34d9e82a",
		"accountReferenceNumber":"UMR0502579",
		"productCode":"50001",
		"productName":"XXXX Visa Debit Card",
		"status":"pending",
		"accountStatusChangedDateTime":"2021-07-14T16:18:53.572Z",
		"statusReasons":[
			"registrationNotComplete"
		],
		"directDepositInformation":{
			"accountNumber":"**6224",
			"routingNumber":"096227418"
		},
		"accountHolders":[
			{
			"user":{
				"firstName":"***********kC",
				"lastName":"***********um",
				"dobStatus":"matched",
				"last4Identity":"5568",
				"identityType":"ssn",
				"userIdentifier":"79113a87-9db0-41fa-a7c4-7ad4a6507607",
				"peerTransferAcceptPreference":"manual",
				"isPrimaryAccountHolder":true,
				"status":"active",
				"kycStateData":{
					"ofacStatus":"passed",
					"kycStatus":"passed",
					"kycPendingGate":"healthy"
				}
			},
		"accountHolderIdentifier":"88d4fe6d-246f-4a3b-92eb-edcfe9fc80e8"
		}],
		"termsAcceptances":[
			{
			 "termsIdentifier":"privPlcy",
			 "termsAcceptanceDateTime":"2021-07-14T09:18:48.177Z",
			 "termsAcceptanceFlag":false
			},
			{
			 "termsIdentifier":"daa",
			 "termsAcceptanceDateTime":"2021-07-14T09:18:48.177Z",
			 "termsAcceptanceFlag":true
			},
			{
			 "termsIdentifier":"eca",
			 "termsAcceptanceDateTime":"2021-07-14T09:18:48.177Z",
			 "termsAcceptanceFlag":true
			}
		],
		"accountCycleDay":0
	}
}
RequestMessageToPartner:{
	"accounts":[{
	"accountIdentifier":"6d12d946-be7f-4040-a1dc-9afb34d9e82a",
	"events":[{
		"eventIdentifier":"7f9ebd65-fa42-4d8f-b583-eb8aa0d6c95d",
		"eventType":"accountUpdated",
		"eventDateTime":"2021-07-14T16:20:53.397Z",
		"account":{
		"accountIdentifier":"6d12d946-be7f-4040-a1dc-9afb34d9e82a",
		"status":"pending",
		"accountStatusChangedDateTime":"2021-07-14T16:18:52.570Z",
		"statusReasons":[
			"registrationNotComplete"
		],
		"accountCycleDay":0,
		"accountHolders":[{
		"user":{
			"userIdentifier":"79113a90-9db0-41fa-a7c4-7ad4a6507607",
			"isPrimaryAccountHolder":true,
			"status":"active",
			"kycStateData":{
				"ofacStatus":"passed",
				"kycStatus":"passed",
				"kycPendingGate":"healthy"
			}}
		}]}
	}]
}]}

ResponseHttpStatusCode:201

ResponseMessage:{
	"clientResponse":"Accepted request for eventIdentifier: 7f9ebd65-fa42-4d8f-b583-eb8aa0d6c95d"
}
SkipPublish:false
TimeoutOccurred:false
X-GD-RequestId:ca94555c-9ea3-420f-8c08-3c536f49bb21
level:INFO
logger:PublishNotificationService
machineName:QA-PN-40D06
message:Publish notification post sent successfully.
threadId:6
time":"2021-07-14 09":"20":53.4542
}

Know Your Business (KYB) Flow during Enrollment

Partners who are configured for KYB flow, can enroll customers who own small businesses.

Please refer to the KYB page for more information.

Enrollments API Endpoints

📘

The following endpoints are used for the enrollment process. For technical reference of all Enrollments API endpoints, please refer to the API Reference section.

Enroll User into a Product and Create the Account and Card

This API enrolls a user into a product and creates the account and card. It is also used to upgrade a GPR (General Purpose Reloadable) account to a DDA (Direct Deposit Account) when the upgradeFlag is set to true.

API Call Structure

POST /programs/{programCode}/enrollments

Upgrade Response Error Codes

KYC Verification

Note: To perform KYC verification checks on users, the userData object must have the following fields completed.

Note: For more information, refer to Sample Unencrypted User Data.

KYC Verification Response Codes

📘

More information about KYC can be found on the KYC Page.

Currency Response Codes

User Data Response Codes

Terms Acceptance Response Codes

Obtain Enrollment Details

This API obtains enrollment details.

Note: During the GPR > DDA upgrade process, the response will include the UpgradeKycStateData property. If the account is already a DDA account, the response will not include the UpgradeKycStateData property.

Structure of API Call:

GET /programs/{programCode}/enrollments/accounts/{accountIdentifier}

Create User, Account, Payment Instrument

Structure of API Call:

POST /programs/{programCode}/enrollments

Note: If POST /enrollments is called with a valid request and enrollment fails during processing, the request will be automatically completed if the customer clears OFAC.

Request Parameters

Sample Unencrypted User Data

To execute Know Your Customer (KYC) successfully, the profileData, identifyingData, email, and phoneNumbers fields are required.

Response Parameters

Bill Cycle Date (BCD)

Active accounts will return a bill cycle date when POST /enrollments is called.

• The bill cycle date will be returned as an accountCycleDay, which represents the first day of the statement cycle for an account.
• The accountCycleDay can be 1-28.

{
  "account":{
    "accountIdentifier":"58787933-9076-4f51-a217-8a2187033625",
    "accountReferenceNumber":"ACCP0000000",
    "status":"normal",
    "accountStatusChangedDateTime":"2020-04-02T16:46:20.13Z",
    "statusReasons":["healthy"],
    "directDepositInformation":{
      "accountNumber":"15**********00",
      "routingNumber":"******100"
    },
    "purses":[
      {
        "purseIdentifier":"d940751b-8208-4d18-9240-58e6ab8b6cfb",
        "purseType":"primary",
        "availableBalance":0.0,
        "ledgerBalance":0.0,
        "availableBalanceAsOfDateTime":"2020-04-02T14:46:19Z",
        "ledgerBalanceAsOfDateTime":"2020-04-02T14:46:19Z",
        "isHidden":false,
        "status":"active"
      }
    ],
    "accountHolders":[
      {
        "paymentInstruments":[
          {
            "encryptedPrivatePaymentInstrumentData":{
              "version":"EC_v1",
              "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEVMFTbdmLF5fffpAhSc99HgLvn7xOqbhMjXnTxCFOt5L1VomD3FHtFY7F128AuUDXEIDBLH0YwU42qzizyJBAqQ==",
              "publicKeyHash":"PiRV5ko8JYGxAtcNb9WV4aVg7aXIp8EsstmeUqqWzT8=",
              "data":"UhYFhBTSX6w/0LOTDfa5O0c+hy9exHIjrqJ6uNvi+Gf4kaut81Tvb9vdVTaFn8BpfGMscEx5QNzvxrh377PGD96bdpfhM0eJL9KjqmY8Rtv6/xC5ZqyzF92uYBkkZbFZ"
            },
            "paymentInstrumentIdentifier":"df2a43c1-2469-4cd4-b468-d1b51cac0059",
            "paymentInstrumentType":"virtual",
            "status":"activated",
            "isPinSet":true,
            "last4Pan":"0000",
            "activatedDateTime":"2020-04-02T16:46:19Z",
            "issuedDateTime":"2020-04-02T16:46:19Z",
            "isPrivateDataViewable":true
          },
          {
            "encryptedPrivatePaymentInstrumentData":{
              "version":"EC_v1",
              "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEn+LEayHfNDYMokvYnD7SsAL4dzyfbZ19NZCHsIaqd07KDIkpZh7T4W3QilkYQDOqRJvAKRiINuh5KcPeDoxLSA==",
              "publicKeyHash":"PiRV5ko8JYGxAtcNb9WV4aVg7aXIp8EsstmeUqqWzT8=",
              "data":"XbyTkaysIEcIQnppkDq8W8namlB9J96UvRVyt1TYYUpUn1OY7wrtFpC1HPRibPQZup8NfWp/7l5sq8ker1rvZqBo8Mw8QQIDH3QsXKj9kr7SwZY2"
            },
            "paymentInstrumentIdentifier":"2adba9d0-4f30-43f8-aa20-0a286ba4bd13",
            "paymentInstrumentType":"emv",
            "status":"notActivated",
            "isPinSet":true,
            "last4Pan":"0000",
            "issuedDateTime":"2020-04-02T16:46:20Z",
            "isPrivateDataViewable":false
          }
        ],
        "user":{
          "userIdentifier":"079c8dde-71c1-4ac7-b93a-cb187eb44ae2",
          "peerTransferAcceptPreference":"manual",
          "status":"active",
          "isPrimaryAccountHolder":true,
          "kycStateData":{
            "ofacStatus":"passed",
            "kycStatus":"passed",
            "kycPendingGate":"healthy"
          }
        }
      }
    ],
    "accountCycleDay":2 – The first day of the statement cycle for an account.
  },
  "responseDetails":[
    {
      "code":0,
      "subCode":0,
      "description":"Success",
      "url":"http://tbd"
    }
  ]" "
}

Idempotent Retry and Billing Cycle Dates

Note: Accounts must have a billing cycle date to have a normal account status.

• Typically, the Billing Cycle Date (BCD) returned as an accountcycleday is automatically created at the time of enrollment, but in conditions where it cannot be created, the account will be left in a pending state.

Partners should make an idempotent call in these situations. The idempotent call for POST /enrollments will populate the BCD when the idempotent retry process is completed. The account status will also be set to normal.

Example: Using a POST /enrollments idempotent call to populate the BCD.

1st POST /enrollments call fails, and the BCD is null. The paymentIdentifier and the payment instruments are not created. The account is in a pending/registration not complete state.

Sample Request Body:-
{
  "user":
  {
    "encryptedUserData":
	{
      "version":"EC_v1",
      "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEF+93ZmoH5cG5W30Lf8MIMeoOAd2BZJ1sLWUBsKrGqMT/fnTjN1MwqLFBiZwhICEX95uxdyuPuKgy05FObHm6hw==",
      "publicKeyHash":"kMhnzB6afrTdRvVFjhOQ5kjUTrPKvkygSCZQXQzNHYo=",      "data":"dJBb3AFMxUbyet1NDAkHVEKhFCFtsoLoQ+muuPBQnCfJjY4jfEBTjUcRVSKIjDgrUsgbwUv2p5le9bGWVFdLArny9SAPcBOtqzrawT+vk0UQApskdhAdrTZsp7Ecs3VOHZiLHUki/Rd5U6qH4cp2SLAskJRCmn7WmpK/C3++hBZZAVallw+htp/EUPUjl4hrowSoMzk/pZHlI9XWqm1kNGwEQG7GYuxCm7G86ff9Cnz+zOAKSN+nJD3rxXWSPV8CplkvoF7c4yWXAxB5Zjy5Ce7fqrknMTV6Na3TqZjxbF73YB45fUEETHPyaD5xCAK7fDztW16lRsKX2tSADxlajVzM6eeXoaksK2+IvXktJmEieqoUGLoDYOsWT9jJfwAOSvswZV+4t5WyOWJYugBFqI+hX2v/+XjgY7POwWXew5zOa7rTQm54Vr1DOoP3I8U0zmB/zys5CrlSV/FYdwlIZxAub2a8X2jUrG5yjPyRkmO0Bxjv0imj8VcCQR0wKD1CFDyzSLqUhMqqwTIcV5uPo0szdZQcwca2ODUHPzco7DUiVNTJA74RWEllaV5QkgFf7GW/sTUnBG1In4WXAxjJRXaydWsLcCYH/ZSiqWHGmXrHNpPjr6vXCNRxi5/X5wPgOZ8lFmoyVrafvAmQXqSzU4Kdg7TPEaQ8EuEiOH+M6Gp9UQNrtD0OKvHuZN3aAlBwH2H9cuLH0dniZbaemcGjJlcRH1nz"
    },
    "termsAcceptances":
	[{
        "termsIdentifier":"termsAndConditions",
        "termsAcceptanceDateTime":"2020-08-22T00:17:07.318Z"
    }]
  },
  "account":
  {
    "productCode":"50400",
    "productMaterialType":"pvc",
    "currency":"USD",
    "termsAcceptances":
	[
      {
        "termsIdentifier":"termsAndConditions",
        "termsAcceptanceDateTime":"2020-08-22T00:17:07.318Z",
        "termsAcceptanceFlag":"true"
      },
      {
        "termsIdentifier":"privPlcy",
        "termsAcceptanceDateTime":"2020-08-22T00:17:07.318Z",
        "termsAcceptanceFlag":"false"
      }
    ]
  },
  "requestPhysicalCardFlag":true,
  "executeKycFlag":true
}

Sample Response:-
{
  "account":{    
  },
  "responseDetails":[
    {
      "code":503,
      "subCode":0,
      "description":"Fail",
      "url":"http://tbd"
    }
  ]
}

The 2nd POST /enrollments call that is Idempotent puts the account into a normal healthy state once the idempotent retry process is completed. The BCD is populated and the paymentIdentifier and payment instruments are created. An Account Updated Webhook is sent.

Sample Request Body:-
{
  "user":{
    "encryptedUserData":{
      "version":"EC_v1",
      "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEF+93ZmoH5cG5W30Lf8MIMeoOAd2BZJ1sLWUBsKrGqMT/fnTjN1MwqLFBiZwhICEX95uxdyuPuKgy05FObHm6hw==",
      "publicKeyHash":"kMhnzB6afrTdRvVFjhOQ5kjUTrPKvkygSCZQXQzNHYo=",      "data":"dJBb3AFMxUbyet1NDAkHVEKhFCFtsoLoQ+muuPBQnCfJjY4jfEBTjUcRVSKIjDgrUsgbwUv2p5le9bGWVFdLArny9SAPcBOtqzrawT+vk0UQApskdhAdrTZsp7Ecs3VOHZiLHUki/Rd5U6qH4cp2SLAskJRCmn7WmpK/C3++hBZZAVallw+htp/EUPUjl4hrowSoMzk/pZHlI9XWqm1kNGwEQG7GYuxCm7G86ff9Cnz+zOAKSN+nJD3rxXWSPV8CplkvoF7c4yWXAxB5Zjy5Ce7fqrknMTV6Na3TqZjxbF73YB45fUEETHPyaD5xCAK7fDztW16lRsKX2tSADxlajVzM6eeXoaksK2+IvXktJmEieqoUGLoDYOsWT9jJfwAOSvswZV+4t5WyOWJYugBFqI+hX2v/+XjgY7POwWXew5zOa7rTQm54Vr1DOoP3I8U0zmB/zys5CrlSV/FYdwlIZxAub2a8X2jUrG5yjPyRkmO0Bxjv0imj8VcCQR0wKD1CFDyzSLqUhMqqwTIcV5uPo0szdZQcwca2ODUHPzco7DUiVNTJA74RWEllaV5QkgFf7GW/sTUnBG1In4WXAxjJRXaydWsLcCYH/ZSiqWHGmXrHNpPjr6vXCNRxi5/X5wPgOZ8lFmoyVrafvAmQXqSzU4Kdg7TPEaQ8EuEiOH+M6Gp9UQNrtD0OKvHuZN3aAlBwH2H9cuLH0dniZbaemcGjJlcRH1nz"
    },
    "termsAcceptances":[
      {
        "termsIdentifier":"termsAndConditions",
        "termsAcceptanceDateTime":"2020-08-22T00:17:07.318Z"
      }
    ]
  },
  "account":{
    "productCode":"50400",
    "productMaterialType":"pvc",
    "currency":"USD",
    "termsAcceptances":[
      {
        "termsIdentifier":"termsAndConditions",
        "termsAcceptanceDateTime":"2020-08-22T00:17:07.318Z",
        "termsAcceptanceFlag":"true"
      },
      {
        "termsIdentifier":"privPlcy",
        "termsAcceptanceDateTime":"2020-08-22T00:17:07.318Z",
        "termsAcceptanceFlag":"false"
      }
    ],
    "fraudData":{
      "key":"string",
      "key":{
        "prop1":"val1",
        "prop2":"val2"
      }
    }
  },
  "requestPhysicalCardFlag":true,
  "encryptedPin":{
    "version":"EC_v1",
    "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmx9T4EJNQHNWHRnf+U48rFWlrUwhXyivdkZrUl2rD4wVVJInEs8MRP7ISABTKEqh8NDdWAsc8hsKtGtxHgYA4A==",
    "publicKeyHash":"kMhnzB6afrTdRvVFjhOQ5kjUTrPKvkygSCZQXQzNHYo=",
    "data":"n8V1k4aSNNqsZWebsq2BKqkWGgFbf2lmS7mklbJo"
  },
  "executeKycFlag":"true"

Sample Response:-
{
    "account":{
      "accountIdentifier":"90edb081-299c-44f1-9a59-f8ddf5ba6155",
      "accountReferenceNumber":"UNP5639733",
      "status":"normal",
      "accountStatusChangedDateTime":"2020-08-22T00:20:19.560Z",
      "statusReasons":[
        "healthy"
      ],
      "directDepositInformation":{
        "accountNumber":"10157253856458",
        "routingNumber":"096017418"
      },
      "purses":[
        {
          "purseIdentifier":"a4b2e6e4-0e80-4e7a-91ca-7ede3913b2ed",
          "purseType":"primary",
          "availableBalance":0.0000,
          "ledgerBalance":0.0000,
          "availableBalanceAsOfDateTime":"2020-08-21T22:20:16Z",
          "ledgerBalanceAsOfDateTime":"2020-08-21T22:20:16Z",
          "isHidden":false,
          "status":"active"
        }
      ],
      "accountHolders":[
        {
          "paymentInstruments":[
            {
              "paymentIdentifier":"6a69336f-78df-40ec-998b-1a0cc4ea1d1b",
              "paymentInstrumentIdentifier":"30f5874d-1e33-4ea4-94fd-4ed47185c14e",
              "paymentInstrumentType":"virtual",
              "status":"activated",
              "isPinSet":false,
              "last4Pan":"7186",
              "activatedDateTime”: "2020-08-22T00":"20":16Z",             
			  "issuedDateTime": "2020-08-22T00":"20":16Z",             
			  "isPrivateDataViewable": false          
			  }],       
			  "user": 
			  {          
				  "firstName": "ZdzYPOIT",          
				  "lastName": "GIiQqxEo",          
				  "dobStatus": "matched",          
				  "last4Identity": "2353",          
				  "identityType": "ssn",          
				  "userIdentifier": "41545272-7f24-4703-bab5-5ae5bae2a303",          
				  "status": "active",          
				  "isPrimaryAccountHolder": true,          
				  "kycStateData": 
				  {             
					  "ofacStatus": "passed",             
					  "kycStatus": "passed",             
					  "kycPendingGate": "healthy"          
				  }       
			  }    
		}], 
		accountCycleDay": 21
   },
   "responseDetails":[
	{
	  "code":0,
	  "subCode":0,
	  "description":"Success",
	  "url":"http://tbd"
	}]

Active Consumer Account Limits

An account is considered active when it has been activated and either has an account status of normal or a kycPendingGate (aka: Cure) with a value other than none. There is a limit to the number of active accounts allowed per social security number for Consumer Accounts.

When the Active Account Limit rule is encountered during a POST /enrollments call and the date of births match, the most recent active enrollment details will be returned. If the date of births do not match, only the response details will be returned.

Social Security Number (SSN) Limits

• Up to 1 active accounts with the same SSN per program is allowed
• Up to 3 lifetime accounts with the same SSN per program are allowed

Phone Limits - Default or Primary Phone Number on Account

The following phone limits will be implemented (during enrollment) only for the phone number that is listed as the default for the account:

• Up to 2 active accounts with the same phone number per program are allowed
• Up to 10 lifetime accounts with the same phone number per program are allowed

Note: Updates requested for phone numbers that exceed the current phone limits will be declined.

ITIN Limits

• Up to 1 active accounts with the same ITIN per program are allowed
• Up to 3 lifetime accounts with the same ITIN per program are allowed

Refer to Active Small Business Account Limits for details about small business account limit thresholds.

Response Codes

Sample Response – Date of Births Match

Sample Response – Date of Births Match:-
{
  "account":{
    "accountIdentifier":"8e1bd112-661b-473f-acad-4ed6181c4c21",
    "accountReferenceNumber":"OXF2701925",
    "status":"normal",
    "statusReasons":[
      "healthy"
    ],
    "directDepositInformation":{
      "accountNumber":"101034163709758",
      "routingNumber":"096017418"
    },
    "purses":[
      {
        "purseIdentifier":"252d1bc1-754f-46e8-95df-aade9bcf25c3",
        "         ""purseType":"primary",
        "availableBalance":0.0,
        "ledgerBalance":0.0,
        "availableBalanceAsOfDateTime":"2018-10-18T21:10:32Z",
        "ledgerBalanceAsOfDateTime":"2018-10-18T21:10:32Z"
      }
    ],
    "accountHolders":[
      {
        "user":{
          "userIdentifier":"1b19ffb1-e869-4c83-8eaa-4af6e5e867c2",
          "status":"active",
          "isPrimaryAccountHolder":true,
          "kycStateData":{
            "ofacStatus":"passed",
            "kycStatus":"passed",
            "kycPendingGate":"healthy"
          }
        },
        "paymentInstruments":[
          {
            "paymentInstrumentIdentifier":"1e5ea745-d3ac-41e6-a703-29c9974c9e49",
            "paymentInstrumentType":"virtual",
            "status":"activated",
            "isPinSet":false,
            "last4Pan":"3782",
            "activatedDateTime":"2018-10-18T23:10:32Z",
            "issuedDateTime":"2018-10-18T23:10:32Z",
            "isPrivateDataViewable":"false"
          }
        ]
      }
    ]
  },
  "responseDetails":[
    {
      "code":2,
      "subCode":60,
      "description":"Number of Active Accounts Exceeded.",
      "url":"http://tbd"
    }
  ]
}

Sample Response – Date of Births do not Match:-
{
  "responseDetails":[
    {
      "code":2,
      "subCode":60,
      "description":"Number of Active Accounts Exceeded.",
      "url":"http://tbd"
    }
  ]
}

Business Rule Response Sub-Codes

Refer to Business Rule Response Sub-Codes for details.

Update Business Profile

This endpoint allows Partners to update the business data associated with a business account.

Structure of API Call:

PUT program/programcode/accounts/accountIdentifier/businessProfile

This endpoint can be used with the following businessTypes:

• ConsumerProfileType
• Individual
• soleProp
• llc
• corp
• partnership
• nonprofit
• SingleLLC
• ProCorp

📘

If the businessName on the account is updated, then the next card replacement request will use the updated businessName.

Response Codes

Update Consumer Profile

This endpoint updates an enrollment account's consumer profile.

Structure of API Call:

PUT /programs/{programCode}/enrollments/account/{accountIdentifier}

Obtain Business Profile

Structure of API Call:

GET programs/{programCode}/accounts/{accountIdentifier}/businessProfile

This endpoint allows the retrieval of business data associated with a business account.

Response Codes

Obtain Business Lookup Data

This API obtains business profile lookup data.

Structure of API Call:

GET /programs​/{programCode}​/businessProfile/application/lookups

Save Business Address

This API saves an address for a business profile.

Structure of API Call:

PUT /programs​/{programCode}​/businessProfile/application/address

Create Business Owner

This API creates a profile for a business owner.

Structure of API Call:

PUT /programs​/{programCode}​/accounts/{accountIdentifier}/businessProfile/application/owner

Update Business Owner

This API creates a profile for a business owner.

Structure of API Call:

PUT /programs​/{programCode}​/accounts/{accountIdentifier}/businessProfile/application/owner

Delete Business Owner

This API deletes a business profile for a business owner.

Structure of API Call:

DELETE /programs​/{programCode}​/accounts/{accountIdentifier}/businessProfile/application/owner/{ownerIdentifier}

Save Business Information

This API saves business information.

Structure of API Call:

PUT /programs​/{programCode}​/accounts/{accountIdentifier}/businessProfile/application/info

Obtain Business Metadata

This API obtain business metadata.

Structure of API Call:

GET /programs​/{programCode}​/accounts/{accountIdentifier}/businessProfile/application/

Save Business Application

This API saves a business application.

Structure of API Call:

POST /programs​/{programCode}​/accounts/{accountIdentifier}/businessProfile/application

Accepting Matricula Consular Identification

This feature allows partners to use Matricula Consular IDs to enroll Mexican Citizens, living in the US, who may not have a Social Security Number (SSN) or an Individual Taxpayer Identification Number (ITIN).

Note: The Matricula Consular ID cannot be used along with an SSN or ssnSuffix (last4ssn). They are mutually exclusive, so if used together, the following error will be returned :

• HTTP Status Code: 400
• Code: 630
• subCode: 0
• Description: Cannot pass both matriculaId and SSN or last4ssn

To enroll a customer using a Matricula Consular ID:

• Call POST /programs/{programCode}/enrollments and include the onboardingID received from the POST /kycGates/scanCapture call you completed
• Note: You must call POST /kycGates/scanCapture before calling POST /enrollments

Sample Unencrypted User Data

{
  "profileData":{
    "firstName":"Alice",
    "middleName":"Mary",
    "lastName":"Jones",
    "addresses":[
      {
        "addressLine1":"215 Main St.",
        "addressLine2":"Suite 200",
        "city":"Pasadena",
        "state":"CA",
        "zipCode":"91107",
        "countryCode":"USA",
        "type":"home",
        "isDefault":true
      }
    ]
  },
  "identifyingData":{
    "dateOfBirth":"1990-01-20",
    "onboardingID":"string"
  },
  "email":{}    
}

Add Taxpayer ID to Customer Account Originally Enrolled Using Mexican Matricula ID

This endpoint allows an Individual Taxpayer Identification Number (ITIN) to be added to a customer’s account that originally enrolled using a Mexican Matricula ID only. This is primarily for U.S. tax purposes.

Structure of API Call:

POST /accounts/{accountIdentifier}/users/{userIdentifier}/identity

How it Works

If a customer successfully enrolls using a Mexican Matricula ID only and they would like to add an ITIN to their account, submit a request containing the ITIN to POST /accounts/{accountIdentifier}/users/{userIdentifier}/identity.

ITIN Limits

• Up to 1 active account with the same ITIN per consumer program is allowed
• Up to 3 lifetime accounts with the same ITIN per consumer program are allowed

Response Codes

Diacritic Character Substitution

Customers can use Spanish characters to properly spell their name during enrollment and replace card requests.

How it Works

Partner will allow identified Spanish characters to be used in the first and last names of their customers.

During enrollment, when the customer enters the allowed Spanish characters for their first and last name, the name embossed onto the card will be substituted with identified replacement characters, by the system.

Refer to the Valid Characters for Names, Cities, and Addresses table for details.

Retrieve Account and Payment Instrument Information

This endpoint retrieves information regarding an account and payment instrument.

API Call Structure

GET /programs/{programCode}/enrollments/accounts/{accountIdentifier}

Response Parameters

• account – Value that returns the user’s account information.
• accountIdentifier – String value that returns a unique identifier for the account.
• accountReferenceNumber – String value that is a friendly unique identifier of an account that is safe for sharing between intra and intercompany staff.
• productCode – Unique identifier of a product within a program.
• currency – Alpha-3 ISO Currency Code.
• Status – String value that returns the status of an account.
• statusReasons – String value that returns the reason for the status of an account.
• accountStatusChangedDateTime – Date and time of the account status change in UTC format.
• directDepositInformation – Value that identifies the account that will be used for direct deposits, along with the account number and routing number.
• accountNumber – Value Returns the account number of the account being used for direct deposit.
• routingNumber – String value Returns the routing number of the account being used for direct deposit.
• purses – A balance holding object that returns the following information about the primary purse (used for general spending activities).
• purseIdentifier – Value that is read only and set to true. It is a unique identifier of a purse within an account.
• purseType – Value used to indicate the purpose of the purse.
• availableBalance – Number value representing the amount of funds available for use. Pending transactions are included.
• ledgerBalance – Number value that represents the balance of the account based on all activities that have been posted to the associated ledger.
• availableBalanceAsOfDateTime – The date/time (UTC) that the available balance is reflective of.
• ledgerBalanceAsOfDateTime – The date/time (UTC) that the ledger balance is reflective of.
• isHidden – True or False
• status – Purse status
• accountHolders – Value that contains detailed information about the account holders.
• paymentInstruments – Used by an accountholder to conduct transactions and make payments. A payment instrument will typically be a physical or virtual card. Contactless EMV cards are also available. Contact your Green Dot Representative to request configuration.
• paymentIdentifier – Unique identifier for a payment instrument if a payment instrument was created.
• paymentInstrumentIdentifier – Unique identifier of a payment instrument for an account.
• paymentInstrumentType – Indicates the type of payment instrument (card) being used. See your Green Dot Representative to request configuration for contactless EMV.
• status – Payment Instrument Status
• isPinSet – Indicates if the ATM pin has been set for this card.
• last4Pan – Last 4 digits of the card number
• issuedDateTime – The date/time (UTC) that the card was requested by the user.
• isPrivateDataViewable – Indicates if privatePaymentInstrumentData can be returned and viewed.
  Note: If this field is true, then the privatePaymentInstrumentData field will be viewable. This field will not be returned for non-virtual cards.
  Note: Partners who are not configured for encryption will have encrypted data, such as encryptedPrivatePaymentInstrumentData, omitted from the data objects in their responses.
• user – Field Returns information about the user of an account.
• firstName – First name of an account holder.
• lastName – Last name of an account holder.
• dobStatus – Can be:
• matched - If isDOBMatched is true and isDOBVerified is false, then matched is used
• notMatched - If isDOBMatched is false and isDOBVerified is false, then notMatched is used
• Verified - If isDOBVerified is true then verified is used
• last4Identity – Last 4 digits of the account holder’s social security number.
• identityType – Type of identity being used for the account holder (i.e. ssn).
• userIdentifier – Unique identifier of a user within a program.
• peerTransferAcceptPreference – Value can be manual or automatic. This property is optional and only applies to Partners using the P2P capabilities of the platform. The default value is manual and has no impact to any service other than P2P.
  Note: If this value is not provided then it will remain manual.
• isPrimaryAccountHolder – Identifies the primary accountHolder.
• status – Current status of the user. It is set to active, which means that the user is fully active.
• kycStateData – Current OFAC and KYC status of the user.
• ofacStatus – Result of most recent OFAC check on the user of the account (pending, passed, or failed).
• kycStatus – Result of most recent KYC check on the user of the account (pending, passed, or failed).
• kycPendingGate – kycGate that the user must pass through to successfully complete KYC (none, kyc2, idv, healthy, manual).
• accountHolderIdentifier –
• termsAcceptances – Represents the acceptance of daa by a user.
• termsIdentifier – Unique identifier for the daa that was accepted.
  Note: termsAcceptanceFlag must be set to true.
• termsAcceptanceDateTime – Optional. Date/time in UTC that the daa was accepted.
  Note: If not provided, will default to the current date/time.
• termsAcceptanceFlag – Indicates whether the terms were accepted by the user. Required for opt in/out agreements.
• accountCycleDay – The bill cycle date will be returned as an accountCycleDay, which represents the first day of the statement cycle for an account. The accountCycleDay can be 1-28.
• responseDetails – Includeds code, subcode, description, URL. See Response Details

Sample Response Bill Cycle Date (BCD)

Active accounts will return a bill cycle date when GET /enrollments is called.

The bill cycle date will be returned as an “accountCycleDay”, which represents the first day of the statement cycle for an account.

The accountCycleDay can be 1-28.

{
  "account":{
    "accountIdentifier":"cab629b7-9b3e-4a31-9ada-a9fa4023eb34",
    "accountReferenceNumber":"NRT0000000",
    "productCode":"00000",
    "currency":"USD",
    "status":"restricted",
    "statusReasons":[
      "potentialFraud"
    ],
    "accountStatusChangedDateTime":"2020-04-02T16:49:21.4Z",
    "directDepositInformation":{
      "accountNumber":"10**********00",
      "routingNumber":"******000"
    },
    "purses":[
      {
        "purseIdentifier":"c0bcab94-ba24-4fc7-a65a-eb914ac65611",
        "purseType":"primary",
        "availableBalance":50.0,
        "ledgerBalance":50.0,
        "availableBalanceAsOfDateTime":"2020-04-02T14:49:06Z",
        "ledgerBalanceAsOfDateTime":"2020-04-02T14:49:06Z",
        "isHidden":false,
        "status":"active"
      }
    ],
    "accountHolders":[
      {
        "paymentInstruments":[
          {
            "paymentInstrumentIdentifier":"beb01ec5-d2a3-4db6-b098-a5974c7c31bd",
            "paymentInstrumentType":"emv",
            "status":"notActivated",
            "isPinSet":true,
            "last4Pan":"7672",
            "issuedDateTime":"2020-04-02T16:49:06Z",
            "isPrivateDataViewable":false
          }
        ],
        "user":{
          "userIdentifier":"39250690-2b55-43da-8b7b-24567b1a1a1c",
          "peerTransferAcceptPreference":"manual",
          "status":"active",
          "isPrimaryAccountHolder":true,
          "kycStateData":{
            "ofacStatus":"passed",
            "kycStatus":"passed",
            "kycPendingGate":"none"
          }
        }
      }
    ],
    "termsAcceptances":[
      {
        "termsIdentifier":"privPlcy",
        "termsAcceptanceDateTime":"2020-04-02T16:49:04.483Z",
        "termsAcceptanceFlag":false
      },
      {
        "termsIdentifier":"daa",
        "termsAcceptanceDateTime":"2020-04-02T16:49:04.483Z",
        "termsAcceptanceFlag":true
      },
      {
        "termsIdentifier":"eca",
        "termsAcceptanceDateTime":"2020-04-02T16:49:04.483Z",
        "termsAcceptanceFlag":true
      }
    ],
    "accountCycleDay":2 -- The first day of the statement cycle for an account.
  },
  "responseDetails":[
    {
      "code":0,
      "subCode":0,
      "description":"Success",
      "url":"http://tbd"
    }
  ]
}

Unblock Card Retry Process

If a fraud block is removed from an account and the payment instrument remains blocked, the request to unblock the payment instrument will be retried up to 3 times.

Note: All three retries will be completed in 15 minutes.

Retry Process

1. A BaaS account is locked due to suspicion of fraud.
2. A request to update the account and payment instrument to a healthy and normal state is submitted.
3. The account is updated to healthy and normal, but the payment instrument remains blocked.
4. The request to unblock the payment instrument is automatically retried up to 3 times.
5. The retry process is successful and the card is unblocked OR the retry process is unsuccessful and the kycPendingGate is set to manual with the statusReason underReview.
6. If the retry process is unsuccessful, the payment instrument will need to be unblocked by the Green Dot Care team.

Sample Response – GET Enrollment After Unsuccessful Retry Process

{
  "responseHeader":{
    "responseId":"06a1cc33-48ce-451e-afc0-fb2ba578ea38",
    "statusCode":0,
    "subStatusCode":0,
    "message":"Success"
  },
  "account":{
    "accountIdentifier":"cb9a242c-5dc2-4810-aeb2-d20a463273f9",
    "accountReferenceNumber":"CCC6782110",
    "productCode":"00000",
    "productName":"Super Product",
    "currency":"USD",
    "status":"locked",
    "accountStatusChangedDateTime":"2020-12-29T23:04:11.030Z",
    "statusReasons":[
      "underReview"
    ],
    "directDepositInformation":{
      "accountNumber":"000071784780522",
      "routingNumber":"000017410"
    },
    "purses":[
      {
        "purseIdentifier":"b199d612-80ef-4c46-9544-442578f8fd5e",
        "purseType":"primary",
        "availableBalance":0.0000,
        "ledgerBalance":0.0000,
        "availableBalanceAsOfDateTime":"2020-12-29T14:28:09.34",
        "ledgerBalanceAsOfDateTime":"2020-12-29T14:28:09.34",
        "isHidden":false,
        "status":"active"
      }
    ],
    "accountHolders":[
      {
        "user":{
          "firstName":"John",
          "lastName":"Doe",
          "dobStatus":"matched",
          "last4Identity":"1111",
          "identityType":"ssn",
          "userIdentifier":"b3b4c380-1015-41a7-89a8-6656da521009",
          "peerTransferAcceptPreference":"manual",
          "isPrimaryAccountHolder":true,
          "status":"active",
          "kycStateData":{
            "ofacStatus":"passed",
            "kycStatus":"passed",
            "kycPendingGate":"manual"
          }
        },
        "paymentInstruments":[
          {
            "paymentInstrumentIdentifier":"72a88759-ede1-4913-9758-5982713fbcd0",
            "paymentIdentifier":"886e8c65-5e52-427c-8677-013ac9d11233",
            "paymentInstrumentType":"virtual",
            "status":"blocked",
            "last4Pan":"2222",
            "issuedDateTime":"2020-12-29T22:28:09.333Z",
            "activatedDateTime":"2020-12-29T22:28:09.333Z",
            "isPinSet":false,
            "isPrivateDataViewable":"false",
            "customCardImageIdentifier":null,
            "paymentInstrumentStatusReasons":[
              "accountBlock"
            ]
          },
          {
            "paymentInstrumentIdentifier":"ac978783-d6eb-491f-9047-1c035cda5366",
            "paymentIdentifier":"886e8c65-5e52-427c-8677-013ac9d11233",
            "paymentInstrumentType":"emv",
            "status":"blocked",
            "last4Pan":"2222",
            "issuedDateTime":"2020-12-29T22:28:10.88Z",
            "isPinSet":false,
            "isPrivateDataViewable":"false",
            "customCardImageIdentifier":null,
            "paymentInstrumentStatusReasons":[
              "accountBlock"
            ]
          }
        ],
        "accountHolderIdentifier":"26122e71-fa5e-4de0-931b-3e7936a2a49f"
      }
    ],
    "termsAcceptances":[
      {
        "termsIdentifier":"daa",
        "termsAcceptanceDateTime":"2020-12-29T22:28:07.000Z",
        "termsAcceptanceFlag":true
      },
      {
        "termsIdentifier":"privPlcy",
        "termsAcceptanceDateTime":"2020-12-29T22:28:07.000Z",
        "termsAcceptanceFlag":true
      },
      {
        "termsIdentifier":"eca",
        "termsAcceptanceDateTime":"2020-12-29T22:28:07.000Z",
        "termsAcceptanceFlag":true
      }
    ],
    "accountCycleDay":1
  }
}

Get Activation Link

This API generates a custom URL to complete account activation after a customer has enrolled for a partner DDA account in store.

API Call Structure

GET /programs/{programCode}/enrollments/fsc/activationlink

Error Codes