Pay REST API Reference

This document describes Coinbase Pay APIs.

Buy Config

The Buy Config API returns the list of countries supported by Coinbase Pay, and the payment methods available in each country. Clients can call this API periodically and cache the response so that they know which users to present the Coinbase Pay Onramp option to.

Method

GET

URL

https://pay.coinbase.com/api/v1/buy/config

Request Parameters

The Buy Config API has no request parameters.

Response Fields

The Buy Config API returns a JSON response including the following fields.

Name	Description
countries	A list of supported countries, represented by their ISO 3166-1 two digit country code. Each country contains a list of payment method types available in that country; for the US it also contains a list of supported states.

Example Request/Response

Request (cURL)

curl https://pay.coinbase.com/api/v1/buy/config /
  -X GET \
  -H 'CBPAY-VERSION: XXXX-XX-XX' \
  -H 'CBPAY-APP-ID: XXXXXXXXXXXXXXXXXXXXXXXXX' \
  -H 'CBPAY-API-KEY: XXXXXXXXXXXXXXXXXXXXXXXXX'

Response 200 (JSON)

{
  "data": {
    "countries": [
      {
        "id": "US",
        "subdivisions": ["CA","NY","WA"],
        "payment_methods": [
          {
            "id": "CARD",
          },
          {
            "id": "ACH_BANK_ACCOUNT",
          },
        ],
      },
      {
        "id": "CA",
        "subdivisions": []
        "payment_methods": [
          {
            "id": "CARD",
          },
        ],
      },
    ],
  }
}

Buy Options

The Buy Options API provides clients with a way to discover the available options for buying Crypto with CBPay. It returns the supported fiat currencies and available crypto assets that can be passed into the Buy Quote API.

Method

GET

URL

https://pay.coinbase.com/api/v1/buy/options

Request Parameters

Name	Req	Description
country	Y	ISO 3166-1 two-digit country code string representing the purchasing user’s country of residence, e.g., US.
subdivision	N	ISO 3166-2 two-digit country subdivision code representing the purchasing user’s subdivision of residence within their country, e.g. NY. Required if the country=“US” because certain states (e.g., NY) have state specific asset restrictions.

Response Fields

The Buy Options API returns a JSON response including the following fields.

Name	Description
payment_currencies	List of supported fiat currencies that can be exchanged for crypto on CBPay in the given location. Each currency contains a list of available payment methods, with min and max transaction limits for that currency.
purchase_currencies	List of available crypto assets that can be bought on CBPay in the given location.

Example Request/Response

Request (cURL)

curl https://pay.coinbase.com/api/v1/buy/options?country=US&subdivision=NY /
  -X GET \
  -H 'CBPAY-VERSION: XXXX-XX-XX' \
  -H 'CBPAY-APP-ID: XXXXXXXXXXXXXXXXXXXXXXXXX' \
  -H 'CBPAY-API-KEY: XXXXXXXXXXXXXXXXXXXXXXXXX'

Response 200 (JSON)

