> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pontisglobe.com/llms.txt
> Use this file to discover all available pages before exploring further.
# /api/v1/beneficiaries/deleteBeneficiary
> Archive a saved recipient so it can no longer be used for new payouts.
The field above is what you **encrypt**, not what goes on the wire. The body is always
`{ "data": "" }` — see [Authentication](/authentication).
**POST, not DELETE.** The consumer API carries an AES-encrypted request body, which a DELETE
cannot carry reliably — so the action is in the path and the id is in the encrypted payload.
## This archives, it does not erase
The beneficiary's `status` becomes `archived`. It can no longer be selected for a new payout, and
payouts that already used it keep their own snapshot of the recipient — which is what preserves the
audit trail on money that has already moved.
There is no un-archive endpoint. Save the recipient again if you need it back.
## Example request
The snippets assume you have already encrypted the body and signed the request — see the
[Quickstart](/quickstart) for the full helper in Node and Python.
```js Node theme={null}
const archived = await call(
'/api/v1/beneficiaries/deleteBeneficiary',
{ beneficiary_id: 'b7c1e2a4-9d3e-4a71-b6c8-5e2f0a7d1934' },
jwt,
)
```
```python Python theme={null}
status, body = call('/api/v1/beneficiaries/deleteBeneficiary', {
'beneficiary_id': 'b7c1e2a4-9d3e-4a71-b6c8-5e2f0a7d1934',
}, jwt)
```
```bash cURL theme={null}
curl -X POST "https://api.pontisglobe.com/api/v1/beneficiaries/deleteBeneficiary" \
-H "content-type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1748023400" \
-H "x-signature: 2f8a9b…" \
-H "authorization: Bearer YOUR_JWT" \
-d '{"data":""}'
```
See [Beneficiaries](/beneficiaries) for how saving and reusing recipients fits together, and
[Errors](/errors) for the envelope shape shared by every endpoint.
## OpenAPI
````yaml openapi.yaml POST /api/v1/beneficiaries/deleteBeneficiary
openapi: 3.1.0
info:
title: PontisGlobe API
version: 1.0.0
summary: Accept stablecoin payments and send cross-border payouts.
description: |
Two products on one balance.
**Global Collections** — accept USDT and USDC through a hosted checkout.
**Global Payouts** — pay out in local currency across 50+ countries.
Every endpoint is `POST`, authenticated with an API key and an HMAC-SHA256
signature, and carries an AES-256-GCM encrypted body. Payout and beneficiary
endpoints additionally require a short-lived JWT obtained from
`/api/v1/user/login`.
## Request bodies are encrypted
The fields documented on each endpoint are what you **encrypt**, not what
goes on the wire. Every request body is a single envelope:
```json
{ "data": "" }
```
So a client that posts the documented JSON directly will be rejected before
validation. Read
[Authentication](https://docs.pontisglobe.com/authentication) and build the
envelope first — it is about fifteen lines of helper code, and the docs give
it in Node and Python.
contact:
name: PontisGlobe Support
url: https://www.pontisglobe.com/contact
servers:
- url: https://api.pontisglobe.com
description: Live. Real money.
- url: https://sandbox.pontisglobe.com
description: |
Sandbox. Deterministic outcomes driven by the trailing cents of
`source_amount` — see https://docs.pontisglobe.com/sandbox.
security:
- ApiKeyAuth: []
tags:
- name: Authentication
description: Exchange credentials for a short-lived JWT.
- name: Payouts
description: Send money to bank accounts and mobile money in 50+ countries.
- name: Beneficiaries
description: Save a recipient once, then pay them by id.
- name: Payins
description: Accept stablecoin payments through a hosted checkout.
paths:
/api/v1/beneficiaries/deleteBeneficiary:
post:
tags:
- Beneficiaries
summary: Archive a beneficiary
description: |
Archived, not deleted — existing payouts keep their audit trail, and the
record can no longer be used for new ones.
operationId: deleteBeneficiary
parameters:
- $ref: '#/components/parameters/TimestampHeader'
- $ref: '#/components/parameters/SignatureHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- beneficiary_id
properties:
beneficiary_id:
type: string
format: uuid
responses:
'200':
description: Archived.
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
enum:
- true
data:
$ref: '#/components/schemas/BeneficiaryRef'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/BeneficiaryNotFound'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
security:
- ApiKeyAuth: []
BearerAuth: []
components:
parameters:
TimestampHeader:
name: x-timestamp
in: header
required: true
description: |
Unix epoch **in seconds** — not milliseconds. Must be within ±5 minutes
of our clock, which is what makes a captured request unusable later.
Keep your client's clock NTP-synced.
schema:
type: integer
format: int64
example: 1748023400
SignatureHeader:
name: x-signature
in: header
required: true
description: |
HMAC-SHA256 over the signing string, hex encoded. The timestamp is part
of what is signed, so a replayed body cannot be re-dated. See
https://docs.pontisglobe.com/authentication for how it is built.
schema:
type: string
example: 2f8a9b4c1d7e0a3f6b8c2d5e9f1a4b7c0d3e6f9a2b5c8d1e4f7a0b3c6d9e2f5a
schemas:
BeneficiaryRef:
type: object
required:
- beneficiary_id
- status
properties:
beneficiary_id:
type: string
format: uuid
status:
type: string
enum:
- active
- archived
Error:
type: object
required:
- ok
- request_id
- error
properties:
ok:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
description: |
Identifies this exact request in our logs. Quote it when contacting
support — it is the fastest path to an answer.
example: 8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Stable, machine-readable. Branch on this, never on `message`.
example: insufficient_funds
message:
type: string
description: Human-readable. Wording may change without notice.
example: 'Insufficient available balance. Available: 5.00 USDT'
responses:
BadRequest:
description: >-
`validation_error` — schema mismatch. Fix and retry; do not retry
unchanged.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: >-
`unauthorized` or `jwt_expired` — bad credentials or an expired JWT.
Re-login.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BeneficiaryNotFound:
description: |
`beneficiary_not_found`. Also returned when the beneficiary belongs to
another account — the API never confirms someone else's record exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: '`rate_limited` — back off and retry with a longer interval.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ServerError:
description: '`internal_error` — contact support quoting `request_id`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: Identifies your account. Issued from Developer Tools in the dashboard.
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
Short-lived token from `/api/v1/user/login`, bound to your account and
mode. Expires in 900 seconds.
````