Skip to main content

Client Status API

Another contract that runs in the opposite direction: you host this endpoint, and Cheggout calls it to check the status of a payment your app collected during the deep payment flow.

Available Required for deep payment integrations

Why it exists​

In deep payment, your app collects the money and then relaunches the SDK with the result. If that relaunch never happens — the app was killed, the network dropped, the customer force-closed — Cheggout has an order with no known outcome.

This endpoint lets Cheggout ask you directly, so the order resolves instead of hanging.

The endpoint you build​

GET https://<your-domain>/cheggout-txn-status?virtualId={{virtualId}}&orderId={{cheggoutRefNo}}&amount={{amount}}

Headers​

HeaderValue
AuthorizationA key you provide to Cheggout

Query parameters​

ParameterDescription
virtualIdThe customer
orderIdCheggout's reference for the transaction — the cheggoutRefNo
amountThe payment amount
Parameters are encrypted and URL-encoded

Cheggout encrypts virtualId, cheggoutRefNo and amount before appending them to the URL, and URL-encodes the result. Your endpoint must URL-decode and then decrypt before using them.

The scheme is AES, with a shared secret key converted to a 16-byte key before encryption.

TBD The secret-key exchange process is not documented. How the AES key is generated, shared and rotated must be agreed with Cheggout before you implement. Tracked in Open items.

TBD The cipher parameters are not documented either. "AES with a 16-byte key" does not describe a decryptor. Not specified: the mode of operation (for example CBC, GCM or ECB), the padding scheme, whether an IV is used and if so how it is transmitted, and the encoding of the ciphertext before URL-encoding (Base64 or hex). Every one of these must match Cheggout's encryptor exactly or decryption fails, and a wrong guess about mode is a security problem rather than only a compatibility one. Agree all four with Cheggout in writing before you implement, and confirm them against real UAT traffic. Tracked separately in Open items.

Lookup requirement​

Your implementation must be able to resolve a payment from either identifier pair:

AvailableLook up by
Your transaction ID and virtualIdYour own transaction reference
cheggoutRefNo and virtualIdCheggout's reference

The second case is the important one. If your app died before it could report your transaction ID, Cheggout only knows its own reference — so you must store cheggoutRefNo against your transaction at the moment you receive the payment request, before you attempt the collection. If you only store it on success, the failure case you built this endpoint for is exactly the case you cannot answer.

Response​

TBD The expected response shape is not documented. Agree the exact contract with Cheggout before implementing — including the field names, the status values they expect, and what to return when the transaction is unknown.

At minimum you will need to express: paid, failed, pending, and not found.

Implementation guidance​

Store cheggoutRefNo immediately. On receiving the payment request, before collecting anything. This is the single most important implementation detail on this page.

Make it idempotent and side-effect free. It is a status query. Cheggout may call it more than once; it must never change anything.

Respond quickly. Look up your own record; do not call downstream payment providers synchronously if you can avoid it.

Authenticate it. Validate the Authorization header against the key you issued to Cheggout. Without that, anyone who guesses the URL can enumerate your transaction statuses.

Never leak beyond the query. Return the status of the requested transaction only — no customer details, no other transactions, no internal identifiers.

Log every call with the orderId so you can reconcile disputes later.

Security​

  • Rate-limit it. It is a public endpoint on your domain.
  • Restrict by IP to Cheggout's outbound addresses if you can obtain them.
  • Do not accept unencrypted parameters as a fallback — that turns the encryption into decoration.
  • Treat a decryption failure as a rejection, not as a reason to guess.
  • Keep the AES key in a secret manager, like any other credential.

Checklist​

  • Endpoint deployed and reachable from Cheggout's network
  • Authorization key issued to Cheggout and validated on every call
  • AES key exchanged and stored in a secret manager
  • URL-decode then decrypt, with failures rejected
  • cheggoutRefNo stored before payment collection
  • Lookup works from either identifier pair
  • Response shape agreed with Cheggout
  • Rate limiting and, where possible, IP restriction in place
  • Every call logged against its orderId

Next​