Return API Method

This operation is used to reverse a previous authorized load transaction.

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

Syntax

POST {baseUrl}/transaction/return

Example Request

Success Request

POST {baseUrl}/transaction/return
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: test102

{
	"originalTransactionId": "test101",
 	"accountNumber": "",
  	"accountIdentifier": "06e33e98-5c40-4c1a-967b-930f28f509a4",
"metadata": {
    		"storeId": "CC970",
    		"merchantId": "FSCC0342",
   		"userId": "[email protected]",
    		"requestDateTime": "2023-09-28T01:00:42Z",
    		"registerId": "01"
  }
}

Negative Request

POST {baseUrl}/transaction/return
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: test103

{
	"originalTransactionId": "test102",
	"accountNumber": "",
	"accountIdentifier": "06e33e98-5c40-4c1a-967b-930f28f509a4",
"metadata": {
    		"storeId": "CC97",
    		"merchantId": "FSCC0342",
   		"userId": "[email protected]",
    		"requestDateTime": "2023-09-28T01:00:42Z",
    		"registerId": "01"
  }
}

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	Unique merchant Id. It is defined by Green Dot – Merchant corresponding with Retailer.
originalTransactionId	Yes	String	MaxLength:50	The transaction id of the transaction info needs to be returned. This is the same value as RequestId passed in Reload request
accountNumber	No	String	16 digits PAN	Account Number (PAN) of the card. Note: Either AccountNumber or AccountIdentifier is required
accountIdentifier	No	GUID	e5843e05-d367-4bf1-a223-3af46ae18802	Newly created unique identifier in sale card, should be using for all subsequent API calls. Either of AccountNumber / AccountIdentifier required.

Example Response

Success Response

HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: test102
X-GD-ResponseId: 57b07865-7c6f-4228-996e-d3f9d9fcc748
X-GD-ResponseCode: 0
{
	"metadata": {
		"requestId": "test102",
		"responseId": "57b07865-7c6f-4228-996e-d3f9d9fcc748",
		"responseDateTime": "2023-09-28T09:00:42.8192011Z",
		"responseCode": 0,
		"responseDescription": "Success"
	}
}

Negative Response

HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: test103
X-GD-ResponseId: 160d9d1b-c528-425c-ad09-01ade5fb5fa9
X-GD-ResponseCode: 800
{
	"metadata": {
		"requestId": "test103",
		"responseId": "160d9d1b-c528-425c-ad09-01ade5fb5fa9",
		"responseDateTime": "2023-09-28T09:03:54.8151139Z",
		"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.

Response Cases

Code	CodeText	ResponseDescription	Description
0	Success	Success	Return is successful.
100	InvalidParameter	• RequestId is too long • The field RegisterId must be a string or array type with a maximum length of '20'. • Invalid length of AccountNumber • UserId is too long • StoreId is too long • MerchantId is too long • The field OriginalTransactionId must be a string with a minimum length of 1 and a maximum length of 50. • RequestId is required • RequestDateTime is required • Either AccountNumber or AccountIdentifier is required • UserId is required • StoreId is required • MerchantId is required • The OriginalTransactionId field is required.	Invalid parameter in the request. Examples: MerchantID not supplied, StoreID not supplied.
110	InvalidAccountNumber	• AccountNotFound • AccountStatus is Pending. • This account is in a restricted state that does not allow outbound transfers. • AccountStatus is locked but is curable. • AccountStatus is Closed.	Account is not found; account status is not valid
130	InvalidMerchant	InvalidMerchant	MerchantId in request has not been found/enabled in the system.
460	OperationNotAllowed	• Transaction was not found • Transaction was already failed • Transaction is under committing and please try later • Original transaction does not support return • Transaction was already returned • Transaction was already voided	Auth transaction was not found; Auth transaction type does not suuport return or Auth transaction is in a status that cannot perform return at the time of request. • Unload does not support return • Transaction Statuses that support return are ‘pending’ and ‘posted’. • If pending auth transaction has ben returned, the transaction status of original transaction will be marked as returned. No transaction will be shown in transaction statement. • If posted auth transaction has been returned, there will be two records in transaction statement. One is auth transaction and the other is the return transaction.
600	UnableToProcessRequest		Unable to process request due to downstream errors.
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 request is not found in system.
862	RetailChainUserNotActive	User is not active.	UserId in request is not active.
1000	GeneralFailure	GeneralFailure	Service failure.