Retrieve a Beneficiary - Anton Payments

GET

beneficiaries

{id}

Retrieve a beneficiary

curl --request GET \
  --url https://api.antonpayments.com/v1/beneficiaries/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'DPoP: <api-key>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>', DPoP: '<api-key>'}};

fetch('https://api.antonpayments.com/v1/beneficiaries/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.antonpayments.com/v1/beneficiaries/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "DPoP: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.antonpayments.com/v1/beneficiaries/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("DPoP", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1",
  "merchant_id": "mer_01HX8Z9K0M2N3P4Q5R6S7T8UZZ",
  "type": "individual",
  "status": "active",
  "display_name": "Jane Smith",
  "country": "GB",
  "external_ref": "contractor-1042",
  "metadata": {
    "department": "engineering"
  },
  "created_at": "2026-04-15T14:30:00Z",
  "updated_at": "2026-04-15T14:30:00Z"
}

Authorizations

Authorization

string

header

required

OAuth 2.0 client_credentials grant (RFC 6749 §4.4) bound to a DPoP keypair (RFC 9449).

Flow (every authenticated /v1 call requires both an access token AND a fresh per-request DPoP proof):

Register a credential via the merchant portal. Anton issues a client_id (ant_oc_<env>_<32hex>) and a client_secret (ant_ocs_<env>_<48hex>, shown ONCE). The portal generates an ES256 or Ed25519 DPoP keypair in your browser; you store the private half.
Mint an access token: POST /oauth/token with Authorization: Basic <client_id:client_secret> and Content-Type: application/x-www-form-urlencoded. Body: grant_type=client_credentials. A DPoP header carrying a proof signed for the token endpoint is required (no ath claim on this proof).
Use the token: send Authorization: DPoP <access_token> plus a fresh DPoP: <proof> header on every /v1 request. The proof JWT MUST carry htm (request method), htu (request URL, no query/fragment), iat (within ±60s), jti (unique within 5 min), and ath (SHA-256 of the access token, base64url).

Tokens expire in 1 hour in production / staging and 8 hours in sandbox. There are no refresh tokens — call /oauth/token again with your secret. Anton's public signing key is published at /.well-known/jwks.json.

OpenAPI 3.0 has no native DPoP scheme; this declaration plus dpopHeader together convey both the access-token Authorization and the per-request proof header.

DPoP

string

header

required

Per-request DPoP proof JWT (RFC 9449). MUST accompany the Authorization: DPoP <access_token> header on every protected operation. The proof is signed by the merchant's private DPoP key and carries htm, htu, iat, jti, and ath claims.

Path Parameters

string

required

Beneficiary ID (prefixed ben_).

Pattern: ^ben_[a-zA-Z0-9]+$

Example:

"ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1"

Response

Beneficiary.

A person or business you pay. PII is tokenized in Basis Theory on creation — raw identifiers are never returned in this response. Use GET /v1/beneficiaries/{id}/pii to retrieve detokenized PII for a beneficiary you own.

string

required

Pattern: ^ben_[a-zA-Z0-9]+$

Example:

"ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1"

merchant_id

string

required

Pattern: ^mer_[a-zA-Z0-9]+$

type

enum<string>

required

Available options:

individual,

business

status

enum<string>

required

active — usable for payouts.
archived — soft-disabled by the merchant; not usable. Can be restored.
blocked — blocked by compliance. Not usable and cannot be restored via the API.

Available options:

active,

archived,

blocked

display_name

string

required

Derived from the tokenized PII on creation. For individuals, a concatenation of name fields; for businesses, the legal name.

Example:

"Jane Smith"

country

string

required

ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Z]{2}$

Example:

"US"

created_at

string<date-time>

required

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

updated_at

string<date-time>

required

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

external_ref

string | null

Your own reference, if you supplied one at creation.

metadata

object

Show child attributes

Update a BeneficiaryUpdate mutable fields on a beneficiary: `display_name`, `country`, `external_ref`, and `metadata`. PII cannot be updated via this endpoint — use `PUT /v1/beneficiaries/{id}/pii` instead, since PII is tokenized. Fields not present in the request body are left unchanged.

⌘I

Retrieve a beneficiary

curl --request GET \
  --url https://api.antonpayments.com/v1/beneficiaries/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'DPoP: <api-key>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>', DPoP: '<api-key>'}};

fetch('https://api.antonpayments.com/v1/beneficiaries/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.antonpayments.com/v1/beneficiaries/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "DPoP: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.antonpayments.com/v1/beneficiaries/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("DPoP", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1",
  "merchant_id": "mer_01HX8Z9K0M2N3P4Q5R6S7T8UZZ",
  "type": "individual",
  "status": "active",
  "display_name": "Jane Smith",
  "country": "GB",
  "external_ref": "contractor-1042",
  "metadata": {
    "department": "engineering"
  },
  "created_at": "2026-04-15T14:30:00Z",
  "updated_at": "2026-04-15T14:30:00Z"
}