{
  "data": {
    "payment_currencies": [
      {
        "id": "USD",
        "payment_method_limits": [
          {
            "id": "card",
            "min": "10.00",
            "max": "7500.00",
          },
          {
            "id": "ach_bank_account",
            "min": "10.00",
            "max": "25000.00",
          },
        ],
      },
    ],
    "purchase_currencies": [
      {
        "id": "2b92315d-eab7-5bef-84fa-089a131333f5",
        "name": "USD Coin",
        "symbol": "USDC",
        "networks": [
          {
            "name": "ethereum-mainnet",
            "display_name": "Ethereum",
            "chain_id": "1",
            "contract_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          },
          {
            "name": "polygon-mainnet",
            "display_name": "Polygon",
            "chain_id": "137",
            "contract_address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
          },
        ]
      }
    ],
  }
}

Buy Quote

The Buy Quote API provides clients with a quote based on the asset the user would like to purchase, the network they plan to purchase it on, the dollar amount of the payment, the payment currency, the payment method, and country of the user.

Limitations

The quote provided by this API is an estimate only. It does not guarantee that the user will be able to complete their purchase using the returned quote. Depending on fluctuations in network fees and exchange rates, and whether or not the user chooses the logged in or guest checkout experience, the actual fees charged may be different.

Method

POST

URL

https://pay.coinbase.com/api/v1/buy/quote

Request Parameters

The Buy Quote API is an RPC endpoint that accepts parameters as JSON in the request body.

Name	Type	Req	Description
purchase_currency		Y	ID of the crypto asset the user wants to purchase. Retrieved from the options API.
purchase_network		N	Name of the network that the purchase currency should be purchased on. Retrieved from the options API. If omitted, the default network for the crypto currency is used.
payment_amount	String	Y	Fiat amount the user wants to spend to purchase the crypto currency, inclusive of fees with two decimals of precision, e.g., 100.00.
payment_currency	String	Y	Fiat currency of the payment amount, e.g., USD.
payment_method		Y	ID of payment method used to complete the purchase. Retrieved from the options API.
country		Y	ISO 3166-1 two-digit country code string representing the purchasing user’s country of residence, e.g., US.
subdivision		N	ISO 3166-2 two-digit country subdivision code representing the purchasing user’s subdivision of residence within their country, e.g. NY. Required if the country=“US” because certain states (e.g., NY) have state specific asset restrictions.

Response Fields

The Buy Options API returns a JSON response including the following fields.

Name	Description
payment_total	Object with amount and currency of the total fiat payment required to complete the purchase, inclusive of any fees. The currency will match the payment_currency in the request if it is supported, otherwise it falls back to USD.
payment_subtotal	Object with amount and currency of the fiat cost of the crypto asset to be purchased, exclusive of any fees. The currency will match the payment_total currency.
purchase_amount	Object with amount and currency of the crypto that to be purchased. The currency will match the purchase_currency in the request. The number of decimals will be based on the crypto asset.
coinbase_fee	Object with amount and currency of the fee changed by the Coinbase exchange to complete the transaction. The currency will match the payment_total currency.
network_fee	Object with amount and currency of the network fee required to send the purchased crypto to the user’s wallet. The currency will match the payment_total currency.
quote_id	Reference to the quote that should be passed into the initialization parameters when launching the Coinbase Pay widget via the SDK or URL generator.

Example Request/Response

Request (cURL)

curl https://pay.coinbase.com/api/v1/buy/quote /
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'CBPAY-VERSION: XXXX-XX-XX' \
  -H 'CBPAY-APP-ID: XXXXXXXXXXXXXXXXXXXXXXXXX' \
  -H 'CBPAY-API-KEY: XXXXXXXXXXXXXXXXXXXXXXXXX' \
  -d '{"purchase_currency": "BTC", "payment_amount": "100.00", "payment_currency": "USD", "payment_method": "CARD", "country": "US", "subdivision": "NY"}'

Response 200 (JSON)

{
  "data": {
    "payment_total": {
      "amount": "100.00",
      "currency": "USD"
    },
    "payment_subtotal": {
      "amount": "97.00",
      "currency": "USD"
    },
    "purchase_amount": {
      "amount": "10.00000000",
      "currency": "BTC"
    },
    "coinbase_fee": {
      "amount": "1.50",
      "currency": "USD"
    },
    "network_fee": {
      "amount": "1.50",
      "currency": "USD"
    },
    "quote_id": "46da84dc-b6d7-11ed-afa1-0242ac120002"
  }
}

Onramp Session Token

The Onramp Session Token API provides a secure way for the client to initialize the Pay SDK. For clients that are integrated with this API, the standard way of initializing the Pay SDK, by passing in an App ID and Destination Wallets as parameters, does not work.

Clients must first call the Onramp Session Token API to obtain a token, and pass that token into the Pay SDK as the sessionToken query string parameter when generating the URL manually. The token will expire after a short period of time, and can only be used once. A new token must be obtained for every new session.

Method

POST

URL

https://pay.coinbase.com/api/v1/onramp/token

Request Parameters

The Onramp Session Token API is an RPC endpoint that accepts parameters as JSON in the request body.

Name	Type	Req	Description
destination_wallets	DestinationWallet[]	Y	Array of destination wallet addresses that the purchased crypto should be sent to. Each entry in this array is an object containing an address and an optional list of blockchains or asset IDs that the address supports.

Response Fields

The Onramp Session Token API returns a JSON response including the following fields.

Name	Description
token	A unique string that can be passed into the Pay SDK as the sessionToken parameter when manually generating a URL to initialize the onramp widget (the resulting URL will look like https://pay.coinbase.com/buy/select-asset?sessionToken=<token>&<other params>). This token is associated with the Destination Wallets and App ID header provided in the request. This token can only be used once per session.
channel_id	Not yet functional. Upcoming implementation: A socket.io channel ID that can be used to receive events from the Pay SDK while the customer goes through the transaction flow.

Example Request/Response

Request (cURL)

curl https://pay.coinbase.com/api/v1/onramp/token /
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'CBPAY-VERSION: XXXX-XX-XX' \
  -H 'CBPAY-APP-ID: XXXXXXXXXXXXXXXXXXXXXXXXX' \
  -H 'CBPAY-API-KEY: XXXXXXXXXXXXXXXXXXXXXXXXX' \
  -d '{"destination_wallets": [{"address":"bc1qrdvlkt8rqsyj229thqzhm0q39edwdj2k7yps6x", "blockchains": ["bitcoin"]}]}'

Response 200 (JSON)

{
  "data": {
    "token": "ZWJlNDgwYmItNjBkMi00ZmFiLWIxYTQtMTM3MGI2YjJiNjFh",
    "channel_id": "MzMzNWMzNmItMDYxNy00MjliLTk1MDYtMWRhZTljYzIwNjRl",
  }
}

Transaction Status

The Transaction Status API provides clients with a list of user CBPay transactions. You can poll the real time status of transactions and show users a view of their Coinbase Pay transactions made within the client app.

To link all transactions created during the session, clients must provide the (optional) field partnerUserId as a query parameter when initializing Coinbase Pay.

Transaction Status returns a paginated list of all transactions from newest to oldest. If the client app doesn’t have a concept of a user, clients can pass a random partnerUserId to reference a one-off session.

Method

GET

URL

https://pay.coinbase.com/api/v1/buy/user/{partner_user_id}/transactions?page_key={next_page_key}&page_size={page_size}

Request Parameters

The Transaction Status API is an RPC endpoint that accepts an argument as part of its URL path.

Name	Type	Req	Description
partner_user_id	String	Y	ID referring to user CBPay transactions in client app.
page_key	String	N	Reference to next page of transactions. Returned in previous page’s response.
page_size	Number	N	Number of transactions to return per page. Default is 1.

Response Fields

The Transaction Status API returns a JSON response including the following fields.

Name	Description
transactions	List of OnrampTransactions in reverse chronological order.
next_page_key	A reference to the next page of transactions.
total_count	The total number of transactions made by the user.

OnrampTransaction Schema

Name	Description	Value
status	Current status of the CBPay transaction.	ONRAMP_TRANSACTION_STATUS_CREATED ONRAMP_TRANSACTION_STATUS_IN_PROGRESS ONRAMP_TRANSACTION_STATUS_SUCCESS ONRAMP_TRANSACTION_STATUS_FAILED
purchase_currency	Crypto currency being purchased.	String
purchase_network	Network used to deliver crypto to the user’s wallet.	String
purchase_amount	Amount of crypto currency being purchased.	String
payment_total	Total amount of fiat the user will pay.	String
payment_subtotal	Amount of fiat the user will pay, exclusive of fees	String
coinbase_fee	Amount of fiat charged to cover brokerage fees.	String
network_fee	Amount of fiat charged to cover network fees.	String
exchange_rate	Unit price of the crypto currency being purchased.	String
country	Country the user resides in.	String
user_id	Unique identifier representing the user.	String
payment_method	Type of payment method the user is paying with.	CARD ACH_BANK_ACCOUNT APPLE_PAY FIAT_WALLET CRYPTO_WALLET
tx_hash	The block hash of the onchain send.	String

Example Request/Response

Request (cURL)

curl https://pay.coinbase.com/api/v1/buy/user/{partner_user_id}/transactions?page_key={next_page_key}&page_size={page_size} \
  -H 'Content-Type: application/json' \
  -H 'CBPAY-VERSION: XXXX-XX-XX' \
  -H 'CBPAY-APP-ID: XXXXXXXXXXXXXXXXXXXXXXXXX' \
  -H 'CBPAY-API-KEY: XXXXXXXXXXXXXXXXXXXXXXXXX'

Response 200 (JSON)

{
    "transactions": [
        {
            "status":"ONRAMP_TRANSACTION_STATUS_SUCCESS",
            "purchase_currency": "USDC",
            "purchase_network": "base",
            "purchase_amount": {
                "value": "5",
                "currency": "USDC"
            },
            "payment_total": {
                "value": "5.07",
                "currency": "USD"
            },
            "payment_subtotal": {
                "value": "5",
                "currency": "USD"
            },
            "coinbase_fee": {
                "value": "0",
                "currency": "USD"
            },
            "network_fee": {
                "value": "0.07",
                "currency": "USD"
            },
            "exchange_rate": {
                "value": "1",
                "currency": "USDC"
            },
            "tx_hash": "0x31814ba2fef2a400a9816767370be09ca12d9e9753b972198fe330a0ecedcbf6",
            "created_at": "2023-09-26T20:06:07.076Z",
            "country": "US",
            "user_id": "9f86d081884c7d659a2feaa0c55ad01",
            "payment_method": "CARD",
            "transaction_id": "1ee7a7ec-fdd1-6032-ad91-0e2bacb520d3"
    }
],
"next_page_key":"eyJndF9za2lwIjowLCJvdF9za2lwIjoxfQ==",
"total_count":"3"
}

Transactions

The Transactions API provides clients with a list of CBPay transactions between two dates. The Transactions API is indented for analytics purposes, if you need real time information about a specific transaction, use the Transaction Status API.

Transactions returns a paginated list of all transactions from newest to oldest.

Method

GET

URL

https://pay.coinbase.com/api/v1/buy/transactions?page_key={next_page_key}&page_size={page_size}&start_date={start_date}&end_date={end_date}

Request Parameters

Name	Type	Req	Description
page_key	String	N	Reference to next page of transactions. Returned in previous page’s response.
page_size	Number	N	Number of transactions to return per page. Default is 1000.
start_date	String	N	The start date (inclusive) of the range of transactions to return. YYYY-MM-DD format. Default is one month before end_date.
end_date	String	N	The end date (exclusive) of the range of transactions to return. YYYY-MM-DD format. Default is tomorrow.

Response Fields

The Transaction Status API returns a JSON response including the following fields.

Name	Description
transactions	List of OnrampTransactions in reverse chronological order.
next_page_key	A reference to the next page of transactions.

OnrampTransaction Schema

Name	Description	Value
status	Current status of the CBPay transaction.	ONRAMP_TRANSACTION_STATUS_CREATED ONRAMP_TRANSACTION_STATUS_IN_PROGRESS ONRAMP_TRANSACTION_STATUS_SUCCESS ONRAMP_TRANSACTION_STATUS_FAILED
purchase_currency	Crypto currency being purchased.	String
purchase_network	Network used to deliver crypto to the user’s wallet.	String
purchase_amount	Amount of crypto currency being purchased.	String
payment_total	Total amount of fiat the user will pay.	String
payment_subtotal	Amount of fiat the user will pay, exclusive of fees	String
coinbase_fee	Amount of fiat charged to cover brokerage fees.	String
network_fee	Amount of fiat charged to cover network fees.	String
exchange_rate	Unit price of the crypto currency being purchased.	String
country	Country the user resides in.	String
user_id	Unique identifier representing the user.	String
payment_method	Type of payment method the user is paying with.	CARD ACH_BANK_ACCOUNT APPLE_PAY FIAT_WALLET CRYPTO_WALLET
tx_hash	The block hash of the onchain send.	String
wallet_address	The address of the wallet the transaction was sent to.	String

Example Request/Response

Request (cURL)

curl https://pay.coinbase.com/api/v1/buy/user/transactions?page_key={next_page_key}&page_size={page_size}&start_date={start_date}&end_date={end_date} \
  -H 'Content-Type: application/json' \
  -H 'CBPAY-VERSION: XXXX-XX-XX' \
  -H 'CBPAY-APP-ID: XXXXXXXXXXXXXXXXXXXXXXXXX' \
  -H 'CBPAY-API-KEY: XXXXXXXXXXXXXXXXXXXXXXXXX'

Response 200 (JSON)

{
    "transactions": [
        {
            "status":"ONRAMP_TRANSACTION_STATUS_SUCCESS",
            "purchase_currency": "USDC",
            "purchase_network": "base",
            "purchase_amount": {
                "value": "5",
                "currency": "USDC"
            },
            "payment_total": {
                "value": "5.07",
                "currency": "USD"
            },
            "payment_subtotal": {
                "value": "5",
                "currency": "USD"
            },
            "coinbase_fee": {
                "value": "0",
                "currency": "USD"
            },
            "network_fee": {
                "value": "0.07",
                "currency": "USD"
            },
            "exchange_rate": {
                "value": "1",
                "currency": "USDC"
            },
            "tx_hash": "0x31814ba2fef2a400a9816767370be09ca12d9e9753b972198fe330a0ecedcbf6",
            "created_at": "2023-09-26T20:06:07.076Z",
            "country": "US",
            "user_id": "9f86d081884c7d659a2feaa0c55ad01",
            "payment_method": "CARD",
            "transaction_id": "1ee7a7ec-fdd1-6032-ad91-0e2bacb520d3",
            "wallet_address": "0x3d7b51da8AA41270C6e052eE261db4514Ba4D50A"
    }
],
"next_page_key":"eyJndF9za2lwIjowLCJvdF9za2lwIjoxfQ==",
}