# Retrieve Payment

***

### Retrieve a Payment

The `GET /payments/{paymentId}` endpoint retrieves the current state of an existing payment.

This endpoint is used to:

* Track execution progress after submission
* Confirm final payment status
* Reconcile payments in backend systems
* Safely verify outcomes without triggering execution

Retrieving a payment **does not modify or execute** it.

***

### Endpoint

```shellscript
GET /payments/{paymentId}
```

***

### Headers

```http
x-publishable-key: pk_test_123456
```

***

### Path Parameters

| Name        | Type   | Required | Description                          |
| ----------- | ------ | -------- | ------------------------------------ |
| `paymentId` | string | Yes      | The unique identifier of the payment |

Example:

```shellscript
GET /payments/pay_456
```

***

### Response

A successful request returns the current payment object.

```json
{
  "payment": {
    "paymentId": "pay_456",
    "status": "SUCCESS",
    "payer": {
      "address": "payer.near",
      "chainId": "near-mainnet"
    },
    "recipient": {
      "address": "example.near",
      "chainId": "near-mainnet"
    },
    "asset": {
      "assetId": "nep141:wrap.near",
      "amount": "1000000000000000000000000"
    },
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:02:00.000Z"
  }
}
```

***

### Payment Status

The payment status will be one of:

* `PENDING` — Execution has been initiated but not yet finalised
* `SUCCESS` — Payment completed successfully
* `FAILED` — Payment failed during execution

A payment should be considered **final** only when it reaches either `SUCCESS` or `FAILED`.

***

### Polling and Confirmation

After submitting a payment, you may poll this endpoint to monitor progress.

Recommended practices:

* Poll at reasonable intervals (e.g. every few seconds)
* Stop polling once the payment reaches a final state
* Use this endpoint as the authoritative source of payment status

***

### Notes

* This endpoint is **safe to call multiple times**
* It does not trigger execution or retries
* Always rely on the retrieved status rather than client-side assumptions
* Backend systems should use this endpoint for fulfillment and reconciliation

***

### Error Response Example

```json
{
  "code": "NOT_FOUND",
  "message": "Payment not found."
}
```