Replace Card
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. |
Updated 16 days ago