Custodial Bank Accounts

Custodial merchants only, register, list, inspect, and remove ACH bank accounts (Uphold External Accounts) used as off-ramp destinations.

Add bank account

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/custodial/bank-account/create

Registers an ACH bank account as an Uphold External Account. Full routing/account numbers are sent to Uphold only, we store the last 4 digits. Gated by 2FA (totpCode). The account starts in processing and transitions to ok once Uphold verifies it.

Authorization: merchantAuth

Body required

application/json

labelstring

Human-readable label for the POS terminal (optional).

Example:Front desk

routingNumberstringrequired

Example:string

accountNumberstringrequired

Example:string

accountTypeenumrequired

checkingsavings

Example:checking

holderAddressobjectrequired

totpCodestringrequired

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/custodial/bank-account/create

cURL

curl -X POST "$BASE_URL/merchant/custodial/bank-account/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "label": "Front desk",
  "routingNumber": "string",
  "accountNumber": "string",
  "accountType": "checking",
  "holderAddress": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "zipCode": "string",
    "country": "string"
  },
  "totpCode": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "label": "Front desk",
      "routingNumberLast4": "string",
      "accountNumberLast4": "string",
      "accountType": "checking",
      "status": "processing",
      "upholdExternalAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "createdAt": 1718012345
    }
  }
}

List bank accounts

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/custodial/bank-account/list

Returns all of the merchant's registered bank accounts as accounts, each with masked routing/account numbers, Uphold EA status, and label.

Authorization: merchantAuth

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/custodial/bank-account/list

cURL

curl -X POST "$BASE_URL/merchant/custodial/bank-account/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "accounts": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "label": "Front desk",
          "routingNumberLast4": "string",
          "accountNumberLast4": "string",
          "accountType": "checking",
          "status": "processing",
          "upholdExternalAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "createdAt": 1718012345
        }
      ]
    }
  }
}

Get bank account

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/custodial/bank-account/get

Returns a single bank account by bankAccountId with up-to-date Uphold status.

Authorization: merchantAuth

Body required

application/json

bankAccountIdstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/custodial/bank-account/get

cURL

curl -X POST "$BASE_URL/merchant/custodial/bank-account/get" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "bankAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "label": "Front desk",
      "routingNumberLast4": "string",
      "accountNumberLast4": "string",
      "accountType": "checking",
      "status": "processing",
      "upholdExternalAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "createdAt": 1718012345
    }
  }
}

Delete bank account

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/custodial/bank-account/delete

Soft-deletes the bank account. Fails with bank_account_has_pending_offramp if there is an in-flight off-ramp using it. Gated by 2FA (totpCode). Returns { ok }.

Authorization: merchantAuth

Body required

application/json

bankAccountIdstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

totpCodestringrequired

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/custodial/bank-account/delete

cURL

curl -X POST "$BASE_URL/merchant/custodial/bank-account/delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "bankAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "totpCode": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}