Skip to main content
GET
/
api
/
v2
/
sessions
/
{sessionId}
/
status
Get GEFT Session Status
curl --request GET \
  --url https://www.{baseurl}.com/api/v2/sessions/{sessionId}/status \
  --header 'Authorization: Bearer <token>'
{
  "sessionId": "aadd08f2-83ce-456d-84ed-c68cfed4ee7b",
  "referenceId": "USER12345",
  "amount": 500,
  "status": "Completed",
  "statusDetails": "EFT0301"
}
Retrieve the current status of a GEFT session at any point in the flow. To successfully call this endpoint, you must have a valid access token from the /Authorize endpoint.

​
Get Session Status

Use this endpoint to retrieve the current status of a Guaranteed EFT session. The response includes the current session status, amount information, and detailed status codes. Call this endpoint periodically (for example, every ~30 seconds) until the status reflects a terminal state.

​
Status Information Returned

  • Current session status: See the status codes table below
  • Reference ID: If one was provided when the session was created
  • Amount requested: For guarantee (null if not yet set or entered by user)
The status returned primarily describes the user flow and any front-end outcome or error (for example, success, user exited, login failure, PAD rejected, session timeout).

​
Request Example

curl --location '{{BaseUri}}/api/v2/sessions/{{sessionId}}/status' \
--header 'Authorization: Bearer {{access_token}}'

​
Response

{
  "sessionId": "aadd08f2-83ce-456d-84ed-c68cfed4ee7b",
  "referenceId": "USER12345",
  "amount": 500,
  "status": "Completed",
  "statusDetails": "EFT0301"
}

​
Status Codes

StatusStatusDetailsDescription
InitiatedEFT0101🟡 Session created, awaiting user start
CompletedEFT0301🟢 Transaction scheduled, session fully completed
CompletedEFT0302🟠 Bank account validated, awaiting PAD signature
FailedEFT0401🔴 Login failed - invalid financial institution credentials
FailedEFT0402🔴 Eligibility failed - no guaranteed EFT offered
FailedEFT0403🔴 Identity failed - invalid user information verification
CanceledEFT0501⚫ Session canceled by API request
ExpiredEFT0601⚫ Session timed out - user inactive or did not complete

​
Status Details Explained

EFT0101 - Session Created: A SessionId has been created and Flinks is awaiting for the user to start the session. EFT0301 - Transaction Scheduled: The user has successfully completed the session and a transaction schedule has been instructed. User is fully complete - transaction information can be checked for status of the schedule. EFT0302 - Bank Account Validated: The user has successfully validated their account (if required) - however, Flinks is awaiting the user to sign the PAD. EFT0401 - Login Failed: The user was not able to successfully login to their Financial Institution (received an invalid login). EFT0402 - Eligibility Failed: The user was not offered a Guaranteed EFT because of their account information (for example NSF or overall risk). EFT0403 - Identity Failed: Invalid user information from their Financial Institution did not match provided user information, hence the session has failed. EFT0501 - Session Canceled: A call to the /Sessions/Cancel endpoint was made with the associated SessionId. EFT0601 - Session Timed Out: The sessionId timed-out before the user completed the session.

​
Polling Implementation

async function pollSessionStatus(sessionId, accessToken) {
  const terminalStates = ['Completed', 'Failed', 'Canceled', 'Expired'];
  const maxAttempts = 20;
  const pollInterval = 30000; // 30 seconds

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const response = await fetch(
        `{{BaseUri}}/api/v2/sessions/${sessionId}/status`,
        {
          headers: {
            'Authorization': `Bearer ${accessToken}`
          }
        }
      );

      const status = await response.json();
      console.log(`Status check ${attempt + 1}:`, status);

      if (terminalStates.includes(status.status)) {
        return status;
      }

      await new Promise(resolve => setTimeout(resolve, pollInterval));
    } catch (error) {
      console.error('Status polling error:', error);
    }
  }

  throw new Error('Polling timeout - session status unknown');
}

​
Alternative: Event-Based Monitoring

Instead of polling, consider using frontend events for real-time status updates: 
window.addEventListener('message', function(e) {
  if (e.data.Step === 'SUCCESS') {
    // Payment completed successfully
  } else if (e.data.Step === 'GUARANTEE_FAILED') {
    // Guarantee declined, offer alternatives
  }
});

​
Error Responses

​
Session Not Found

{
  "error": "not_found",
  "error_description": "Session not found"
}

​
Authentication Required

{
  "error": "unauthorized",
  "error_description": "Valid access token required"
}

​
Best Practices

​
Polling Frequency

  • Recommended interval: Every 30 seconds
  • Avoid aggressive polling: Don’t poll more frequently than every 10 seconds
  • Set timeout limits: Implement maximum polling attempts

​
Terminal State Handling

  • Success states: Completed with EFT0301 or EFT0302
  • Failure states: Failed, Canceled, Expired
  • Implement retry logic: For certain failure scenarios where appropriate

​
Error Handling

  • Network errors: Implement retry logic with exponential backoff
  • Token expiration: Re-authenticate and continue polling
  • Session timeouts: Handle gracefully with user messaging

Authorizations

​
Authorization
string
header
required

Bearer token obtained from /api/v1/authorize endpoint

Path Parameters

​
sessionId
string<uuid>
required

Unique session identifier obtained from session creation.

Response

Session status retrieved successfully

​
sessionId
string<uuid>

Unique session identifier.

Example:

"aadd08f2-83ce-456d-84ed-c68cfed4ee7b"

​
referenceId
string

Reference ID provided during session creation.

Example:

"USER12345"

​
amount
number | null

Amount requested for guarantee (null if not set or entered yet).

Example:

500

​
status
enum<string>

Current session status.

Available options:
Initiated,
Completed,
Failed,
Canceled,
Expired
Example:

"Completed"

​
statusDetails
enum<string>

Detailed status code providing additional information.

Available options:
EFT0101,
EFT0301,
EFT0302,
EFT0401,
EFT0402,
EFT0403,
EFT0501,
EFT0601
Example:

"EFT0301"