> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pontisglobe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/v1/payouts/getPayoutStatus

> Poll the current state of a transaction you previously created.

```
POST /api/v1/payouts/getPayoutStatus
```

## Headers

| Header          | Required             |
| --------------- | -------------------- |
| `x-api-key`     | yes                  |
| `x-timestamp`   | yes                  |
| `x-signature`   | yes                  |
| `authorization` | yes — `Bearer <JWT>` |
| `content-type`  | yes                  |

## Request body

```json theme={null}
{ "data": "<encrypted blob of the payload below>" }
```

Decrypted payload:

| Field            | Type   | Required | Notes                                                                                                         |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `transaction_id` | string | yes      | The `transaction_id` you received from `sendPayoutRequest`. Live IDs are UUIDs; sandbox IDs start with `sb_`. |

## Example request

<Info>
  All examples assume you've already encrypted the body and signed the request — see the [Quickstart](/quickstart) for the full helper in Node and Python.
</Info>

<CodeGroup>
  ```js Node theme={null}
  const status = await call(
    '/api/v1/payouts/getPayoutStatus',
    { transaction_id: '029b2038-6166-4bea-80a9-f1a2425a85eb' },
    jwt,
  )
  ```

  ```python Python theme={null}
  status, body = call(
      '/api/v1/payouts/getPayoutStatus',
      {'transaction_id': '029b2038-6166-4bea-80a9-f1a2425a85eb'},
      jwt,
  )
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.pontisglobe.com/api/v1/payouts/getPayoutStatus" \
    -H "content-type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "x-timestamp: 1748023400" \
    -H "x-signature: 2f8a9b…" \
    -H "authorization: Bearer eyJhbGciOi…" \
    -d '{"data":"<encrypted blob>"}'
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("POST",
    "https://api.pontisglobe.com/api/v1/payouts/getPayoutStatus",
    strings.NewReader(`{"data":"`+encryptedBody+`"}`))
  req.Header.Set("content-type", "application/json")
  req.Header.Set("x-api-key", apiKey)
  req.Header.Set("x-timestamp", timestamp)
  req.Header.Set("x-signature", signature)
  req.Header.Set("authorization", "Bearer "+jwt)
  res, _ := http.DefaultClient.Do(req)
  ```

  ```java Java theme={null}
  HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.pontisglobe.com/api/v1/payouts/getPayoutStatus"))
    .header("content-type", "application/json")
    .header("x-api-key", apiKey)
    .header("x-timestamp", timestamp)
    .header("x-signature", signature)
    .header("authorization", "Bearer " + jwt)
    .POST(HttpRequest.BodyPublishers.ofString("{\"data\":\"" + encryptedBody + "\"}"))
    .build();
  HttpResponse<String> res = HttpClient.newHttpClient().send(req, BodyHandlers.ofString());
  ```

  ```kotlin Kotlin theme={null}
  val req = Request.Builder()
    .url("https://api.pontisglobe.com/api/v1/payouts/getPayoutStatus")
    .post("""{"data":"$encryptedBody"}""".toRequestBody("application/json".toMediaType()))
    .addHeader("x-api-key", apiKey)
    .addHeader("x-timestamp", timestamp)
    .addHeader("x-signature", signature)
    .addHeader("authorization", "Bearer $jwt")
    .build()
  val res = OkHttpClient().newCall(req).execute()
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.pontisglobe.com/api/v1/payouts/getPayoutStatus');
  curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      'content-type: application/json',
      "x-api-key: $apiKey",
      "x-timestamp: $timestamp",
      "x-signature: $signature",
      "authorization: Bearer $jwt",
    ],
    CURLOPT_POSTFIELDS => json_encode(['data' => $encryptedBody]),
    CURLOPT_RETURNTRANSFER => true,
  ]);
  $res = curl_exec($ch);
  ```

  ```ruby Ruby theme={null}
  uri = URI('https://api.pontisglobe.com/api/v1/payouts/getPayoutStatus')
  req = Net::HTTP::Post.new(uri, {
    'content-type' => 'application/json',
    'x-api-key' => api_key,
    'x-timestamp' => timestamp,
    'x-signature' => signature,
    'authorization' => "Bearer #{jwt}",
  })
  req.body = { data: encrypted_body }.to_json
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
  ```

  ```csharp C# theme={null}
  var req = new HttpRequestMessage(HttpMethod.Post,
    "https://api.pontisglobe.com/api/v1/payouts/getPayoutStatus");
  req.Headers.Add("x-api-key", apiKey);
  req.Headers.Add("x-timestamp", timestamp);
  req.Headers.Add("x-signature", signature);
  req.Headers.Add("authorization", $"Bearer {jwt}");
  req.Content = new StringContent($"{{\"data\":\"{encryptedBody}\"}}",
    Encoding.UTF8, "application/json");
  var res = await new HttpClient().SendAsync(req);
  ```

  ```swift Swift theme={null}
  var req = URLRequest(url: URL(string: "https://api.pontisglobe.com/api/v1/payouts/getPayoutStatus")!)
  req.httpMethod = "POST"
  req.setValue("application/json", forHTTPHeaderField: "content-type")
  req.setValue(apiKey, forHTTPHeaderField: "x-api-key")
  req.setValue(timestamp, forHTTPHeaderField: "x-timestamp")
  req.setValue(signature, forHTTPHeaderField: "x-signature")
  req.setValue("Bearer \(jwt)", forHTTPHeaderField: "authorization")
  req.httpBody = #"{"data":"\#(encryptedBody)"}"#.data(using: .utf8)
  let (data, _) = try await URLSession.shared.data(for: req)
  ```
</CodeGroup>

## Responses

### 200 — Success

```json theme={null}
{
  "ok": true,
  "data": {
    "transaction_id": "029b2038-6166-4bea-80a9-f1a2425a85eb",
    "status": "completed",
    "status_message": null
  }
}
```

`status` is one of:

| Value              | Meaning                                               |
| ------------------ | ----------------------------------------------------- |
| `pending_approval` | Awaiting manual approval                              |
| `pending`          | Approved and queued for processing                    |
| `processing`       | Submitted to the payment network, awaiting settlement |
| `completed`        | Payment was successfully delivered                    |
| `failed`           | Payment could not be delivered                        |
| `rejected`         | Transaction was rejected before processing            |
| `reversed`         | A previously delivered transaction was returned       |
| `canceled`         | Transaction was canceled before processing            |

`status_message` is non-null only on `failed`, `rejected`, `reversed`, `canceled`.

### 400 — validation\_error

`transaction_id` missing or malformed (must be a UUID or start with `sb_`).

### 401 — unauthorized / jwt\_expired

Bad/missing JWT.

### 404 — not\_found

Transaction doesn't exist or belongs to a different account.

```json theme={null}
{
  "ok": false,
  "request_id": "01J9F5Z4X7Y3K2B1Q0M8N7V6T5",
  "error": { "code": "not_found", "message": "Transaction not found" }
}
```

### 429 — rate\_limited

Throttle your polling.

## Recommendation

Polling works, but **register a [Callback URL](/callbacks)** to stop polling entirely. We POST to you as soon as the transaction reaches a final state.