> ## Documentation Index > Fetch the complete documentation index at: https://docs.i-pay.money/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a payment link > Read the state of a payment link from its reference. No key is required. > [!WARNING] > > This operation requires no key. Anyone who knows the reference can check the state of the link and, once a payment has been completed, the payer information it contains. Always generate this reference randomly and with high entropy (see [Create a hosted payment link](https://docs.i-pay.money/en/api-reference/payment-by-link/create-a-payment-link.md)), and never log it or display it in a context accessible to a third party not involved in this payment. * **Response shape.** It depends on the actual state of the link: a payment carried through to completion, a link still waiting for a first payment attempt, or a link that expired without a completed payment. A refund made afterwards does not change this shape: this operation is not a reliable indicator for detecting a refund. * **Expired link.** After thirty minutes without a completed payment, the lookup still responds `200`, with `has_expire` set to `true` and `status` set to `cancelled`. Treat this shape as a permanently unusable link, not as a transient error to retry. * **Unknown reference.** A reference that does not match any link returns `404`. Since the operation is public, brute-force enumeration is possible if the reference is not random enough: this is the reason for the warning above. Common error messages: [Errors](https://docs.i-pay.money/en/api-reference/errors.md). ## OpenAPI ````yaml en/openapi.yaml GET /external_payments/{reference} openapi: 3.1.0 info: title: iPayMoney Merchant API version: 1.0.0 description: >- v1 merchant contracts verified against the Rails routes, controllers and services. Partner contracts and non-operational v2 routes are not part of this public specification. Payment links must use private random references. servers: - url: https://i-pay.money/api/v1 description: Sandbox or Live depending on the headers and the key used security: [] tags: - name: Payments description: Creation and tracking of merchant transactions - name: Payment links description: Hosted payment links paths: /external_payments/{reference}: get: tags: - Payment links summary: Retrieve a payment link description: >- This route is currently accessible without a key and can return customer data. Use a randomly generated private reference, never a sequential order identifier. parameters: - name: reference in: path required: true description: High-entropy private reference, not published on the client side. schema: type: string minLength: 32 responses: '200': description: State of the link or of the associated payment content: application/json: schema: oneOf: - $ref: '#/components/schemas/ExternalPaymentStatus' - $ref: '#/components/schemas/ExternalPaymentWaiting' - $ref: '#/components/schemas/ExternalPaymentExpired' '404': description: Link not found content: application/json: schema: $ref: '#/components/schemas/Error' security: [] components: schemas: ExternalPaymentStatus: type: object description: >- Shape returned when a payment has been carried through to completion for this link. `status` can then only be `succeeded` or `failed`: on this operation, never `initiated`, `pending` or `refunded`. Edge case: a payment refunded afterwards is no longer attached to the link, and the operation then returns the shape of a link still waiting (`status: initiated`) instead of exposing the refund — do not use this operation as a reliable refund indicator. x-verified: >- Internal verification note (not intended for the public documentation). Verified on 2026-09-16 in `Api::V1::ExternalPaymentsController#show` (app/controllers/api/v1/external_payments_controller.rb:41-59, 63-92): this schema is only rendered for `most_recent_successful || most_recent_failed`, two scopes filtered on `payments.status = 2` and `payments.status = 3` respectively (lines 68-73), to be compared with the `Payment.status` enum (app/models/payment.rb:119 — initiated:0, pending:1, succeeded:2, failed:3, refunded:4). The existing enum was already correct, confirmed rather than fixed. If a `succeeded` payment is later marked `refunded` in the database, it no longer matches either of the two SQL scopes and this route then renders `ExternalPaymentWaiting`. properties: reference: type: string amount: type: integer country: type: string currency: type: string transaction_id: type: string msisdn: type: string customer_name: type: string status: type: string enum: - succeeded - failed created_at: type: string format: date-time ExternalPaymentWaiting: type: object properties: message: type: string status: type: string const: initiated reference: type: string page_url: type: string format: uri ExternalPaymentExpired: type: object properties: message: type: string has_expire: type: boolean const: true status: type: string const: cancelled reference: type: string Error: type: object properties: message: type: string status: type: string description: >- Only present on some application failures, e.g. a duplicate payment on `POST /payments`, where `status` is always `failed`. Absent from the other errors of this contract (e.g. 404 `Payment Not Found`, header/authentication errors). x-verified: >- Internal verification note (not intended for the public documentation). See `Live::PaymentService#error_response` (app/services/live/payment_service.rb:994-1005). example: failed ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.