> ## Documentation Index
> Fetch the complete documentation index at: https://docs.globalstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deactivate a wallet credential

> Deactivates a wallet credential by flipping its `status` to `disabled`. The credential
record is preserved — list and get continue to return it.

The path ids are GlobalStack external identifiers: the wallet (`wal_…`) and the credential
(`wcr_…`).

An optional JSON body `{ "reason": "…" }` (max 255 chars) records why the credential was
deactivated in `disabled_reason`.

### Response

```json
{
  "status": true,
  "message": "Wallet credential has been successfully deactivated",
  "code": "ok",
  "data": { "id": "wcr_01HXYZABC1234567890ABCDEFG", "success": true },
  "meta": { "request_id": "req_…", "timestamp": "…", "version": "1" }
}
```

### Status preconditions

- `pending` → disabled.
- `active` → disabled.
- `frozen` → `409 invalid_status` (a merchant cannot clear an internal/compliance freeze).
- `disabled` → `409 invalid_status` (not idempotent).

### Errors

- `400 invalid_input` — `wal_…` or `wcr_…` id is malformed.
- `401 authentication_failed` — invalid or missing API key.
- `404 not_found` — wallet or credential does not exist in this integration.
- `409 invalid_status` — credential is already disabled or is frozen.

### Example

```
DELETE /v1/wallets/wal_01HXYZABC1234567890ABCDEFG/credentials/wcr_01HXYZABC1234567890ABCDEFG
```




## OpenAPI

