SaleCard API Method

This method is used to sell a card to a customer. If a “RegistrationToken” passes, then the card gets registered to the customer’s name.

📘
Every request triggered should have a unique X-GD-RequestId value in the header.

API Call Structure

POST {baseUrl}/card/sale

Example Request

Success Request

POST {baseUrl}/card/sale
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: 123456789

{
  "metadata": {    
    "merchantId": "FSCC0342",
    "registerId": "01001",
    "storeId": "CC970",
    "userId": "EMP001234555",
    "requestDateTime": "2013-09-18T10:53:07Z"    
  },
  "externId": "3085033189",
  "feePlan": "Monthly",
  "registrationToken": "2E28C3D0-A1EC-4178-A707-77AFD46D4B24",
  "productMaterialType": "02"
}

Negative Request

POST {baseUrl}/card/sale
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: 264538a7-6917-421c-9918-a6fc7097682f

{
    "externId":"0003194263",
    "registrationToken":"38fb5c2f-c1e7-4967-b396-a55ee4bc0848",
    "productMaterialType":"02",
    "feePlan":"Monthly",
    "metadata":{
        "storeId":"test",
        "merchantId":"FSCC0342",
        "userId":"EMP001234555",
        "requestDateTime":"2023-09-22T08:39:05Z",
        "registerId":"01001"
    }
}

Request Parameters

Parameter	Required(Y/N)	Format/Data Type	Pattern	Description
X-GD-RequestId	Yes	String	MaxLength:50	It is a unique transaction identifier that is generated by the retailer.
requestDateTime	Yes	DateTime	2023-08-08T12:34:56Z	Time stamp at which transaction occurred. The time stamp has to be in UTC time zone and follow the following date and time formats: YYYY-MM-DDTHH:mm:ssZ
registerId	No	String	MaxLength: 20	Register where the transaction occurred.
userId	Yes	String	MaxLength:50	The unique ID of the user generating the transaction.
storeId	Yes	String	MaxLength: 20	The store number associated with the retailer that sold the package. If not supplied, InvalidParameter (Code:100) error will be return.
merchantId	Yes	String	MaxLength: 20	The unique merchant Id. Defined by Green Dot – Merchant corresponding with Retailer.
externId	No	String	Max: 20	It is 10 digit Green Dot internal reference number that is associated with the package. The length of digits may vary across products. Must be null or empty for cards printed at store.
feePlan	No	String	Max Length - 100	Fee paid for a Plan. Use this field in SaleCard to indicate the fee plan. The values for fee plan should come from pre-defined list of values agreed upon between partner and Greendot.
registrationToken	Yes	GUID	e5843e05-d367-4bf1-a223-3af46ae18802	RegistrationToken from the ValidateRegistration response.
productMaterialType	Yes	String	Max: 100	Identifies card design of personal card. This should come from pre-defined list of values agreed upon between partner and GDOT.

Example Response

Success Response

HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: 201309181254
X-GD-ResponseId: 127d59fa-8851-444a-a639-716e81b2cecd
X-GD-ResponseCode: 0

{
    "metadata": {
        "requestId": "201309181254",
        "responseCode": 0,
        "responseDescription": "Success",
        "responseDateTime": "2013-09-18T17:53:07.1411753Z",
        "responseId": "127d59fa-8851-444a-a639-716e81b2cecd"
    },    
    "lastFourOfCard": "2897",    
    "accountIdentifier": "391372D1-20CD-4279-BA37-5308FC3A54C2",
    "accountReferenceNumber": "VTN2604025"
}

Negative Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-GD-RequestId: 264538a7-6917-421c-9918-a6fc7097682f
X-GD-ResponseCode: 800
X-GD-ResponseId: bfd7997a-a711-41b0-9857-2a77a5146c1d

{
    "lastFourOfCard":null,
    "accountIdentifier":null,
    "accountReferenceNumber":null,
    "metadata":{
        "requestId":"264538a7-6917-421c-9918-a6fc7097682f",
        "responseId":"bfd7997a-a711-41b0-9857-2a77a5146c1d",
        "responseDateTime":"2023-09-22T10:07:52.8826751Z",
        "responseCode":800,
        "responseDescription":"Store was not found"
    }
}

Response Parameters

Parameter	Required(Y/N)	Format/Data Type	Pattern	Description
requestId	Yes	String	MaxLength:50	The unique request ID from request.
responseId	Yes	String	MaxLength:50	The unique Response Identifier (generated by GreenDot).
responseDateTime	Yes	DateTime	2023-09-07T16:12:23.4541445+08:00	Time stamp at which transaction occurred. The time stamp is in UTC time zone and follow the following date and time formats: • YYYY-MM-DDTHH:mm:ssfffffffK
responseCode	Yes	Numeric	MaxLength:4	Indicates success and failure of the response codes. It is in the numeric format.
responseDescription	Yes	String	MaxLength:255	Describes the Response Code in more detail. It is in the String format.
lastFourOfCard	Yes	String	4 digits	The last 4 digits of the sold card. It will only be returned with successful card sale.
accountIdentifier	No	String	e5843e05-d367-4bf1-a223-3af46ae18802	Newly created unique identifier for sale card, should be using for all subsequent API calls
accountReferenceNumber	No	String	Max: 50	This should be used to pass to Entrust for card data lookup

Response Cases

Code	Code Text	Response Description	Explanation of the Response Code
0	Success	• Success	Card is enrolled successfully.
100	InvalidParameter	• The RegistrationToken field is required. • StoreId is required • MerchantId is required • UserId is required • StoreId is too long • UserId is too long • MerchantId is too long • RequestId is too long • ExternalId already used. • Registration token status is not healthy • The registration token is already linked to a card • Registration token has been expired. • ExternalId expired. • Product material type can not be empty • RequestDateTime is required • RequestId is required • The field ExternId must be a string with a maximum length of 20.	Invalid parameter when validating the request value. Examples: MerchantID not supplied, StoreID not supplied.
130	InvalidMerchant	• InvalidMerchant	MerchantId in request has not been found/enabled in the system.
800	InvalidStore	• Store was not found	Store is not found; store is not for the partner or store does not support this operation.
861	RetailChainUserNotFound	• User is not found.	UserID in the request is not found in system.
862	RetailChainUserNotActive	• User is not active.	UserId in request is not active.
600	UnableToProcessRequest	• Package Id not found	Extern ID on the package was not found.
1000	GeneralFailure	• GeneralFailure	Service failure.