Overview

For the Instant Transfer Service, there are two types of API flows, both of which are built based on Green Dot's Global Fund Transfer service:

• Standard Flow
• Single Phase Commit

The API Endpoints section below describes the APIs for both flows. For other related information, refer to these sections in that documentation:

• Crypto Primer for Banking as a Service
• OAuth 2.0 Authentication Workflow
• Valid/Invalid Character Constraints

Standard Flow Transfers

The standard Instant Transfer Model to move funds in near real-time to any eligible debit card involves the following three API calls:

• Create Customer Profile API (only once per recipient)
• Link Card API (only once when linking a new source account[i] or destination account, or when updating a destination account information)
• Transfer API (per transfer transaction, between individual accounts for A2A/P2P transfers, and for B2C disbursements, from the partner’s disbursing account to the recipient’s debit card account)

To accomplish this, the partner needs to call the referenced APIs in the API Reference page to complete each step while creating and linking a customer for the first time. After the customer profile is created, the Link Card API links multiple cards to that profile. Finally, after the linking is established, the partner can call the Transfer API to initiate a transfer.

Note:

• All responses are real-time and no Webhooks are generated in this model.
• Green Dot stores encrypted user and card data and uses tokens in the API calls.

A detailed discussion of these APIs is detailed below.

Instant Transfer Service API Endpoints

Create Customer Profile API

This API creates a recipient customer profile in the Green Dot instant transfer system. As part of that, the customer information goes through Green Dot's verification process configured for this partner before initiating any further API calls, ensuring all required information was passed and there are no OFAC or compliance problems with the recipient. The profile is needed before a customer links with an external card. The same customer profile can have multiple card accounts linked to it, and the target card accounts must always be linked to a target receiving customer.

Business Logic

• CustomerToken – If this field is left blank
  • When this field is mandatory, the partner must provide a unique value.
  • When this field is optional and the request contains a CustomerToken value, the same value is used. Otherwise, the Instant Transfer Service generates a GUID as the CustomerToken.
• Idempotent Check -- This check is based on the CustomerToken. If the request contains a value that already exists in the database, it returns the Record already exists error.
• DB Level Encryption -- This encryption is based on DateOfBirth.
• CustomerID in DB -- As per Green Dot standards, the CustomerID is a GUID that the Instant Transfer service generates.

API Call Structure

POST /programs/{programCode}/externalAccounts

Sample Request Body

{
  "salt": "eb6c967d-765a-4b18-9a6e-d4eb4df69efa",
  "customerToken": "eb6c967d-765a-4b18-9a6e-d4eb4df69efa",
  "encryptedData": {
    "version": "string",
    "ephemeralPublicKey": "string",
    "publicKeyHash": "string",
    "data": "string"
  }
}

Sample Encrypted Data (JSON)

{
  "firstName": "string",
  "lastName":"string",
  "middleName":"string",
  "email": "[email protected]",
  "phoneNumber": "1234567890",
  "dateOfBirth": "yyyy-mm-dd",
  "address":{ "addressLine1": "string",
  "addressLine2": "string",
  "city": "string",
  "state": "XX",
  "zipcode": "12345"
 },
}

Response Messages

Sample Response Body

{
  "customerToken": "eb6c967d-765a-4b18-9a6e-d4eb4df69efa",
  "status": "Pending",
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "string",
      "url": "string"
    }
  ]
}

Link Card API

After a recipient customer profile is created, the Link Card API creates links to target debit cards so they can be used as destinations for money movement transfers by either the person doing an A2A transfer or as the desired target account for a recipient of B2C disbursements.

Note: FundingType must = Card (debit cards)

Business Logic

This API includes the following processing logic:

• Idempotent Check -- If the account number is already linked with the given customer, the API returns the existing link information. Otherwise, it creates a new record.
  • Note: For an external card, an Idempotent check is performed based on Program Code, Customer Token, Account Number, Expiry Month, or Expiry Year.
  • For a GreenDot account, an Idempotent check is performed based on Program Code, Customer Token, or Account Token.
• Checking Eligibility
  • We verify that the target card BIN is eligible for a Fast Funds transfer, using the MasterCard send or Visa Direct gateways, depending on the partner configuration.
  • Note: Card will be eligible for fund transfer if receiving eligibility = true and funds availability = IMMEDIATE.
• Database Encryption Levels -- These include:
  • AccountNumber
  • ExpiryMonth
  • ExpiryYear
