> ## Documentation Index
> Fetch the complete documentation index at: https://direct-api.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Reveal card details

> Required API-key scope: `cards:read_vault`.

Returns a short-lived link to a secure, Reap-hosted page that shows the card number, expiry date and CVV, for you to display in an iframe. The link expires after 1 minute, and the card details never pass through your servers. Always call this endpoint from your backend, and only for people allowed to see the card. See [Card details](/concepts/card-details).

## Display card details securely

This endpoint returns one short-lived URL for a Reap-hosted card-details widget. The widget displays the card number, expiry date, and CVV together and includes a control for copying the card number. It does not display the billing address. Sensitive card data is never returned to your backend or parent-page JavaScript.

> [!WARNING]
>
> Call this endpoint from your backend. Never expose your API key in browser or mobile application code.

**1. Request an access URL from your backend**

Call the endpoint when an authenticated and authorized user opens the card-details view. Keep the API key in your backend's secrets manager.

```ts
const apiKey = process.env.REAP_DIRECT_API_KEY;
if (!apiKey) {
  throw new Error("REAP_DIRECT_API_KEY is not configured");
}

const response = await fetch(
  `https://api.global.direct.reap.global/2026-07-13/cards/${encodeURIComponent(cardId)}/reveal`,
  {
    method: "POST",
    headers: {
      "x-api-key": apiKey,
    },
  },
);

if (!response.ok) {
  throw new Error(`Card reveal failed with status ${response.status}`);
}

const { accessUrl } = await response.json();
```

Return only the short-lived `accessUrl` to your frontend through your own authenticated session. Do not log or persist it.

**2. Render the card details**

Use the returned URL directly as the source of one iframe. Do not parse, modify, or reconstruct it.

```html
<iframe
  id="reap-card-details"
  title="Card details"
  sandbox="allow-scripts allow-same-origin"
  allow="clipboard-write"
  referrerpolicy="no-referrer"
  style="width: 100%; height: 180px; color-scheme: light; border: 0"
></iframe>
```

```ts
const iframe = document.querySelector<HTMLIFrameElement>(
  "#reap-card-details",
);
if (!iframe) {
  throw new Error("Card-details iframe was not found");
}