````yaml /api-reference/openapi.json delete /v1/wallets/{id}/credentials/{credentialId}
openapi: 3.0.0
info:
  title: GlobalStack API
  version: 1.0.0
  description: >
    # Introduction


    GlobalStack API for cross-border payments powered by stablecoin rails.


    Getting started: authenticate with a Bearer token, make your first call to

    `GET /v1/currencies`, and explore.


    **Key operations:**


    - **Onramp** — convert external fiat into crypto credited to a wallet.

    - **Offramp** — convert crypto from a wallet into fiat delivered to a
    beneficiary.

    - **Conversion** — move value between two wallets belonging to the same
    customer.

    - **Transfer** — send crypto from a wallet to an external address.

    - **Deposit** — receive external crypto into a wallet via a deposit address.


    See the sections below for authentication, response shape, idempotency,

    references, metadata, and webhooks.


    ## Authentication


    All API requests require a Bearer token in the `Authorization` header:


    ```

    Authorization: Bearer gsa_sk_live_your_api_key

    ```


    API keys use the `gsa_sk_live_` prefix.


    API keys are scoped to a single merchant account. All resources created with

    a key belong to that merchant. Keep your keys secret — do not expose them in

    client-side code or public repositories.


    To rotate a key, generate a new one from your dashboard and update your

    integration before revoking the old key.


    ## API Response Shape


    Every response — success or failure — follows the same envelope:


    ```json

    {
      "status": true,
      "message": "Onramp created successfully",
      "code": "ok",
      "data": { },
      "meta": {
        "request_id": "req_01ABC...",
        "timestamp": "2026-04-22T02:00:00Z",
        "version": "1"
      }
    }

    ```


    **Fields:**


    - `status` (boolean) — whether the HTTP call succeeded. This is not the
      business status of the underlying resource.
    - `message` (string) — human-readable explanation for developers and logs.
      Do not show to end users.
    - `code` (string) — stable machine-readable result. `ok` on success, or an
      error code like `bad_request`.
    - `data` — the resource payload on success (object, array, or scalar).
    `null`
      on failure.
    - `meta` — request-scoped metadata, always present. Includes `request_id`
      (quote this in support tickets), `timestamp`, and `version`. On list
      endpoints, also includes `page`, `per_page`, `total`, `has_more`. On
      validation errors, includes `errors` array and `next_steps`.

    Error responses include `next_steps` in `meta` with an `action` string and a

    `docs_url` link:


    ```json

    {
      "status": false,
      "message": "Your request has validation errors.",
      "code": "bad_request",
      "data": null,
      "meta": {
        "request_id": "req_01ABC...",
        "timestamp": "2026-04-22T02:00:00Z",
        "version": "1",
        "errors": [
          { "field": "amount", "code": "required", "message": "Amount is required." }
        ],
        "next_steps": {
          "action": "Review the request and retry with corrected parameters.",
          "docs_url": "https://docs.globalstack.io/errors#bad_request"
        }
      }
    }

    ```


    ## Idempotency


    Pass an `Idempotency-Key` header on any create endpoint to make the request

    safely retryable:


    ```

    Idempotency-Key: your-unique-key-here

    ```


    **Rules:**


    - Same key + same body = returns the original response (no side effects).

    - Same key + different body = returns `idempotency_conflict` (409).

    - Keys are scoped to your merchant account.

    - Keys expire after 24 hours.


    Use idempotency keys for any operation that creates a resource or moves

    money. This protects against network retries, duplicate webhooks, and

    client-side retry loops.


    ## Rate Limits


    Requests over the rate limit are rejected with HTTP `429` and the error code

    `rate_limited`:


    ```json

    {
      "status": false,
      "message": "Too many requests. Slow down and retry shortly.",
      "code": "rate_limited"
    }

    ```


    **Money-movement writes** (creating transfers, offramps, conversions, or

    wallet operations) are limited **per merchant account** — the budget is

    shared across all of your API keys and dashboard sessions. Reads are not

    limited.


    On a `429`, back off and retry with jitter; for money movement, reuse the

    same `Idempotency-Key` so the retry stays safe.


    ## Reference


    Every money movement operation (onramp, offramp, conversion, transfer)

    accepts an optional `reference` field — a merchant-supplied identifier that

    is unique per merchant account.


    ```json

    {
      "reference": "INV-2026-001",
      "wallet_id": "wal_..."
    }

    ```


    If you omit `reference`, the API generates one automatically (prefixed

    `ref_`).


    References are unique per merchant — attempting to create two operations

    with the same reference returns the existing operation (same behavior as

    idempotency, but permanent and not time-limited).


    Use `reference` to correlate GlobalStack operations with your own system

    records (invoices, orders, payouts).


    ## Metadata


    Most create endpoints accept an optional `metadata` object — a flat set of

    string key/value pairs stored on the resource:


    ```json

    {
      "metadata": {
        "order_id": "ord_12345",
        "customer_email": "alice@example.com"
      }
    }

    ```


    Metadata is returned on every GET response and in webhook payloads. It is

    not used by GlobalStack for processing — it exists for your own

    record-keeping.


    Resources that accept metadata: customers, wallets, senders, beneficiaries,

    wallet credentials, deposit addresses, onramps, offramps, conversions, and

    transfers.


    ## Webhook Signatures


    Every webhook delivery is signed so you can verify it came from GlobalStack
    and

    was not tampered with in transit. Signatures follow the

    [Svix](https://docs.svix.com/receiving/verifying-payloads/how) standard, so
    you

    can verify them with any Svix library — or manually with the construction
    below.


    Each delivery carries three headers:


    ```

    svix-id: msg_2gT8sV...          # unique message id (the body's event_id,
    prefixed msg_)

    svix-timestamp: 1718960400      # unix seconds when the delivery was signed

    svix-signature: v1,g0hM9SsE...  # space-separated list of
    v1,<base64-signature>

    ```


    Your signing secret (prefixed `whsec_`) is returned in plaintext **exactly

    once** — when you create a webhook endpoint or rotate its secret. Store it

    securely; you cannot retrieve it again.


    **Verify with a Svix library (recommended):**


    ```python

    from svix.webhooks import Webhook


    wh = Webhook(signing_secret)                            # the whsec_...
    value

    payload = wh.verify(raw_request_body, request_headers)  # raises on a bad
    signature

    ```


    **Verify manually:**


    1. Build the signed content by joining the id, timestamp, and the **raw**
       request body with dots:

       ```
       signed_content = svix_id + "." + svix_timestamp + "." + raw_body
       ```

    2. Take your signing secret, drop the `whsec_` prefix, and base64-decode the
       remainder — those bytes are your HMAC key.

    3. Compute `base64(HMAC-SHA256(key, signed_content))`.


    4. The `svix-signature` header is a space-separated list of `v1,<signature>`
       entries (an endpoint can have more than one valid secret during a rotation).
       Compare your computed value against each entry's signature — the part after
       `v1,` — using a constant-time comparison, and accept if any matches.

    5. Reject deliveries whose `svix-timestamp` differs from your current time
    by
       more than a few minutes, to guard against replay.

    The body's `event_id` equals the `svix-id` without its `msg_` prefix, so you
    can

    use either to deduplicate redelivered events.


    ## Request IDs


    Every response carries an `X-Request-Id` header (also surfaced in

    `meta.request_id`). Include the value when reporting issues — it scopes

    backend logs to your specific request.


    You may also send your own `X-Request-Id` header. Values matching

    `^[A-Za-z0-9_-]{1,128}$` are honored verbatim; anything else is replaced
    with

    a generated id.


    ## Versioning


    Public endpoints are versioned under `/v1/`. Breaking changes ship under a
    new

    major version; additive changes (new fields, new endpoints) ship under the

    existing version.
  contact:
    name: Paystack Cross-Border
    url: https://globalstack.io
servers:
  - url: https://api.globalstack.io
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Supported Countries
  - name: Supported Currencies
  - name: Customers
  - name: Wallets
  - name: Beneficiaries
  - name: Quotes
  - name: Onramps
  - name: Offramps
  - name: Conversions
  - name: Transfers
  - name: Transactions
  - name: Notification Webhooks
  - name: Me
paths:
  /v1/wallets/{id}/credentials/{credentialId}:
    delete:
      tags:
        - Wallets
      summary: Deactivate a wallet credential
      description: >
        Deactivates a wallet credential by flipping its `status` to `disabled`.
        The credential

        record is preserved — list and get continue to return it.


        The path ids are GlobalStack external identifiers: the wallet (`wal_…`)
        and the credential

        (`wcr_…`).


        An optional JSON body `{ "reason": "…" }` (max 255 chars) records why
        the credential was

        deactivated in `disabled_reason`.


        ### Response


        ```json

        {
          "status": true,
          "message": "Wallet credential has been successfully deactivated",
          "code": "ok",
          "data": { "id": "wcr_01HXYZABC1234567890ABCDEFG", "success": true },
          "meta": { "request_id": "req_…", "timestamp": "…", "version": "1" }
        }

        ```


        ### Status preconditions


        - `pending` → disabled.

        - `active` → disabled.

        - `frozen` → `409 invalid_status` (a merchant cannot clear an
        internal/compliance freeze).

        - `disabled` → `409 invalid_status` (not idempotent).


        ### Errors


        - `400 invalid_input` — `wal_…` or `wcr_…` id is malformed.

        - `401 authentication_failed` — invalid or missing API key.

        - `404 not_found` — wallet or credential does not exist in this
        integration.

        - `409 invalid_status` — credential is already disabled or is frozen.


        ### Example


        ```

        DELETE
        /v1/wallets/wal_01HXYZABC1234567890ABCDEFG/credentials/wcr_01HXYZABC1234567890ABCDEFG

        ```
      operationId: CredentialController.deactivate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            pattern: '[^\/#\?]+?'
            type: string
        - in: path
          name: credentialId
          required: true
          schema:
            pattern: '[^\/#\?]+?'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeactivateCredentialDto'
        description: DeactivateCredentialDto
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessEnvelope'
                  - type: object
                    required:
                      - data
                      - meta
                    properties:
                      message:
                        type: string
                        example: Wallet credential has been successfully deactivated
                      data:
                        $ref: '#/components/schemas/DeactivateCredentialResponse'
                      meta:
                        $ref: '#/components/schemas/ApiResponseMetaSchema'
          description: Wallet credential has been successfully deactivated
        '400':
          description: >-
            Bad request. `invalid_input` covers a malformed `wal_…` or `wcr_…`
            path id; `bad_request` covers a `reason` body that fails validation.
            Branch on the `code` field of the response envelope.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - invalid_input
                          - bad_request
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - authentication_failed
        '404':
          description: Wallet or credential not found in this integration
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - not_found
        '409':
          description: >-
            Credential cannot be deactivated — it is already disabled, or it is
            frozen.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - invalid_status
components:
  schemas:
    DeactivateCredentialDto:
      properties:
        reason:
          maxLength: 255
          type: string
      type: object
    ApiSuccessEnvelope:
      properties:
        status:
          type: boolean
          enum:
            - true
          example: true
        message:
          type: string
          description: Human-readable summary
          example: Resource fetched successfully
        code:
          type: string
          enum:
            - ok
          example: ok
      type: object
      required:
        - status
        - message
        - code
    DeactivateCredentialResponse:
      properties:
        id:
          type: string
          description: Credential external id (prefixed wcr_).
          example: wcr_01HXYZABC1234567890ABCDEFG
        success:
          type: boolean
          enum:
            - true
          example: true
      type: object
      required:
        - id
        - success
    ApiResponseMetaSchema:
      properties:
        request_id:
          type: string
          description: ULID-prefixed identifier for this request
          example: req_01HXYZ4K5ABCDEFGHJKLMNPQRS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-14T15:43:55.732Z'
        version:
          type: string
          description: Major API version parsed from /vN/
          example: '1'
      type: object
      required:
        - request_id
        - timestamp
        - version
    ApiErrorEnvelope:
      properties:
        status:
          type: boolean
          enum:
            - false
          example: false
        message:
          type: string
          description: Human-readable failure summary
          example: Resource not found
        code:
          type: string
          description: Stable error code for branching logic
          example: not_found
        data:
          type: object
          nullable: true
          example: null
        meta:
          $ref: '#/components/schemas/ApiErrorMetaSchema'
      type: object
      required:
        - status
        - message
        - code
        - data
        - meta
    ApiErrorMetaSchema:
      properties:
        next_steps:
          $ref: '#/components/schemas/NextStepsSchema'
        request_id:
          type: string
          description: ULID-prefixed identifier for this request
          example: req_01HXYZ4K5ABCDEFGHJKLMNPQRS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-14T15:43:55.732Z'
        version:
          type: string
          description: Major API version parsed from /vN/
          example: '1'
      type: object
      required:
        - next_steps
        - request_id
        - timestamp
        - version
    NextStepsSchema:
      properties:
        action:
          type: string
          description: Suggested action for the caller
          example: Verify the resource identifier and retry.
        docs_url:
          type: string
          format: uri
          example: https://docs.globalstack.io/errors#not_found
      type: object
      required:
        - action
        - docs_url
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key issued during merchant onboarding.

````