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)
Response 200 (JSON)

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'

{
  "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)
Response 200 (JSON)

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'

{
  "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

GET

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)
Response 200 (JSON)

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"}'

{
  "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"
  }
}

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`

Example Request/Response

Request (cURL)
Response 200 (JSON)

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'

{
    "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"
}

Was this helpful?

Buy Config​

Method​

URL​

Request Parameters​

Response Fields​

Example Request/Response​

Buy Options​

Method​

URL​

Request Parameters​

Response Fields​

Example Request/Response​

Buy Quote​

Method​

URL​

Request Parameters​

Response Fields​

Example Request/Response​

Transaction Status​

Method​

URL​

Request Parameters​

Response Fields​

OnrampTransaction Schema​

Example Request/Response​

Buy Config

Method

URL

Request Parameters

Response Fields

Example Request/Response

Buy Options

Method

URL

Request Parameters

Response Fields

Example Request/Response

Buy Quote

Method

URL

Request Parameters

Response Fields

Example Request/Response

Transaction Status

Method

URL

Request Parameters

Response Fields

OnrampTransaction Schema

Example Request/Response