3.2 Get PayIn Status

GET /api/v1/payins/{external_id}

Request

Headers

Parameter	Type	Required	Description
X-API-Key	string	Yes	API key.
X-Timestamp	string	Yes	Request time.
X-Signature	string	Yes	HMAC-SHA256(secret, timestamp + body). For GET requests body is empty.

Path

Parameter	Type	Required	Description
external_id	string	Yes	PayIn identifier provided at creation.

Query

Parameter	Type	Required	Description
shop_code	string	No	Shop code. If omitted, lookup uses the merchant's default active shop.

Example request

GET /api/v1/payins/PIN-BDT-001?shop_code=your_bdt_shop

Response

Fields

Empty paymentData is omitted from the response.

Parameter	Type	Description
id	number	Payfield operation ID.
external_id	string	PayIn identifier provided at creation.
shop_code	string	Shop code used for routing.
status	string	Current merchant-facing payin status.
amount	string	PayIn amount.
currency	string	PayIn currency.
updated_at	string	Last update timestamp.
paymentData	object	Shop-schema output, when configured and non-empty.

Statuses

Status	Description
pending	Created or still in progress from the merchant view.
success	Completed successfully.
failed	Processing finished with an error.
canceled	The user canceled the operation.
refunded	The amount was refunded after completion.
expired	The time for completing the payin expired.

Example response

Success

{
  "id": 12345,
  "external_id": "PIN-BDT-001",
  "shop_code": "your_bdt_shop",
  "status": "pending",
  "amount": "5000.00",
  "currency": "BDT",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

Error

{
  "message": "PayIn not found",
  "code": "not_found",
  "error": {
    "code": "not_found",
    "message": "PayIn not found"
  }
}