How Balances Work

Summary

The GetQuote call is where we check the validity of the card. We're both looking at the balance of the card and if it's a card we accept. This is the longest part of the process so the call to GetQuote is Asynchronous so you will need to handle this flow properly to get the results. Please review the Flow section on the asynchronous​ process.

Best Practices for customer interaction

It's also important for the customer experience that feedback is given as part of the process so they understand the delay and once we have a response either the Quote for the card or the error message associated with the card.

GetQuote Returns and how to interpret them.

There are 5 different scenarios that need to be handled

🚧

Please take note of the API call for the return

Not all of the error returns are on the same API call. Because the GetQuote is asynchronous there are two different API calls with two different results. The POST /GetQuote and the GET /GetQuote. Please pay special attention to which call returns which value.

1. Successfully created the Quote

These are returned on POST /GetQuote

If we're able to successfully create the quote we return a 201 response. We've successfully created a quote and a Transaction has been created to track the card through the GetQuote process.

2. Successfully retrieved a balance

These are returned in GET /GetQuote

If we successfully retrieved a balance, we return a 200 response. You need to look at the Response object in the TransactionStatus object for the updated QuoteResponse with the correct value.

2. Invalid Card Values

These are returned on GET /GetQuote

Invalid Card values are errors where either the customer gave us bad information (i.e. the card number or PIN was incorrect) or when we tried to retrieve the information we found that the card was not acceptable or the balance was not there.

These are the most common types of errors but also the most contentious with the customer. Care should be given on the interaction with the customer and instructions on why we could not accept the card and how they should proceed.

For a return of this type of error, an Error object is returned. These are the important values in the Error:

• The ErrorCode is a machine-readable string that represents the type of error. This allows for parsing of the error to allow for different flows of error recovery.
• The Message is a short explanation of the message. This is meant for logging what happened.
• The UserMessage is meant to explain what happened and how to resolve. In the case of GetQuote, this UserMessage is the message either from the merchant website or the human that tried to retrieve the balance (if your account is configured for Human-based Balance Inquiries. Please talk with your account manager for more information)

📘

Best Practice

The UserMessage field in meant to be displayable to the customer or your agent/associate if you have a real-time interaction with the customer. It provides crucial feedback on why there was an issue with the card and as a best practice, we encourage you to share this information with the customer, so they understand the problem and in some cases, they will be able to resolve it.

3. Failed to retrieve the balance

These are returned on GET /GetQuote

Failed to Retrieve errors occur when we're not able to retrieve the status of the card. These types of errors are transient in nature, but it's not known when we will be able to recover from this error. This can occur if one of our downstream processors are down or the merchant website or phone number is down.

📘

Best Practice

We will try to provide as much information as we can in the UserMessage portion of the Error but with this type of error,​ we don't know when we're going to recover. We recommend that you let the customer know that we're having problems contacting the merchant and to please try again later.

4. Invalid Parameters

These are returned in GET /GetQuote and POST /GetQuote

Invalid Parameter errors can happen if either header information or the wrong parameter values are sent. This error usually happens during the code and testing phase so it should not have a customer impact.

5. Internal Server Errors

These are returned on GET /GetQuote or POST /GetQuote

Server errors can happen if there is a problem with the infrastructure or a major configuration issue. We monitor for these types of errors and Alerts are generated for our Site Reliability Team to investigate. If you are seeing high levels of errors you can also email [email protected] to alert us of issues you are having.

Flow

Getting the quote

Polling for Results

There are two steps for getting a Quote

Step 1 -- Calling POST /GetQuote

This step will send the card information for the quote and return immediately. This will queue up the balance check and you will get back a TransactionID. You use this TransactionId in the next step. You will also NOT get the above HTTP​ status codes. This is returned in Step 2.

POST https://api.GiftDeals.com/prod/v3/exchange/quote HTTP/1.1
Accept-Encoding: gzip,deflate
x-api-key: e73e0d89-9701-4a53-8e24-47b946521f1d
requestId: quote2222
Content-Type: application/json
Content-Length: 109
Host: api.GiftDeals.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
  
{ 
 "card":{ 
        "cardNumber":"9879200195344144",
        "pinNumber":"4144",
        "productLineId":"19"     
   }
}

HTTP/1.1 201 Created
Date: Thu, 26 Oct 2017 17:17:59 GMT
Server: Apache-Coyote/1.1
Location: https://api.cardpool.com/prod/v3/exchange/quote/X6F3JFM8FJGFV8XJRN3QM8RXWC
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
CP-TRACE-ID: WfIYwwq@rOMAAFJI3yYAAACD
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked


{
  "transactionId" : "X6F3JFM8FJGFV8XJRN3QM8RXWC",
  "isCompleted" : true,
  "percentComplete" : 100,
  "actualCardValue" : 25.0,
  "exchangeCardValue" : 16.5,
  "responseTimestamp" : "2017-10-26T17:17:59.064Z",
  "expectedCompletionTime" : 0
}

Step 2 -- Calling GET /GetQuote

This step will retrieve the TransactionStatus which will contain the QuoteResponse. It's important to look at the IsCompleted field. Only use the card value values if IsCompleted = true.

GET https://api.GiftDeals.com/prod/v3/exchange/quote/47b946521f1d HTTP/1.1
Accept-Encoding: gzip,deflate
x-api-key: e73e0d89-9701-4a53-8e24-47b946521f1d
requestId: quote2222
Content-Type: application/json
Content-Length: 109
Host: api.GiftDeals.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
  
{ 
}

HTTP/1.1 200 Ok
Date: Thu, 26 Oct 2017 17:17:59 GMT
Server: Apache-Coyote/1.1
Location: https://api.cardpool.com/prod/v3/exchange/quote/X6F3JFM8FJGFV8XJRN3QM8RXWC
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
CP-TRACE-ID: WfIYwwq@rOMAAFJI3yYAAACD
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked

{
"entityid" : X123ASDAS123SDSFSS,
"createrid" : 123,
"createdTimestamp": "2017-10-26T17:17:59.064Z",
"updatedTimespamp": "2017-10-26T17:17:59.064Z",
 "steps":    [
            {
         "descriptionTag": "exchange.vault.credit.card",
         "isCompleted": true,
         "startTime": "2017-10-26T23:13:20.335Z",
         "completionTime": "2017-10-26T23:13:21.306Z"
      },
            {
         "descriptionTag": "exchange.cp.fraud.check",
         "isCompleted": true,
         "startTime": "2017-10-26T23:13:21.753Z",
         "completionTime": "2017-10-26T23:13:23.257Z"
      }
   ],
"percentComplete": 100,
"completionTime": "2017-10-26T23:13:23.257Z",
"response": 
{
  "transactionId" : "X6F3JFM8FJGFV8XJRN3QM8RXWC",
  "isCompleted" : true,
  "percentComplete" : 100,
  "actualCardValue" : 25.0,
  "exchangeCardValue" : 16.5,
  "responseTimestamp" : "2017-10-26T17:17:59.064Z",
  "expectedCompletionTime" : 0
},
"request":
{

 "card":{ 
        "cardNumber":"9879200195344144",
        "pinNumber":"4144",
        "productLineId":"19"     
   }



}

Callback for Results

Coming soon. We will be adding a callback that can be used instead of the polling.