ReplaceCard API Method

This operation is used to replace the card for different reasons and replace it immediately with a temp/perso card in store.

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

Syntax

POST {baseUrl}/card/replace

Example Request

Success Request

POST {baseUrl}/card/replace
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: test101
{
    "metadata": {
        "merchantId": "fscc0342",
        "registerId": "01",
        "requestDateTime": "2023-10-11T07:53:32Z",
        "storeId": "CC970",
        "userId": "[email protected]"
    },
  "replacementRequestType": "Lost",
  "externId": "",
  "deliveryType": "InstantIssue",
  "productMaterialType": "02",
  "accountNumber": "",
  "accountIdentifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" 
}

Negative Request

POST {baseUrl}/card/replace
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: test101
{
    "metadata": {
        "merchantId": "fscc0342",
        "registerId": "01",
        "requestDateTime": "2023-11-10T10:22:22Z",
        "storeId": "CC970",
        "userId": "[email protected]"
    },
  "replacementRequestType": "Lost",
  "externId": "",
  "deliveryType": "InstantIssue",
  "productMaterialType": "08",
  "accountNumber": "",
  "accountIdentifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6" 
}

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. If not supplied, InvalidParameter (Code:100) error will be return.
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	Unique merchant Id. It is defined by Green Dot – Merchant corresponding with Retailer. If not supplied, InvalidParameter (Code:100) error will be return.
accountNumber	No	String	16 digits PAN	16 digits number of Card. Either of AccountNumber / AccountIdentifier required.
replacementRequestType	Yes	Enum	• Lost • Stolen • Damaged • NeverReceived	Replacement Request Type
externId	No	String	0012345678	10 digit Green Dot internal reference number that is associated with the package. This is required when the card is being replaced with a replacement card in store. It is optional for instant issue cards.
deliveryType	No	Enum	InstantIssue	Delivery Type of Perso Card.
accountIdentifier	No	String	e5843e05-d367-4bf1-a223-3af46ae18802	Newly created unique identifier for sale card, should be using for all subsequent API calls. Either of AccountNumber / AccountIdentifier required.
ProductMaterialType	No	String	03	Blank for original design, value for new design. Please refer to Appendix B for detail.

Example Response

Success Response

HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: test101
X-GD-ResponseId: c07cdd09-85a8-438b-97bc-9c50745d3631
X-GD-ResponseCode: 0

{
    "accountReferenceNumber ": "XXX123455",    
    "metadata": {
        "requestId": "test101",
        "responseId": "c07cdd09-85a8-438b-97bc-9c50745d3631",
        "responseDateTime": "2023-10-11T07:53:36.1198386Z",
        "responseCode": 0,
        "responseDescription": "Success"
    }
}

Negative Response

HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: test101
X-GD-ResponseId: 5225d51b-12e6-4683-b6ae-23b5fecc92e9
X-GD-ResponseCode: 600

{
    "accountReferenceNumber": null,    
    "metadata": {
     "requestId": "test101",
     "responseId": "5225d51b-12e6-4683-b6ae-23b5fecc92e9",
     "responseDateTime": "2023-11-10T10:22:30.171817Z",
     "responseCode": 600,
     "responseDescription": "Invalid Product Material type"
    }
}

Response Parameters

Parameter	Format/Data Type	Pattern	Description
requestId	String	MaxLength:50	The unique request ID generated from the request.
responseId	String	MaxLength:50	The unique Response Identifier (generated by GreenDot).
responseDateTime	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	Numeric	MaxLength:4	Indicates success and failure of the response codes. It is in the numeric format.
responseDescription	String	MaxLength:255	Describes the Response Code in more detail. It is in the String format.
accountReferenceNumber	String	ABXX8768420	This should be used to pass to Entrust for card data lookup – for in store replacement. Only success response contains accountReferenceNumber value.

Response Cases:

Code	CodeText	responseDescription	Description
0	Success	Success	Success.
100	InvalidParameter	• Either AccountNumber or AccountIdentifier is required • Invalid length of AccountNumber • ExternalId already used. • ExternalId expired. • RequestId is required • UserId is required • RequestDateTime is required • StoreId is required • MerchantId is required • RequestId is too long • UserId is too long • StoreId is too long • MerchantId is too long	Invalid parameter in the request. 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 • The replace feature is not enabled for this store	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 request is not found in system.
862	RetailChainUserNotActive	User is not active.	UserId in request is not active.
110	InvalidAccountNumber	• Account Status is Closed • Account Status is Locked • Account Status is Restricted • Account Status is Pending • InvalidAccountNumber • Account Not Found	Account is not found; account status is not valid.
600	UnableToProcessRequest	• The initial card is not activated • Payment Instrument cannot be generated due to incorrect mailing address. • Not received was made against a PAN/Instrument which is already activated. • Invalid ProductMaterialType • Package Id not found • Fail	Error when process replace card in download stream services.
1000	GeneralFailure	GeneralFailure	Service failure.