Skip to main content
POST
Get payin status
Returns the current state of a payment you created. Scoped to your own account: a reference belonging to another merchant is indistinguishable from one that does not exist — both return not_found.
This is for reconciliation and support, not for driving fulfilment. Fulfil on the callback; polling this endpoint in a loop will be rate limited and will always be slower than the callback already on its way to you.
The field above is what you encrypt, not what goes on the wire. The body is always { "data": "<aes-256-gcm ciphertext>" }, and your IP must be on the account allowlist — both covered in Authentication.
No JWT — same as create. Payin endpoints are authenticated by your API key, request signature and IP allowlist. A payin-only integration never calls /api/v1/user/login.
You look a payment up by your own reference, not by our id. There is nothing extra to store: the order id you already have is the key.

​
Example request

All examples assume you have already encrypted the body and signed the request. The transport is identical to payouts, so the helper in Payouts quickstart is the same one both products use.

​
Reading the response

All amounts are decimal strings, never numbers — "100.00", not 100.00. Parsing them into a floating-point type will eventually cost you precision on a real payment.
Three different currencies appear in this one response. requested_currency is what you priced in, deposit_asset is what you were credited in, and received_currency belongs to our internal settlement figure. Reconcile against credited_amount and deposit_asset together — see the three currencies.

​
Status values

All three of paid, underpaid and overpaid moved your balance — but only paid and overpaid mean the customer paid in full. There is no minimum on an underpayment: 10 USDT against a 100 USDT order settles as underpaid. Compare credited_amount against requested_amount before fulfilling anything.
expired means we stopped waiting, not no money arrived. The deposit address stays live, and a late payment still settles, still credits you, and still fires a callback. A payment can move from expired to paid, so do not make it terminal in your own system.

​
Which fields are populated when

Money fields are null until the payment settles. This is the single most common surprise here:
deposit_asset is never null — before your customer picks a method it holds the default (USDT) rather than a choice they have made. Only read it as “the currency you were credited in” once status is settled or deposit_chain is non-null.

​
Telling the two 400s apart

validation_error means merchant_reference was missing, empty, or over 128 characters — the payload reached us and failed validation. bad_request means the envelope was wrong, so nothing was ever validated: a missing or skewed x-timestamp, a body that is not {"data":"…"}, or a payload we could not decrypt with your encryption secret. If you are seeing this on every call, the problem is in your signing helper, not in your fields. A 403 is either an IP that is not on your allowlist or the payin product not being enabled on the account. A 429 means you are over 600 lookups per minute.
A reference that belongs to a different merchant returns not_found too. The endpoint never confirms that someone else’s order exists.
See Errors for the envelope shape shared by every endpoint.

​
Polling, if you must

The callback is the intended path and it is retried up to 8 times — but if you are recovering from a missed callback or reconciling a batch:
  • Look up on demand (a support query, an order older than expected), not on a fixed loop over every open order
  • Stop at the first settled status: paid, underpaid or overpaid are final for fulfilment
  • Keep polling expired orders only briefly. A late payment fires a callback anyway, and we keep re-checking lapsed payments on our side
If a callback never arrived and this endpoint reports a settled status, the money is in your balance — the delivery failed, not the payment. Check your callback URL is reachable and returning 2xx: see retries.

Authorizations

​
x-api-key
string
header
required

Identifies your account. Issued from Developer Tools in the dashboard.

Headers

​
x-timestamp
integer<int64>
required

Unix epoch in seconds — not milliseconds. Must be within ±5 minutes of our clock, which is what makes a captured request unusable later. Keep your client's clock NTP-synced.

Example:

1748023400

​
x-signature
string
required

HMAC-SHA256 over the signing string, hex encoded. The timestamp is part of what is signed, so a replayed body cannot be re-dated. See https://docs.pontisglobe.com/authentication for how it is built.

Example:

"2f8a9b4c1d7e0a3f6b8c2d5e9f1a4b7c0d3e6f9a2b5c8d1e4f7a0b3c6d9e2f5a"

Body

application/json
​
merchant_reference
string
required
Required string length: 1 - 128
Example:

"ORDER-1042"

Response

Current state of the payment.

​
ok
enum<boolean>
Available options:
true
​
data
object