Sale Card

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.


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": "[email protected]",
    "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

        "userId":"[email protected]",

Request Parameters

ParameterRequired(Y/N)Format/Data TypePatternDescription
X-GD-RequestIdYesStringMaxLength:50It is a unique transaction identifier that is generated by the retailer.
requestDateTimeYesDateTime2023-08-08T12:34:56ZTime stamp at which transaction occurred.
The time stamp has to be in UTC time zone and follow the following date and time formats:

registerIdNoStringMaxLength: 20Register where the transaction occurred.
userIdYesStringMaxLength:50The unique ID of the user generating the transaction.
storeIdYesStringMaxLength: 20The store number associated with the retailer that sold the package.

If not supplied, InvalidParameter (Code:100) error will be return.
merchantIdYesStringMaxLength: 20The unique merchant Id. Defined by Green Dot – Merchant corresponding with Retailer.
externIdNoStringMax: 20It 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.
Fee paid for a Plan. The available options are:

• Monthly
• Employee

Use this field in SaleCard to indicate if this card is for employee (teller) or customer.
registrationTokenYesGUIDe5843e05-d367-4bf1-a223-3af46ae18802RegistrationToken from the ValidateRegistration response.
productMaterialTypeYesStringMax: 100Identifies 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

        "responseDescription":"Store was not found"

Response Parameters

ParameterRequired(Y/N)Format/Data TypePatternDescription
requestIdYesStringMaxLength:50The unique request ID from request.
responseIdYesStringMaxLength:50The unique Response Identifier (generated by GreenDot).
responseDateTimeYesDateTime2023-09-07T16:12:23.4541445+08:00Time 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
responseCodeYesNumericMaxLength:4Indicates success and failure of the response codes. It is in the numeric format.
responseDescriptionYesStringMaxLength:255Describes the Response Code in more detail. It is in the String format.
lastFourOfCardYesString4 digitsThe last 4 digits of the sold card. It will only be returned with successful card sale.
accountIdentifierNoStringe5843e05-d367-4bf1-a223-3af46ae18802Newly created unique identifier for sale card, should be using for all subsequent API calls
accountReferenceNumberNoStringMax: 50This should be used to pass to Entrust for card data lookup

Response Cases

CodeCode TextResponse DescriptionExplanation of the Response Code
0Success• SuccessCard is enrolled successfully.
100InvalidParameter• 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.
130InvalidMerchant• InvalidMerchantMerchantId in request has not been found/enabled in the system.
800InvalidStore• Store was not foundStore is not found; store is not for the partner or store does not support this operation.
861RetailChainUserNotFound• User is not found.UserID in the request is not found in system.
862RetailChainUserNotActive• User is not active.UserId in request is not active.
600UnableToProcessRequest• Package Id not foundExtern ID on the package was not found.
1000GeneralFailure• GeneralFailureService failure.