• Status
  • Link Profile status is InActive upon creating a link for the first time. After creating a successful first transfer, the link status changes to Active.
  • Validation can occur on the Expiry month and year while creating/updating the link information.

API Call Structure

POST /programs​/{programCode}​/externalAccounts​/customers/{customerToken}/linkCard

Sample Request Body

{
  "salt": "62ea6192-1b84-4107-864e-c96f494bbaff",
  "encryptedData": {
    "version": "EC_v1",
    "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAElQYeCVWEp3dm2AnNN6hfh7B6BOBCUSKFETY7Ls0Rc/JS7NvNqKuXeSwX3OiBd6TdhjGISa+VSdytefwjV0doyA==",
    "publicKeyHash": "t+rDLgzIWeXCY9qGd7VW6yypnJ3VqKUXVEYdhL/Q7Lo=",
    "data": "k28+pf0bUw4cR4aC0CgASxSVLZdOuNcuNjhDgatQz7C/c0D/rC/KDPMA+AVZscWf/mHs0HeII0tZxNmKkJERrQ/EfBq6AbViH3lfvwokhbtr16LVh4GcW6ahJWTvIbyKWQAs2MAkgu5yu8D6DCHoEhGy2QbnAaqa6jVf7Uldb6xlLq6jf4MwNDUYSsMH2rqnuv8xaj8vwoSwm3BvKyojuzMwHh5xRAE8fdELuLiZa7PVav2kW8GU0G0Fmgre37mIK/6znWIN01bfD2rYAs2tBABdf1lduD2uthEIR7kUR0xwV3aK6+ErS2sJthlGOKUOoYVBJzgyFrqsfFBXbuNayX1EKkhTV9+HFhH3TafKrPSzpsBQPNaJCo59vMWX9opatFIWmN1rWFTOty95DG4zJ1urXt9KhXw7GptM0K82sTzq81VyHL9xTXQZnHt/4Zwvo+JxF6ejRaWM9p0HYCMr5Ln6dpWWWBQFRoZ8aT+Qdot5dywDZS3uEKqSJbLbJRg+hXsmXqEYkhc3yLs1erw2mgo="
  }
}

Sample Encrypted Data (JSON)

{
   "firstName": "string",
   "lastName": "string",
   "middleName": "string",
   "nickName": "string",
   "accountNumber": "string",
   "expiryMonth": "string",
   "expiryYear": "string",
   "address": {
     "addressLine1": "string",
     "addressLine2": "string",
     "city": "string",
     "state": "string",
     "zipCode": "string"
   },
 }

Response Body

{
  "link": {
    "linkId": "00000000-0000-0000-0000-000000000000"
  },
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "Success",
      "url": "http://tbd"
    }
  ]
}

Delete Link Card API

When a customer no longer needs to be linked with a card, the Delete Link Card API will remove this link.

API Call Structure

DELETE programs/{programCode}/externalAccounts/customers/{CustomerToken}/linkCard/{linkId}

Response Messages

Transfers API

The Transfers API allows partners to enable their customers to move funds in near real-time from a Green Dot-issued account, a third party account, or a central disbursement payout account, and posting to an external account. We have two formats of the Transfer API for instant transfers to debit cards:

1. Green Dot BaaS Account partners
2. Green Dot Network or Money Movement only partners, please go to the related section below the Transfers API

API Call Structure

POST ​/programs​/{programCode}​/transfers

This endpoint is used to transfer funds from a program-funding source to a consumer account. The transferType value differentiates the transaction from a B2C, A2A, or P2P.

Note:

• For B2C Disbursements, Use transferType as DisbursementExternal
• For A2A Transfers transferring from a Green Dot BaaS account, use transferType as A2AOut

For B2C transfers, a configured account is required for the organization providing the funds. A static account ID is assigned, which the partner is expected to pass in the transfer request.

For A2A transfers from a Green Dot-issued account, the partner should pass the Green Dot Bank Account ID as the source identifier in the transfer request.

Sample Request Body

{
  "transferIdentifier": "d8ef71d0-bbfc-4d02-823c-821cf0cd2d89",
  "transferType": "A2AOut",
  "transferAuthorizationType": "execute",
  "partnerReferenceData": "",
  "initiator": "FED00D17-01EB-40E1-86F9-3E9457F6C82C",
  "transferRoute": {
    "transactionAmount": 20,
    "sourceTransferEndpoint": {
      "transferEndpointType": "ProgramFundingSource",
      "identifier": "FED00D17-01EB-40E1-86F9-3E9457F6C82C",
      "currency": "USD"
    },
    "targetTransferEndpoint": {
      "transferEndpointType": "card",
      "identifier": "32A7FC9A-9502-4650-ACB9-C939E1F34DAA",
      "currency": "USD"
    }
  },
"fraudData":       {
  "key": "string",
  "key": {"prop1":"test",
  "prop2":"BaaS"
  }
}
}

