Skip to content
straddle API Docs
Get started
API Reference
Paykeys

Retrieve an unmasked paykey token

$ straddle paykeys reveal
GET/v1/paykeys/{id}/reveal

Retrieves the details of a paykey that has previously been created. Supply the unique paykey ID that was returned from your previous request, and Straddle will return the corresponding paykey information including the unmasked token.

ParametersExpand Collapse
--id: string
--correlation-id: optional string

Optional client generated identifier to trace and debug a series of requests.

--request-id: optional string

Optional client generated identifier to trace and debug a request.

--straddle-account-id: optional string

For use by platforms to specify an account id and set scope of a request.

ReturnsExpand Collapse
PaykeyRevealResponse: object { data, meta, response_type }
data: object { id, config, created_at, 13 more }
id: string

Unique identifier for the paykey.

config: object { processing_method, sandbox_outcome }
processing_method: optional "inline" or "background" or "skip"
"inline"
"background"
"skip"
sandbox_outcome: optional "standard" or "active" or "rejected" or "review"
"standard"
"active"
"rejected"
"review"
created_at: string

Timestamp of when the paykey was created.

label: string

Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI

paykey: string

The tokenized paykey value. This token is used to create payments and should be stored securely.

source: "bank_account" or "straddle" or "mx" or 3 more
"bank_account"
"straddle"
"mx"
"plaid"
"tan"
"quiltt"
status: "pending" or "active" or "inactive" or 3 more
"pending"
"active"
"inactive"
"rejected"
"review"
"blocked"
updated_at: string

Timestamp of the most recent update to the paykey.

balance: optional object { status, account_balance, updated_at }
status: "pending" or "completed" or "failed"
"pending"
"completed"
"failed"
account_balance: optional number

Account Balance when last retrieved

updated_at: optional string

Last time account balance was updated.

bank_data: optional object { account_number, account_type, routing_number }
account_number: string

Bank account number. This value is masked by default for security reasons. Use the /unmask endpoint to access the unmasked value.

account_type: "checking" or "savings"
"checking"
"savings"
routing_number: string

The routing number of the bank account.

customer_id: optional string

Unique identifier of the related customer object.

expires_at: optional string

Expiration date and time of the paykey, if applicable.

external_id: optional string

Unique identifier for the paykey in your database, used for cross-referencing between Straddle and your systems.

institution_name: optional string

Name of the financial institution.

metadata: optional map[string]

Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the paykey in a structured format.

status_details: optional object { changed_at, message, reason, 2 more }
changed_at: string

The time the status change occurred.

message: string

A human-readable description of the current status.

reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 24 more
"insufficient_funds"
"closed_bank_account"
"invalid_bank_account"
"invalid_routing"
"disputed"
"payment_stopped"
"owner_deceased"
"frozen_bank_account"
"risk_review"
"fraudulent"
"duplicate_entry"
"invalid_paykey"
"payment_blocked"
"amount_too_large"
"too_many_attempts"
"internal_system_error"
"user_request"
"ok"
"other_network_return"
"payout_refused"
"cancel_request"
"failed_verification"
"require_review"
"blocked_by_system"
"watchtower_review"
"validating"
"auto_hold"
source: "watchtower" or "bank_decline" or "customer_dispute" or 2 more
"watchtower"
"bank_decline"
"customer_dispute"
"user_action"
"system"
code: optional string

The status code if applicable.

meta: object { api_request_id, api_request_timestamp }

Metadata about the API request, including an identifier and timestamp.

api_request_id: string

Unique identifier for this API request, useful for troubleshooting.

api_request_timestamp: string

Timestamp for this API request, useful for troubleshooting.

response_type: "object" or "array" or "error" or "none"

Indicates the structure of the returned content.

  • "object" means the data field contains a single JSON object.
  • "array" means the data field contains an array of objects.
  • "error" means the data field contains an error object with details of the issue.
  • "none" means no data is returned.
"object"
"array"
"error"
"none"

Retrieve an unmasked paykey token

straddle paykeys reveal \
  --api-key 'My API Key' \
  --id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "config": {
      "processing_method": "inline",
      "sandbox_outcome": "standard"
    },
    "created_at": "2019-12-27T18:11:19.117Z",
    "label": "Bank of America ****1234",
    "paykey": "paykey",
    "source": "straddle",
    "status": "pending",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "balance": {
      "status": "pending",
      "account_balance": 0,
      "updated_at": "2019-12-27T18:11:19.117Z"
    },
    "bank_data": {
      "account_number": "****1234",
      "account_type": "checking",
      "routing_number": "021000021"
    },
    "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "expires_at": "2019-12-27T18:11:19.117Z",
    "external_id": "external_id",
    "institution_name": "Bank of America",
    "metadata": {
      "foo": "string"
    },
    "status_details": {
      "changed_at": "2019-12-27T18:11:19.117Z",
      "message": "Bank account sucesfully validated",
      "reason": "insufficient_funds",
      "source": "watchtower",
      "code": "code"
    }
  },
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z"
  },
  "response_type": "object"
}
Returns Examples
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "config": {
      "processing_method": "inline",
      "sandbox_outcome": "standard"
    },
    "created_at": "2019-12-27T18:11:19.117Z",
    "label": "Bank of America ****1234",
    "paykey": "paykey",
    "source": "straddle",
    "status": "pending",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "balance": {
      "status": "pending",
      "account_balance": 0,
      "updated_at": "2019-12-27T18:11:19.117Z"
    },
    "bank_data": {
      "account_number": "****1234",
      "account_type": "checking",
      "routing_number": "021000021"
    },
    "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "expires_at": "2019-12-27T18:11:19.117Z",
    "external_id": "external_id",
    "institution_name": "Bank of America",
    "metadata": {
      "foo": "string"
    },
    "status_details": {
      "changed_at": "2019-12-27T18:11:19.117Z",
      "message": "Bank account sucesfully validated",
      "reason": "insufficient_funds",
      "source": "watchtower",
      "code": "code"
    }
  },
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z"
  },
  "response_type": "object"
}