Skip to main content
POST
/
api
/
v1
/
payments
/
{paymentId}
/
authorize
Authorize payment
curl --request POST \
  --url https://payments.coinbase.com/api/v1/payments/{paymentId}/authorize \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "amount": "<string>",
  "allocateRewards": [
    {
      "campaignAddress": "<string>",
      "tokenAddress": "<string>",
      "chainId": 123
    }
  ],
  "merchantId": "<string>",
  "metadata": {}
}
'
{
  "operationId": "<string>",
  "rewardOperations": [
    {
      "id": "<string>",
      "action": "REWARD_OPERATION_ACTION_ALLOCATE",
      "status": "REWARD_OPERATION_STATUS_PENDING",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "reward": {
        "id": "<string>",
        "campaignAddress": "<string>",
        "paymentInfoHash": "<string>",
        "recipientAddress": "<string>",
        "tokenAddress": "<string>",
        "chainId": 123,
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "amount": "<string>",
      "transactionHash": "<string>",
      "error": "<string>",
      "errorCode": "<string>",
      "revertReason": "<string>",
      "blockNumber": "<string>",
      "metadata": {},
      "operationSteps": [
        {
          "entity": "<string>",
          "id": "<string>",
          "type": "OPERATION_STEP_TYPE_AUTH_ESCROW",
          "operationId": "<string>",
          "operationType": "OPERATION_TYPE_PAYMENT",
          "status": "OPERATION_STEP_STATUS_SUCCEEDED",
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z",
          "params": {},
          "error": "<string>",
          "errorCode": "<string>",
          "transactions": [
            {
              "entity": "<string>",
              "transactionHash": "<string>",
              "blockNumber": "<string>",
              "createdAt": "2023-11-07T05:31:56Z",
              "updatedAt": "2023-11-07T05:31:56Z",
              "revertReason": "<string>",
              "operationStepId": "<string>"
            }
          ]
        }
      ]
    }
  ],
  "invalidRewardInputs": [
    {
      "rewardInput": {
        "campaignAddress": "<string>",
        "tokenAddress": "<string>",
        "chainId": 123
      },
      "invalidReason": "<string>"
    }
  ]
}

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

Path Parameters

​
paymentId
string
required

The unique identifier of the payment to authorize.

Body

application/json

Request payload for authorizing a payment using the payment ID. This simplified endpoint fetches payment details from the database.

​
amount
string
required

Amount to authorize in the escrow protocol.

Example:

"50.00"

​
allocateRewards
RewardInput · object[]

List of rewards to allocate during payment authorization.

Example:
[
  {
    "campaignAddress": "0x1234567890123456789012345678901234567890",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "chainId": 8453
  }
]
​
merchantId
string

Custom merchant ID, which will be returned in the webhook.

Example:

"merchant123"

​
metadata
Metadata · object

Metadata for the payment operation that will be returned in the webhook.

Example:
{ "key": "value" }

Response

A successful response.

Response payload for payment authorization requests.

​
operationId
string
required

Identifier for the payment operation.

Example:

"op-2341434"

​
rewardOperations
RewardOperation · object[]

List of reward operations with detailed information, if rewards were processed.

Example:
[
  {
    "id": "ro-5678901",
    "reward": {
      "id": "rw-123456",
      "campaignAddress": "0x1234567890123456789012345678901234567890",
      "paymentInfoHash": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
      "recipientAddress": "0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": 8453,
      "createdAt": "2024-03-20T00:00:00.000Z",
      "updatedAt": "2024-03-20T00:30:00.000Z"
    },
    "action": "REWARD_OPERATION_ACTION_ALLOCATE",
    "amount": "100.00",
    "status": "REWARD_OPERATION_STATUS_PENDING",
    "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "createdAt": "2024-03-20T00:00:00.000Z",
    "updatedAt": "2024-03-20T00:30:00.000Z",
    "metadata": { "key": "value" }
  }
]
​
invalidRewardInputs
InvalidRewardInput · object[]

List of rewards that were invalid/unable to be processed with detailed reasoning

Example:
[
  {
    "rewardInput": {
      "campaignAddress": "0x1234567890123456789012345678901234567890",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": 8453
    },
    "invalidReason": "invalid campaign address"
  }
]