Request Body Field Definitions

Response Messages

Sample Response - A2A Out

{"transfer":{"transferIdentifier":"d8ef71d0-bbfc-4d02-823c-821cf0cd2d89","transferStatus":"completed"},"responseDetails":[{"code":0,"subCode":0,"description":"Success","url":"http://tbd"}]}

Response Parameters - A2AOut

Retry Process

How it Works

If POST/transfers are called when a timeout with a downstream service has occurred:

• The HTTP response to the partner is 202. This indicates the Disbursement request is correctly pending a retry.
• Initially, the transfer status is pending and the Retry service attempts to obtain the latest transaction status exponentially, thus increasing the maximum wait time between retries to 24 hours. Interval retry time is expressed in minutes. For example: 1,1,2,3,5,8,13 and so on.
• If the transaction has not completed successfully after 24 hours, the OCC team needs to update the status from pending to failed. An alert is triggered if there are more than 24 transactions in a pending status at any point of time.

Valid/Invalid Character Constraints

**Note: **Invalid characters are listed in bold. Anything outside the range is considered invalid, too.

Realtime API Response Codes (valid for any APIs on this page)

Money Movement Only (GDN) Partners

For a Green Dot Partner not using Green Dot’s BaaS account services, please use the call below to execute instant transfers to any debit card.

API Call Structure

POST /programs/{programCode}/transfers/gft

Sample Request Body

{
   "transferId":"0e38d18e-58b7-40cd-af2f-d173f1f82080",
   "transferType":"DisbursementExternal",
   "transferRoute":{
      "transactionAmount":2.9,
      "transactionDescription":"",
      "partnerReferenceData": "",
      "sourceTransferEndPoint":{
         "transferEndPointType":"programFundingSource",
         "identifier":"6C0536D0-AA9F-41B9-A74C-CCF01206F49E",
         "currency":"USD"
      },
      "targetTransferEndPoint":{
         "transferEndPointType":"card",
         "identifier":"014CF701-AA90-4F2A-AE09-22ED10C727D6",
         "currency":"USD"
      }
   }
}

Response Messages

Sample Response Body

{
   "transfer": {
      "transferId": "f0be739c-1408-4611-bec7-cb2d2704a349",
      "transferStatus": "Completed",
      "transferStatusReason": "TransferCompleted",
      "transactionDate": "2023-08-28T22:40:50.4859535-07:00",
      "currency": "USD",
      "transactionAmount": 2.9,
      "totalFeeAmount": 0.04,
      "totalTransactionNetAmount": 2.86,
      "feeDetails": [
         {
            "feeType": "CustomerFee",
            "feeAmount": 0.04
         }
      ],
      "processor": "MasterCardSend",
      "network": "MoneySend"
   },
   "responseDetails": [
      {
         "code": 0,
         "subCode": 0,
         "description": "Success"
      }
   ]
}

Single Phase Commit Transfers Endpoints

Single Commit API

URLs

<https://\{evn}.mul.secure2.greendot.com/enrollment/v1/api/flex/transfers/singlecommit> <https://pie.mul.secure2.greendot.com/enrollment/v1/api/flex/transfers/singlecommit> <https://prd.mul.secure2.greendot.com/enrollment/v1/api/flex/transfers/singlecommit>

Sample Request Header Parameters

Sample Request Body

{
   "transferIdentifier": "4771cde6-e8ee-4458-8020-c905d704064f",
   "transferType": "DisbursementExternal",
   "initiator": "e4b06240-b719-4c76-87c3-961f515e33eb",
   "transferdescription": "",
   "transferRoute": {
	   "transactionAmount": 5,
	   "sourceTransferEndpoint": {
		   "transferEndPointType": "programFundingSource",
		   "identifier": "8EADF071-657B-4CFA-9FBA-7B77D77C3BE8",
		   "currency": "USD"
	   },
	   "targetTransferEndpoint": {
		   "transferEndPointType": "singlePhaseFunding",
		   "identifier": "6b5eed71-48d3-46e0-be44-4342c6826b60",
		   "currency": "USD",
		   "cardData": {
			   "expiration": {
				   "month": "12",
				   "year": "2022"
			   },
			   "firstName": "John",
			   "lastName": "Dee",
			   "address1": "123 Street",
			   "address2": "Apt 123",
			   "city": "Test",
			   "state": "AZ",
			   "zipCode": 12345
		   },
		   "userData": {
			   "firstName": "John",
			   "lastName": "Dee",
			   "zipCode": 12345
		   }
	   }
     }
}

