Single payee, including upstream_status

GET /v1/remit/payees/{id} scope: remittances:read

On behalf of a member · x-on-behalf-of required

The list uses keyset cursors and has no ID-filter parameter. Without this endpoint, retrieving an older payee would require paging to the end or keeping a local cache. Caching would freeze name_mismatch and upstream_status at their creation-time values, even though both can change after creation.

Use this endpoint to inspect the current record after POST /v1/remit/payees returns outcome: review, indicating a holder-name mismatch with an existing record.

Path Parameters

Field	Type	Required	Description
`id`	string	Required	Payee ID. Optional `pye_` prefix; the remaining value must contain digits only.

Query Parameters

Field	Type	Required	Description
`line`	"express" \| "pobo"	Optional	Line used to determine `upstream_status`. The same payee has independent upstream records for the two lines; the personal line uses the member’s own subaccount context. Other fields are unaffected.

Field	Type	Required	Description
`x-on-behalf-of`	string	Required	Member on whose behalf the call is made.

Response

200OK

{
  "id": "pye_1042",
  "nickname": "房东",
  "entity_type": "INDIVIDUAL",
  "country": "GB",
  "currency": "GBP",
  "payment_method": "LOCAL",
  "clearing_system": "FASTER PAYMENTS",
  "summary": "Barclays ····4821",
  "bank_name": "Barclays",
  "account_holder": "MARY SMITH",
  "status": "active",
  "upstream_status": "active",
  "name_mismatch": false,
  "created_at": "2026-08-01T02:11:04Z"
}

404not_found: this member has no association with the payee, or it was removed. A nonnumeric id produces the same result deliberately.

Additional Details

`upstream_status`: whether the upstream accepts this payee

Our payee is provider-independent and local creation does not call the upstream. Upstream onboarding normally happens at dispatch; this field gives advance visibility into whether that step can succeed:

not_submitted: not sent upstream yet. Normal for a new payee, not an error. To submit early, call POST /v1/remit/payees/{id}/verify.
pending: submitted and being verified upstream, normally for a few minutes.
active: accepted upstream and eligible for payout. The upstream guide states: “Do not create payouts until the beneficiary is ACTIVE”.
failed: the upstream rejected the data itself; this is terminal. Retrying unchanged does not fix it. Ask the user to correct and recreate the payee; changed account identifiers produce a new entity. Alternatively, contact us.
deleted: the upstream record was deleted.
unknown: we cannot currently resolve the upstream identity for this line, because no provider is enabled or the member lacks a personal-line subaccount. This is not a payee issue; first enable the line. It is different from not_submitted.

⚠ We do not return the provider identity or upstream record ID. ⚠ status, active / blocked, is our independent local enable/disable flag.

Request

curl -X GET 'https://api.zinfra.vip/v1/remit/payees/{id}' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID'

const res = await fetch("https://api.zinfra.vip/v1/remit/payees/{id}", {
  method: "GET",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
  },
});
// Keep monetary amounts as strings, never numbers.
const data = await res.json();

import requests

res = requests.get(
    "https://api.zinfra.vip/v1/remit/payees/{id}",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
    },
)
# Use Decimal(str(...)) for amounts, not float.
data = res.json()

req, _ := http.NewRequest("GET", "https://api.zinfra.vip/v1/remit/payees/{id}",
    nil)
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
res, err := http.DefaultClient.Do(req)
// Decode amount fields as string, not float64.

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zinfra.vip/v1/remit/payees/{id}"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
// Use String / BigDecimal for amounts, not double.

$ch = curl_init('https://api.zinfra.vip/v1/remit/payees/{id}');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
  ],
]);
$res = curl_exec($ch);
// Use bcmath / strings for amounts, not floatval.

200

{
  "id": "pye_1042",
  "nickname": "房东",
  "entity_type": "INDIVIDUAL",
  "country": "GB",
  "currency": "GBP",
  "payment_method": "LOCAL",
  "clearing_system": "FASTER PAYMENTS",
  "summary": "Barclays ····4821",
  "bank_name": "Barclays",
  "account_holder": "MARY SMITH",
  "status": "active",
  "upstream_status": "active",
  "name_mismatch": false,
  "created_at": "2026-08-01T02:11:04Z"
}