Skip to main content
POST
/
api
/
v1
/
payments
Create payment
curl --request POST \
  --url https://payments.coinbase.com/api/v1/payments \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "maxAmount": "<string>",
  "networkId": 123,
  "receiver": "<string>",
  "operator": "<string>",
  "token": "<string>",
  "autoAuthorize": true,
  "autoCapture": true,
  "minFeeBps": 123,
  "maxFeeBps": 123,
  "feeReceiver": "<string>",
  "preApprovalExpiry": "<string>",
  "authorizationExpiry": "<string>",
  "refundExpiry": "<string>",
  "successRedirectUrl": "<string>",
  "failRedirectUrl": "<string>",
  "contractAddress": "<string>",
  "merchant": {
    "name": "<string>",
    "logoUrl": "<string>",
    "locale": "<string>",
    "metadata": {}
  },
  "customer": {
    "locale": "<string>",
    "metadata": {}
  },
  "fiat": {
    "amount": "<string>",
    "currency": "<string>",
    "metadata": {}
  },
  "externalClientReferenceId": "<string>"
}
'
{
  "payment": {
    "entity": "<string>",
    "id": "<string>",
    "maxAmount": "<string>",
    "networkId": 123,
    "receiver": "<string>",
    "maxFeeBps": 123,
    "minFeeBps": 123,
    "feeReceiver": "<string>",
    "salt": "<string>",
    "paymentInfoHash": "<string>",
    "nonce": "<string>",
    "authorizationExpiry": "<string>",
    "preApprovalExpiry": "<string>",
    "refundExpiry": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "operator": "<string>",
    "merchantId": "<string>",
    "link": {
      "id": "<string>",
      "paymentId": "<string>",
      "url": "<string>",
      "maxUsage": 123,
      "usageCount": 123,
      "successRedirectUrl": "<string>",
      "failRedirectUrl": "<string>",
      "successCallbackUrl": "<string>",
      "metadata": {},
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "sourceAddress": "<string>",
    "sourceAsset": "<string>",
    "tokenCollector": "<string>",
    "merchant": {
      "name": "<string>",
      "logoUrl": "<string>",
      "locale": "<string>",
      "metadata": {}
    },
    "customer": {
      "locale": "<string>",
      "metadata": {}
    },
    "fiat": {
      "amount": "<string>",
      "currency": "<string>",
      "metadata": {}
    },
    "metadata": {},
    "autoAuthorize": true,
    "autoCapture": true,
    "externalClientReferenceId": "<string>",
    "version": 123
  }
}

Authorizations

​
Authorization
string
header
required

Authorization header using the Bearer scheme. Learn more about JWT tokens in the Coinbase Developer Portal.

Headers

​
x-idempotency-key
string
required

Unique identifier to ensure request idempotency

Body

application/json

Request payload for creating a payment.

​
maxAmount
string
required

The max amount to be signed by the buyer, in USD with up to 2 decimal places.

Example:

"100.00"

​
networkId
integer<int32>
required

Identifier for the blockchain network.

Example:

"8453"

​
receiver
string
required

The receiver's wallet address (on Base).

Example:

"0xreceiver"

​
operator
string
required

The operator's smart account address for processing payments.

Example:

"0xoperator"

​
token
string

The token address used for the payment. (Default: USDC address for the specified network_id, e.g. 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 for Base Mainnet)

Example:

"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

​
autoAuthorize
boolean

Whether to automatically authorize the transaction once the payer completes the checkout process. (Default: true, unless auto_capture is set). Cannot be true if auto_capture is also true.

Example:

"true"

​
autoCapture
boolean

Whether to auto capture the payment. (Default: false). Cannot be true if auto_authorize is also true.

Example:

"false"

​
minFeeBps
integer<int32>

Min Fee in basis points. (Default: 0)

Example:

"50"

​
maxFeeBps
integer<int32>

Max Fee in basis points. (Default: 0)

Example:

"50"

​
feeReceiver
string

Address that receives the fee. (Default: 0x0000000000000000000000000000000000000000)

Example:

"0xfee789"

​
preApprovalExpiry
string<int64>

Timestamp (in seconds) when the pre-approval expires. After this expiration, the payment can no longer be authorized or captured. Must be at least 1 minute from now. (Default: now() + 1 day)

Example:

"1843954582"

​
authorizationExpiry
string<int64>

Timestamp (in seconds) when the authorization expires. After this expiration, the payment can no longer be captured. Must be at least 1 minute from now. (Default: now() + 7 days)

Example:

"1843954582"

​
refundExpiry
string<int64>

Timestamp (in seconds) when the refund expires. Must be at least 1 minute from now. (Default: now() + 7 days)

Example:

"1843954582"

​
successRedirectUrl
string

URL to redirect on successful payment.

Example:

"https://example.com/success"

​
failRedirectUrl
string

URL to redirect on failed payment.

Example:

"https://example.com/fail"

​
contractAddress
string

Contract address of the Commerce protocol (PaymentEscrow.sol). (Default: PaymentEscrow address for the specified network_id, e.g. 0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff for Base Mainnet)

Example:

"0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff"

​
merchant
Merchant · object

Additional merchant metadata. Does not impact the actual payment transaction.

Example:
{
  "name": "MerchantName",
  "logoUrl": "https://example.com/logo.png",
  "locale": "en-US",
  "metadata": "{}"
}
​
customer
Customer · object

Additional customer metadata. Does not impact the actual payment transaction.

Example:
{ "locale": "en-US", "metadata": "{}" }
​
fiat
fiat · object

Additional fiat currency metadata. Does not impact the actual payment transaction.

Example:
{
  "amount": "10.00",
  "currency": "USD",
  "metadata": "{}"
}
​
externalClientReferenceId
string

External reference ID provided by the client.

Example:

"ext-ref-123"

Response

A successful response.

Response containing the payment ID.

​
payment
Payment · object

The payment information.

Example:
{
  "entity": "payment",
  "id": "payment123",
  "maxAmount": "100.00",
  "networkId": 8453,
  "receiver": "0xreceiver",
  "minFeeBps": 50,
  "maxFeeBps": 50,
  "feeReceiver": "0xcccccccccccccccccccccccccccccccccccccccc",
  "salt": "2334324235415445346745646",
  "paymentInfoHash": "2334324235415445346745646",
  "nonce": "2334324235415445346745646",
  "authorizationExpiry": 1843954582,
  "preApprovalExpiry": 0,
  "refundExpiry": 1843954582,
  "createdAt": "2024-03-20T00:00:00Z",
  "updatedAt": "2024-03-20T00:00:00Z",
  "operator": "0xoperator"
}