Request Body Parameters

Encrypted Card Data Body

{
   "CardData": {
	"CardNumber": "string",
	"Expiration": {
		"CardExpirationMonth": "string",
		"CardExpirationyear": "string"
	},
	"FirstName": "string",
	"LastName": "string",
	"AddressLine1": "string",
	"AddressLine2": "string",
	"City": "string",
	"State": "string",
	"ZipCode": "string"
      }
}

Sample Encrypted Card Data Body

{
    "CardData": {
	"pan": "4111999999991234",
	"expiration": {
	     "month": "12",
	     "year": "2020"
        }
    }
}

Encrypted Card Data Parameters

Sample User Data Body

{
   "UserData": {
	"FirstName": "john",
	"LastName": "doe",
	"ZipCode": "91107"
   }
}

User Data Parameters

Sample Single Commit Responses

Transfer Pending

Response:HTTP/1.1 201 Created
Date: Tue, 12 Apr 2022 19:47:33 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 121
Connection: keep-alive
x-correlation-id: be732974-aa3d-4b1b-aaea-5d64daf0b170
Strict-Transport-Security: max-age=31536000; includeSubdomains;
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block

{
   "transfer": {
      "transferIdentifier": "c8b18a28-b87b-4c0f-ab77-87965c4c6199",
      "transferStatus": "Pending"
    }
}

Transfer Failed (HTTP 503)

This response indicates a timeout (HTTP 503) or internal exception.

{
      "transfer": {
	  "transferIdentifier": "1d670075-a5bc-467d-856c-32ec44455fef",
	  "transferStatus": "failed"
      },
      "errors": [
      {
       "code": 4214,
       "subcode": 1514,
       "description": "system error"
      }
   ]
}

Transfer Failed (HTTP 400)

This response indicates a data issue (HTTP 400) occurred.

{
    "transfer": {
	"transferIdentifier": "1d670075-a5bc-467d-856c-32ec44455fef",
	"transferStatus": "failed"
    },
    "errors": [
	{
	    "code": 4200,
	    "subcode": 945,
	    "description": "Invalid Request Id"
	}
    ]
}

GET Transfer API

Partner Integration Environment URL

<https://pie.mul.secure2.greendot.com/enrollment/v1/api/flex/externalAccounts/acb07274-b4e8-446f-9ac5-c43fe117ec91/transfers/27e289ba-2002-492b-8497-db44b44bca6f> HTTP/1.1

Production URL

<https://prd.mul.secure2.greendot.com/enrollments/v1/api/\{programCode}/externalAccounts/\{externalAcctId}/transfers/\{transferId}>

Request Header Parameters

URL Parameters

Sample Request

GET https://qa.mul.secure2.greendot.com/enrollment/v1/api/flex/externalAccounts/acb07274-b4e8-446f-9ac5-c43fe117ec91/transfers/27e289ba-2002-492b-8497-db44b44bca6f HTTP/1.1
Accept-Encoding: gzip,deflate
x-Remapped-Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMzNmNlZGI4LTg3NTQtNDY1MS04NWYxLTY2NDI4ODY4YzAwZSJ9.eyJjbGllbnRpZCI6ImU1MWIyMDExYjNhMzRmYzE5Mzk0MTJkZWU4ZTRkOTIyIiwiaXNzIjoiaHR0cHM6Ly9ncmVlbmRvdC5jb20iLCJhdWQiOiJBbGwiLCJpYXQiOjE2MDI3ODMzMTYsImV4cCI6MjIzMzUwMzMxNn0.lT5Oeb1wL-cf8F15A4O7g8ixlrUYDV-GM-RIspQ5yUDp6NhVRCW7054nLvhyYYQIxiT5X1vKKA4QYLbSvcEMY1GxLUkSlassJRrqA8djucdpK5e9evGzN7knqQ3HR8arTLe8Ah6HrcznN_xbQ_UOvAvfLT8Sk7M3pIIUfEZhOtFyYtph4tJOmkJBsvU3yIBRlLb9k9Z4BhqCBftvQalIZ7RYIGJIQW6vX_fUQFKHI3-FjPkFXT3uOEzGr1LNyhHM5t31r525rZeuem5co1bXFiDaGBaRJbdNCMCxoNaM6e9CqzVcoupFW_u1jyPokFwIDLXrZtAzEn8RSBHA4QKVXg
X-Forwarded-For: 192.168.23.3
Request-ID: 5da118ce-29ef-4d86-81a4-2990ec1471fa
Content-Length: 0
Host: qa.mul.secure2.greendot.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.5.2 (Java/1.8.0_181)