iframe.src = accessUrl;
```

Set the iframe's `color-scheme` to `light` or `dark` to match your page, or omit it to use the browser's inherited color preference (normally the user's system preference). Your application can style the iframe element and its container, but it cannot directly style or inspect the cross-origin contents.

**3. Discard the access URL**

The URL is short-lived. Clear the iframe source and discard the URL when the card-details view closes. Request a fresh URL whenever the user opens or retries the view.

The interactive playground can demonstrate the API response, but it does not render the card widget.

## Security requirements

* Keep your API key on your backend.
* Return the access URL only to an authenticated user who is authorized to view that card.
* Keep the URL only in memory for the active card-details view. Do not log, persist, decode, inspect, or modify it.
* Do not send the URL to analytics, error reporting, or session-replay tools.
* Use the iframe sandbox, clipboard permission, and no-referrer policy shown above.

## Troubleshooting

| Symptom | Resolution |
| - | - |
| The API returns `401` | Check that the backend supplied a valid API key. |
| The API returns `403` | Confirm the key has the `cards:read_vault` scope and that the request satisfies its IP restrictions. Use the response `code` to distinguish the cause. |
| The API returns `404` | Confirm the card ID belongs to the authenticated business and is available. |
| The iframe is empty or reports that card data is unavailable | Request a fresh access URL and replace the iframe source. |
| The iframe renders blank | If the frame renders blank on your domain, your origin isn't allowlisted; contact Reap to enable embedding, or open the URL in a new tab instead. |
| The copy control does not work | Confirm the iframe includes `allow="clipboard-write"` and that the browser permits clipboard access. |
| The browser refuses to frame the widget | Confirm the iframe uses the returned HTTPS URL directly and is not being blocked by the application's own Content Security Policy. |


## OpenAPI

````yaml /openapi/2026-11-05.json post /2026-11-05/cards/{cardId}/reveal
openapi: 3.1.0
info:
  title: Reap Business Account API
  description: >

    # Introduction


    The Reap Business Account API lets you manage cards, spend and Treasury

    funding for your Business Account from your own systems. Every endpoint is

    authenticated with an API key sent in the `x-api-key` header and versioned

    with a date in the URL (`/2026-11-05/...`).


    Guides, concepts and the full setup reference live on the docs site:

    [direct-api.reap.global](https://direct-api.reap.global).



    ## Errors


    All errors share a single JSON envelope:


    ```json

    {
      "statusCode": 400,
      "type": "INVALID_REQUEST_ERROR",
      "code": "SPEND_CAP_TOO_LOW",
      "message": "Spend cap cannot be lower than the amount already spent on this card.",
      "param": "spendCap",
      "requestId": "01H..."
    }

    ```


    - `statusCode`: HTTP status, duplicated in the body.

    - `type`: coarse category, **always present**. Branch on this for
    retry/re-auth decisions.

    - `code`: stable, machine-readable identifier. Present only for
    programmatically-actionable errors.

    - `message`: human-readable explanation, safe to surface to users.

    - `param`: offending field for validation errors (optional).

    - `details`: structured extra context such as validation issues or required
    API-key scopes (optional).

    - `requestId`: correlation id; include it when contacting support
    (optional).


    The specific error codes each endpoint can return are documented on that

    endpoint's responses below.


    ### Error types


    | Type | Description |

    | --- | --- |

    | `INVALID_REQUEST_ERROR` | The request was rejected due to invalid input, a
    missing resource, or a business-rule violation (HTTP 400/404/409/422). |

    | `AUTHENTICATION_ERROR` | Authentication is missing or invalid (HTTP 401).
    |

    | `PERMISSION_ERROR` | The caller is authenticated but not permitted to
    perform the action (HTTP 403). |

    | `RATE_LIMIT_ERROR` | Too many requests; retry after a delay (HTTP 429). |

    | `API_ERROR` | An unexpected error occurred on our side (HTTP 5xx). |

    | `UPSTREAM_ERROR` | An upstream service returned an error (HTTP 502/503). |
  version: '2026-11-05'
  contact: {}
servers:
  - url: https://api.global.direct.reap.global
security: []
tags: []
paths:
  /2026-11-05/cards/{cardId}/reveal:
    post:
      tags:
        - Cards
      summary: Reveal card details
      description: >-
        Required API-key scope: `cards:read_vault`.


        Returns a short-lived link to a secure, Reap-hosted page that shows the
        card number, expiry date and CVV, for you to display in an iframe. The
        link expires after 1 minute, and the card details never pass through
        your servers. Always call this endpoint from your backend, and only for
        people allowed to see the card. See [Card
        details](/concepts/card-details).
      operationId: revealCard
      parameters:
        - name: cardId
          required: true
          in: path
          description: >-
            The card's ID, as returned by [List
            cards](/api-reference/cards/list-cards) or [Create
            card](/api-reference/cards/create-card).
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevealedCardDetails'
              examples:
                vaultHandoff:
                  summary: Card-details iframe
                  value:
                    accessUrl: >-
                      https://secure.card.reap.global/api/card/show-card-info?auth=temporary-token&copyPan=true
        '400':
          description: '`BAD_REQUEST`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BAD_REQUEST:
                  summary: BAD_REQUEST
                  value:
                    statusCode: 400
                    type: INVALID_REQUEST_ERROR
                    message: Bad request.
        '401':
          description: '`UNAUTHORIZED`, `AUTH_CREDENTIAL_MISSING`, `API_KEY_INVALID`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UNAUTHORIZED:
                  summary: UNAUTHORIZED
                  value:
                    statusCode: 401
                    type: AUTHENTICATION_ERROR
                    message: Authentication required.
                AUTH_CREDENTIAL_MISSING:
                  summary: AUTH_CREDENTIAL_MISSING
                  value:
                    statusCode: 401
                    type: AUTHENTICATION_ERROR
                    code: AUTH_CREDENTIAL_MISSING
                    message: Authentication is required.
                API_KEY_INVALID:
                  summary: API_KEY_INVALID
                  value:
                    statusCode: 401
                    type: AUTHENTICATION_ERROR
                    code: API_KEY_INVALID
                    message: API key is invalid.
        '403':
          description: >-
            `FORBIDDEN`, `API_KEY_IP_NOT_ALLOWED`,
            `AUTH_INSUFFICIENT_PERMISSIONS`, `AUTH_METHOD_NOT_ALLOWED`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                FORBIDDEN:
                  summary: FORBIDDEN
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    message: You do not have permission to perform this action.
                API_KEY_IP_NOT_ALLOWED:
                  summary: API_KEY_IP_NOT_ALLOWED
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: API_KEY_IP_NOT_ALLOWED
                    message: Request IP is not allowed for this API key.
                AUTH_INSUFFICIENT_PERMISSIONS:
                  summary: AUTH_INSUFFICIENT_PERMISSIONS
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: AUTH_INSUFFICIENT_PERMISSIONS
                    message: Insufficient permissions.
                    details:
                      requiredScopes:
                        - <required-scope>
                AUTH_METHOD_NOT_ALLOWED:
                  summary: AUTH_METHOD_NOT_ALLOWED
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: AUTH_METHOD_NOT_ALLOWED
                    message: >-
                      This endpoint does not accept the credential type
                      provided.
        '404':
          description: '`NOT_FOUND`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NOT_FOUND:
                  summary: NOT_FOUND
                  value:
                    statusCode: 404
                    type: INVALID_REQUEST_ERROR
                    message: The requested resource was not found.
        '429':
          description: '`API_KEY_RATE_LIMITED`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                API_KEY_RATE_LIMITED:
                  summary: API_KEY_RATE_LIMITED
                  value:
                    statusCode: 429
                    type: RATE_LIMIT_ERROR
                    code: API_KEY_RATE_LIMITED
                    message: API key rate limit exceeded.
        '500':
          description: '`INTERNAL_ERROR`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                INTERNAL_ERROR:
                  summary: INTERNAL_ERROR
                  value:
                    statusCode: 500
                    type: API_ERROR
                    message: An unexpected error occurred.
        '504':
          description: '`UPSTREAM_TIMEOUT`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UPSTREAM_TIMEOUT:
                  summary: UPSTREAM_TIMEOUT
                  value:
                    statusCode: 504
                    type: UPSTREAM_ERROR
                    code: UPSTREAM_TIMEOUT
                    message: >-
                      An upstream service did not respond in time. If this
                      request changes data, it may still have been applied, so
                      fetch the resource before you retry.
      security:
        - apiKey: []
components:
  schemas:
    RevealedCardDetails:
      type: object
      properties:
        accessUrl:
          type: string
          format: uri
          description: >-
            A link to a secure, Reap-hosted page that shows the card number,
            expiry date and CVV. Load it in an iframe straight away: it expires
            after 1 minute and must never be stored or logged.
      required:
        - accessUrl
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          minimum: 100
          maximum: 599
          description: The HTTP status code, repeated in the body for convenience.
        type:
          type: string
          enum:
            - INVALID_REQUEST_ERROR
            - AUTHENTICATION_ERROR
            - PERMISSION_ERROR
            - RATE_LIMIT_ERROR
            - API_ERROR
            - UPSTREAM_ERROR
          description: >-
            The broad kind of error, for example `RATE_LIMIT_ERROR`. It's always
            present: use it to decide whether to retry, re-authenticate or fix
            the request.
        code:
          description: >-
            A stable, machine-readable error code, for example
            `CARD_CREATION_REQUIRES_DEPOSIT`. It's present when there's a
            specific action you can take, and each endpoint lists the codes it
            can return.
          type: string
        message:
          type: string
          description: >-
            A plain-English explanation of the error that's safe to show to your
            users.
        param:
          description: >-
            The request field that caused a validation error, for example
            `spendCap`.
          type: string
        details:
          description: >-
            Extra structured information, such as the list of validation issues
            or the API-key scopes your key is missing.
        requestId:
          description: >-
            A unique ID for this request. Include it when you contact Reap
            Support so the team can find it.
          type: string
      required:
        - statusCode
        - type
        - message
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Enter your API key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.