Skip to content

Update cards, accounts and users documentation #253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ricardobcl wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Update cards, accounts and users documentation #253

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cb30d2d
Update cards documentation
ricardobcl Aug 23, 2026
d5edbef
Update accounts documentation
ricardobcl Aug 23, 2026
693ca5a
Update users documentation
ricardobcl Aug 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 28 additions & 9 deletions _accounts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,18 @@ Uphold allows users to deposit value into a specific card from an external sourc
Whenever a deposit is made into an Uphold card, it will be automatically converted into the value determined by the card's denomination.
Likewise, when a withdrawal is made, the currency will be converted to the currency of the destination account, thus minimizing fees and currency conversions.

We support the following account types:
Deposit and withdrawal support for the most common account types is as follows:

Account type | Deposits supported? | Withdrawals supported?
------------ | ------------------- | ----------------------
ach | Yes | Yes
card | Yes | No
card | Yes | No \*
sepa | Yes | Yes

\* Push-to-card withdrawals via OCT settlement are available for eligible debit cards — see the [Approved cards](#approved-cards) section below.

Accounts of other types can also be returned by the API — namely `fps` bank accounts, `swift` and `wire` bank accounts, and `exchange` accounts.

Please refer to our FAQ for estimated [ACH transaction times](https://support.uphold.com/hc/en-us/articles/206762103-How-to-add-and-withdraw-funds-via-bank-transfer-U-S-), [SEPA transaction times](https://support.uphold.com/hc/en-us/articles/205803186-How-to-add-and-withdraw-funds-via-bank-transfer-Europe-), [fees and limits](https://support.uphold.com/hc/en-us/articles/360038404532).

## List Accounts
Expand All @@ -27,18 +31,21 @@ curl https://api.uphold.com/v0/me/accounts \
> Example of filtering the list to show only accounts of the `sepa` or `card` types, and in the `ok` status:

```bash
curl 'https://api.uphold.com/v0/me/accounts?q=type:sepa,card%20status:ok'
curl 'https://api.uphold.com/v0/me/accounts?q=type:sepa,card%20status:ok' \
-H "Authorization: Bearer <token>"
```

> The above command returns the following JSON:

```json
[{
"bic": "CGDIPTPL",
"billing": {},
"currency": "EUR",
"iban": "PT69003500001234567890112",
"id": "18843b6d-5a43-480f-8e2b-73b27d726bf0",
"label": "Checking Account",
"provider": "uphold",
"status": "ok",
"type": "sepa"
},
Expand All @@ -47,9 +54,12 @@ curl 'https://api.uphold.com/v0/me/accounts?q=type:sepa,card%20status:ok'
"name": "Makenna Ortiz"
},
"brand": "visa",
"cardNumberMasked": "1519",
"currency": "USD",
"expiryDate": "2027-12-31T23:59:59.999Z",
"id": "0874745c-f0bf-4973-a3d9-9832aeaae087",
"label": "Savings Account",
"provider": "credit-card-gateway",
"status": "ok",
"type": "card"
}]
Expand All @@ -65,16 +75,22 @@ Retrieves a list of accounts for the current user.
Requires the <code>accounts:read</code> scope for Uphold Connect applications.
</aside>

You can filter the list of returned accounts using query string parameters.
You can filter the list of returned accounts using the `q` query string parameter.
Supported filters are `status:` and `type:`, with either a single value or a comma-separated list.
For a list of valid values for these parameters, refer to the [Account Object](#account-object) documentation.
Valid values for `status:` are `expired`, `failed`, `ok` and `pending`.
By default, only accounts with the `ok` status are returned.
Valid values for `type:` are `bank`, `card` and `exchange`, as well as the deprecated values `ach`, `fps` and `sepa`.
Note that `swift` and `wire` may appear as account types in responses, but are not valid values for the `type:` filter.
Multiple filters can be used together, separated with a space.
See the code to the right for an example.

### Response

Returns an array of the current user's accounts.

All accounts include the `provider` property.
Depending on the account type, additional properties are returned — e.g. `bic` and `iban` for `sepa` accounts, the masked account and routing numbers (`accountNumberMasked` and `routingNumberMasked`) for `ach` accounts, and `brand`, `cardNumberMasked` and `expiryDate` for `card` accounts.

## Get Account Details

```bash
Expand All @@ -86,10 +102,13 @@ curl https://api.uphold.com/v0/me/accounts/18843b6d-5a43-480f-8e2b-73b27d726bf0

```json
{
"bic": "CGDIPTPL",
"billing": {},
"currency": "EUR",
"iban": "PT69003500001234567890112",
"id": "18843b6d-5a43-480f-8e2b-73b27d726bf0",
"label": "Checking Account",
"provider": "uphold",
"status": "ok",
"type": "sepa"
}
Expand Down Expand Up @@ -142,7 +161,7 @@ Number | Brand | Type | Country | OCT settlement |
4658584090000001 | visa | debit | GB | N/A |
4659105569051157 | visa | debit | GB | instant |
4659465888705671 | visa | debit | GB | N/A |
4757337282365488 | visa | debit | DE | N/A |
4757337282365488 | visa | debit | DE | N/A |
4921817844445119 | visa | debit | GB | instant |
5121073611487018 | mastercard | credit | US | N/A |
5259410220714099 | mastercard | credit | US | N/A |
Expand All @@ -167,10 +186,10 @@ Number | Brand | Type | Country | 3DS flow | Result
5518832400606463 | mastercard | debit | US | 3DS2 challenge flow | authentication attempted |
5291144083573579 | mastercard | credit | US | 3DS2 frictionless | error message during scheme communication |
5121073611487018 | mastercard | credit | US | 3DS2 frictionless | no associated 3DS method url |
5385308360135181 | mastercard | credit | US | 3DS2 challenge flow | authentication successfull |
5385308360135181 | mastercard | credit | US | 3DS2 challenge flow | authentication successful |
5259410220714099 | mastercard | credit | US | 3DS2 challenge flow | no associated 3DS method url |
4242424242424242 | visa | credit | GB | 3DS2 challenge flow | authentication successfull |
4485040371536584 | visa | credit | US | 3DS2 frictionless | authentication successfull |
4242424242424242 | visa | credit | GB | 3DS2 challenge flow | authentication successful |
4485040371536584 | visa | credit | US | 3DS2 frictionless | authentication successful |
4484070000035519 | visa | credit | GB | 3DS2 frictionless | card not enrolled |
4556574722325580 | visa | credit | PT | 3DS2 frictionless | authentication attempted |
4447336775378848 | visa | debit | US | 3DS2 challenge flow | authentication could not be performed |
Expand Down
58 changes: 40 additions & 18 deletions _cards.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Cards

Uphold uses the concept of a "card" as a store of value.
Each card is denominated by a currency or store of value, and every card is automatically provisioned one or more addresses to which value can be sent.
Each card is denominated by a currency or store of value, and addresses to which value can be sent can be created on demand for a card via the [Create Card Address](#create-card-address) endpoint.
(Note that there can be multiple cards for the same currency.)

Whenever value flows into a card, Uphold automatically converts that value into the value determined by the card's denomination.
Expand All @@ -20,7 +20,7 @@ curl https://api.uphold.com/v0/me/cards \
> Example of filtering the list to show only starred cards denominated in BTC or EUR:

```bash
curl 'https://api.uphold.com/v0/me/cards?q=currency:BTC,EUR%20settings.starred:true'
curl 'https://api.uphold.com/v0/me/cards?q=currency:BTC,EUR%20settings.starred:true' \
-H "Authorization: Bearer <token>"
```

Expand All @@ -43,7 +43,7 @@ curl 'https://api.uphold.com/v0/me/cards?q=currency:BTC,EUR%20settings.starred:t
"currency": "USD"
}],
"settings": {
"position": 1,
"position": 0,
"protected": false,
"starred": true
}
Expand All @@ -64,7 +64,7 @@ curl 'https://api.uphold.com/v0/me/cards?q=currency:BTC,EUR%20settings.starred:t
"currency": "USD"
}],
"settings": {
"position": 2,
"position": 0,
"protected": false,
"starred": true
}
Expand All @@ -81,11 +81,19 @@ Retrieves a list of cards for the current user.
Requires the <code>cards:read</code> scope for Uphold Connect applications.
</aside>

You can filter the list of returned cards using query string parameters.
Supported filters are `currency:` (which accepts a comma-separated list of currencies) and `settings.starred:` (which accepts `true` or `false`).
You can filter the list of returned cards using the `q` query string parameter.
Supported filters are `currency:` (which accepts a comma-separated list of currencies), `id:` (which accepts a comma-separated list of card IDs) and `settings.starred:` (which accepts `true` or `false`).
Multiple filters can be used together, separated with a space.
See the code to the right for an example.

The list can also be sorted using the following query string parameters:

Parameter | Description
------------------ | --------------------------------------------------------------------------------------------------------------------------------------
direction | The sort direction. Possible values are `asc` and `desc`. Defaults to `asc`.
normalizedCurrency | The currency in which the `normalized` amounts are expressed. Defaults to the user's settings currency.
sort | The field to sort the list by. Possible values are `createdAt`, `currency`, `normalized.available` and `normalized.balance`. Defaults to `currency`.

This endpoint supports [Pagination](#pagination).

### Response
Expand Down Expand Up @@ -118,7 +126,7 @@ curl https://api.uphold.com/v0/me/cards/bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3 \
"currency": "USD"
}],
"settings": {
"position": 2,
"position": 0,
"protected": false,
"starred": true
}
Expand All @@ -135,7 +143,7 @@ Retrieves the details about a specific card.
Requires the <code>cards:read</code> scope for Uphold Connect applications.
</aside>
<aside class="notice">
<code>:id</code> can either be the card ID or its bitcoin address and it must be owned by the user making the call.
<code>:id</code> can either be the card ID or any of the card's crypto addresses (on any network), and it must be owned by the user making the call.
</aside>

### Response
Expand All @@ -160,10 +168,12 @@ curl https://api.uphold.com/v0/me/cards \
Requires the <code>cards:write</code> scope for Uphold Connect applications.
</aside>

Parameter | Description
--------- | -------------------------------------------------------------------------------------------------------------
currency | The [currency](#currencies) to denominate the value stored by the card, represented by its code (e.g. "USD").
label | The display name of the card. Max length: 140 characters.
Parameter | Required | Description
--------- | -------- | -------------------------------------------------------------------------------------------------------------
currency | yes | The [currency](#currencies) to denominate the value stored by the card, represented by its code (e.g. "USD").
label | no | The display name of the card. Max length: 140 characters. If omitted, a default label is derived from the asset's name (e.g. "Bitcoin account").
settings | no | This property contains the following keys:
| | | `starred`: Indicates whether the card is starred or not. Defaults to `false`.

### Response

Expand Down Expand Up @@ -192,7 +202,11 @@ Parameter | Description
label | The display name of the card. Max length: 140 characters.
settings | This property contains the following keys:
| | `starred`: Indicates whether the card is starred or not.
| | <code class="notice">DEPRECATED</code> `position`: The card's current position.

<aside class="notice">
The deprecated <code>settings.position</code> key is ignored if sent.
Cards no longer have a position — the field is always returned as <code>0</code> for backward compatibility.
</aside>

### Response

Expand Down Expand Up @@ -220,7 +234,7 @@ curl https://api.uphold.com/v0/me/cards/024e51fc-5513-4d82-882c-9b22024280cc/add
Generate an address for a card.

<aside class="notice">
For the network <code>xrp-ledger</code> the response also returns the <code>tag</code> property, which is the corresponding <code>Destination Tag</code>.
For tag-based networks — <code>stellar</code>, <code>ton</code> and <code>xrp-ledger</code> — the response also returns the <code>tag</code> property (e.g. the <code>Destination Tag</code> on the XRP Ledger), which must be included when sending funds to the address.
</aside>

> For an XRP Ledger address, the following JSON is returned:
Expand All @@ -240,10 +254,15 @@ Generate an address for a card.
<aside class="notice">
Requires the <code>cards:write</code> scope for Uphold Connect applications.
</aside>
<aside class="notice">
Requires the user to have the deposits capability, otherwise a <code>403</code> error is returned.
The card's currency must support buying, otherwise a <code>400</code> error is returned.
Only one address can be created per network on each card.
</aside>

Parameter | Description
--------- | -----------------------------------------------------------------------------------------------------------------------------------------------------
network | The address network. Possible values are `bitcoin`, `bitcoin-cash`, `bitcoin-gold`, `dash`, `ethereum`, `interledger`, `litecoin` and `xrp-ledger`.
network | The address network. Possible values are the networks of the cryptocurrencies available to the user — for example `bitcoin`, `ethereum`, `litecoin`, `solana`, `ton`, `tron` and `xrp-ledger`, among many others.

### Response

Expand All @@ -262,8 +281,11 @@ curl https://api.uphold.com/v0/me/cards/37e002a7-8508-4268-a18c-7335a6ddf24b/add
```json
[{
"formats": [{
"format": "pubkeyhash",
"value": "mkZuBgFa4gAjJ2UckDA3Pms68rVBavAneF"
"format": "wrappedSegWit",
"value": "3QJmV3qfvL9SuYo34YihAf3sRCW3qSinyC"
}, {
"format": "nativeSegWit",
"value": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"
}],
"type": "bitcoin"
},
Expand All @@ -287,7 +309,7 @@ curl https://api.uphold.com/v0/me/cards/37e002a7-8508-4268-a18c-7335a6ddf24b/add
Retrieves a list of addresses for a specific card.

<aside class="notice">
The property <code>tag</code> is defined only to allow the XRP Ledger network to identify the card's <code>Destination Tag</code>.
The <code>tag</code> property is returned for tag-based networks — <code>stellar</code>, <code>ton</code> and <code>xrp-ledger</code> — and identifies the card on the shared address (e.g. the <code>Destination Tag</code> on the XRP Ledger).
</aside>

### Request
Expand Down
36 changes: 28 additions & 8 deletions _users.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,17 @@ curl "https://api.uphold.com/v0/me" \
"zipCode": "53059"
},
"balances": {
"available": "90.00",
"currencies": {
"BTC": {
"amount": "90.00",
"available": "0.1",
"balance": "0.1",
"currency": "USD",
"rate": "900.00000"
}
},
"pending": "0.00",
"total": "90.00"
},
"birthdate": "2014-08-27",
Expand All @@ -35,6 +38,9 @@ curl "https://api.uphold.com/v0/me" \
],
"email": "luke.skywalker@uphold.com",
"firstName": "Luke",
"fullName": "Luke Skywalker",
"id": "d602e7bb-b938-44e0-bc74-b35ad3e21a55",
"identityCountry": "US",
"lastName": "Skywalker",
"memberAt": "2015-07-10T15:36:20.288Z",
"name": "Luke Skywalker",
Expand Down Expand Up @@ -73,6 +79,7 @@ curl "https://api.uphold.com/v0/me" \
},
"state": "WA",
"status": "ok",
"type": "individual",
"verifications": {}
}
```
Expand All @@ -90,14 +97,10 @@ curl "https://api.uphold.com/v0/me" \
Returns the data associated with the current user.
See the [user object](#user-object) documentation for details about the format of the response.

<aside class="notice">
Be advised that this method can potentially return a large amount of data.
</aside>

### Cards

The `cards` property will be removed from the response.
To access the cards of a given user please refer to the appropriate specific [endpoint](#list-cards).
The `cards` property has been removed from the response.
To access the cards of a given user please refer to the [List Cards](#list-cards) endpoint.

## Get User Phone Numbers

Expand All @@ -108,21 +111,38 @@ curl "https://api.uphold.com/v0/me/phones" \

> The above command returns the following JSON:

```json
[{
"country": "US",
"e164": "+15558675304",
"id": "1d78aeb5-43ac-4ee8-8d28-1291b5d8355c"
}]
```

> Requests authenticated with email and password (or a password reset token) receive masked numbers instead:

```json
[{
"e164Masked": "+XXXXXXXXX04",
"id": "1d78aeb5-43ac-4ee8-8d28-1291b5d8355c",
"internationalMasked": "+X XXX-XXX-XX04",
"nationalMasked": "(XXX) XXX-XX04",
"primary": "true",
"verified": "true"
"primary": true,
"verified": true
}]
```

### Request

`GET https://api.uphold.com/v0/me/phones`

<aside class="notice">
Requires the <code>phones:read</code> scope for Uphold Connect applications.
</aside>

### Response

Returns an array of all the phone numbers associated with the current user.

When the request is authenticated with an OAuth token, each item contains the `country`, `e164` and `id` properties.
Requests authenticated with email and password (or a password reset token) receive masked numbers (`e164Masked`, `internationalMasked` and `nationalMasked`) along with the `primary` and `verified` flags instead.