Sample Response Body

{
   "transfer": {
	"transferId": "046D4980-6428-4CE4-9476-4755564F8517",
	"transferStatus": "Completed",
	"transactionDate": "Completed",
	"currency": "USD",
	"transactionAmount": "5.00",
	"totalFeeAmount": "0.0",
	"totalTransactionAmount": "5.00",
   }
}

{
   "responseDetails": [
       {
	  "code": 0,
	  "subCode": 0,
	  "description": "string",
	  "url": "http://tbd"
       }
   ]
}

Webhook Transfer Statuses

To notify a partner the result of a transfer, the GFT processor triggers transfer webhooks.

API Call Structure

POST <https://yourendpoint.yourcompany.com/events/SinglePhaseTransfer>

Webhook status types include:

• Completed - The transfer was successful.
• Failed - A system error occurred.
• Declined - The transfer was declined for one of the following reasons:
  • The account was not eligible for transfer activity.
  • The transfer request exceeded the transfer limit.
  • The transfer was rejected due to fraud (OFAC).
  • The transfer request was for less than the minimum transaction amount.

A sample of each type follows.

Sample Completed Transfer

{
   "accounts": [
	{
	   "accountIdentifier": "c63ff033-7df4-4bdf-a5aa-d8d1dfc4a05d",
	   "events": [
	{
	   "eventIdentifier": "125d5986-4c07-4ab6-9c66-de3053e688a1",
	   "eventType": "singlePhaseTransfer",
	   "eventDateTime": "2022-03-14T17:10:08.129Z",
	   "singlePhaseTransfer": [
		{
		   "transferIdentifier": "DBC79BB6-40D9-A63C-B69B-C7DBD9403CA6",
		   "transactionAmount": 5.0,
		   "transferStatus": " Completed",
		   "transferDateTime": "2022-03-11T23:13:13Z",
		   "response": {
		      "code": "0",
		      "subCode": "0",
		      "description": "success"
	        }
  	      }
	    ]
          }
        ]
      }
    ]
  }

Sample Failed Transfer

{
   "accounts": [
	{
	   "accountIdentifier": "c63ff033-7df4-4bdf-a5aa-d8d1dfc4a05d",
	   "events": [
		{
		   "eventIdentifier": "125d5986-4c07-4ab6-9c66-de3053e688a1",
		   "eventType": "singlePhaseTransfer",
		   "eventDateTime": "2022-03-14T17:10:08.129Z",
		   "singlePhaseTransfer": [
		   {
		      "transferIdentifier": "DBC79BB6-40D9-A63C-B69B-C7DBD9403CA6",
		      "transactionAmount": 5.0,
		      "transferStatus": "failed",
		      "transferDateTime": "2022-03-11T23:13:13Z",
		      "response": {
		          "code": "4200",
			  "subCode": "948",
			  "description": " InvalidTransferType"
		     }
	          }
	       ]
	     }
	  ]
       }
    ]
 }

Sample Declined Transfer

{
   "accounts": [
	{
	   "accountIdentifier": "c63ff033-7df4-4bdf-a5aa-d8d1dfc4a05d",
	   "events": [
	{
	   "eventIdentifier": "125d5986-4c07-4ab6-9c66-de3053e688a1",
	   "eventType": "singlePhaseTransfer",
	   "eventDateTime": "2022-03-14T17:10:08.129Z",
	   "singlePhaseTransfer": [
	   {
	      "transferIdentifier": "DBC79BB6-40D9-A63C-B69B-C7DBD9403CA6",
	      "transactionAmount": 5.0,
	      "transferStatus": "declined",
	      " transferDateTime": "2022-03-11T23:13:13Z",
	      "response": {
	         "code": "4240",
		 "subCode": "1540",
	         "description": "Consumers monthly transaction limit reached"
	      }
	    }
	  ]
	}
      ]
    }
  ]
}

Realtime API Response Codes

Webhook Transfer Status Codes