Polling Best Practice

Transaction Result Events

After processing a transaction, poll for status updates to retrieve the latest transaction result details.

Please Note:

  • Postback is our recommended result gathering method for most transaction types.
  • Polling can optionally be used in place of postback, or as a fallback method.
  • Polling for transaction results is only necessary for UI-initiated transactions.
  • Server-initiated transactions (tokenized, checkout, direct post, etc.) return direct results and do not require polling.

Environment URLs

Sandbox https://api.emergepay-sandbox.chargeitpro.com
Production https://api.emergepay.chargeitpro.com

Authentication

Header Authentication Token – HTTP Bearer (JWT)
Contact an integration specialist if you need a new Authentication Token.

Polling Request

Begin polling for updates after the transaction has been submitted or sent to the payment terminal.

Method GET
Route /virtualterminal/v1/orgs/{{oid}}/transactions/{{externalTransactionId}}

200 - OK

Status 200 – OK
Content-Type application/json
Advice Transaction result found. Take action based on result:

  • Approved: Stop polling; present approval.
  • Partially Approved: Stop polling; submit follow-up for remaining balance.
  • Decline/Cancelled: Stop polling; present status to user.
Example Result 
{ 
  "transactionResponse": { 
    "externalTransactionId": "550e8400-e29b-41d4-a716-446655440000", 
    "uniqueTransId": "12345678901234567890",
    "transactionReference": "TXN-2024-001", 
    "transactionType": "CreditSale", 
    "resultStatus": "true", 
    "resultMessage": "Transaction approved",
    "amount": "123.45",
    "amountProcessed": "123.45",
    "amountTipped": "5.00",
    "amountTaxed": "8.00",
    "amountBalance": "0.00",
    "maskedAccount": "************1234",
    "accountCardType": "VS",
    "accountExpiryDate": "1225",
    "accountEntryMethod": "Chip",
    "accountFingerprint": "abc123def456",
    "approvalNumberResult": "A12345",
    "avsResponseCode": "Y",
    "avsResponseText": "Address and ZIP match",
    "cvvResponseCode": "M",
    "cvvResponseText": "CVV match",
    "batchNumber": "20240101",
    "billingName": "John Doe",
    "cashier": "CASHIER001",
    "customerId": "CUST123",
    "createdOn": "2024-01-15T10:30:00.000Z",
    "isPartialApproval": false,
    "consumerSurchargeFee": "0.00",
    "emv": {
      "aid": "A0000000041010"
    }, 
    "level2": {
      "isTaxExempt": false,
      "purchaseId": "123",
      "purchaseOrderNumber": "321"
    }, 
    "signature": "data:image/png;base64,iVBORw0KGgo..." 
  }
}

404 - Transaction Not Found

Status 404 Not Found
Advice Occurs when the transaction result is not available yet.

  • First 0-3 Minutes: Retry every 3-5 seconds.
  • After 3 Minutes: Send a cancellation request. Move to background queue.
  • Background: Poll every 30 seconds for 20 minutes.
  • If Approved in Background: Issue a void request.
  • After 20 Minutes: Flag for manual review.

Error Responses (400, 401, 403)

400 Bad Request Invalid request (e.g., malformed UUID). Review error message body.
401 Unauthorized JWT missing or invalid. Contact developer support if formatting is correct.
403 Forbidden Incorrect Endpoint URL. Verify URL in developer documentation.