Authorize payment - Coinbase Developer Documentation

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

POST

api

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.

allocateRewards

RewardInput · object[]

List of rewards to allocate during payment authorization.

Show child attributes

allocateRewards.campaignAddress

string

required

The onchain address of the campaign

allocateRewards.tokenAddress

string

required

The token address for the rewards

allocateRewards.chainId

integer<int32>

required

The chain ID where the campaign is deployed

merchantId

string

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

metadata

Metadata · object

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

Response

A successful response.

Response payload for payment authorization requests.

operationId

string

required

Identifier for the payment operation.

rewardOperations

RewardOperation · object[]

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

Show child attributes

rewardOperations.id

string

required

Unique identifier for the reward operation.

rewardOperations.action

enum<string>

required

Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE).

Available options:

REWARD_OPERATION_ACTION_ALLOCATE,

REWARD_OPERATION_ACTION_DEALLOCATE,

REWARD_OPERATION_ACTION_DISTRIBUTE,

REWARD_OPERATION_ACTION_SEND

rewardOperations.status

enum<string>

required

Current status of the reward operation.

Available options:

REWARD_OPERATION_STATUS_PENDING,

REWARD_OPERATION_STATUS_SUCCEEDED,

REWARD_OPERATION_STATUS_FAILED

rewardOperations.createdAt

string<date-time>

required

Timestamp when the reward operation was created.

rewardOperations.updatedAt

string<date-time>

required

Timestamp when the reward operation was last updated.

rewardOperations.reward

Reward · object

Detailed reward object associated with this operation.

Show child attributes

rewardOperations.reward.id

string

required

Unique identifier for the reward.

rewardOperations.reward.campaignAddress

string

required

Onchain address of the campaign contract.

rewardOperations.reward.paymentInfoHash

string

required

Hash of the payment info that this reward is associated with.

rewardOperations.reward.recipientAddress

string

required

Blockchain address that will receive the reward.

rewardOperations.reward.tokenAddress

string

required

Address of the token contract used for the reward.

rewardOperations.reward.chainId

integer<int32>

required

The blockchain network identifier where the reward is processed.

rewardOperations.reward.createdAt

string<date-time>

required

Timestamp when the reward was created.

rewardOperations.reward.updatedAt

string<date-time>

required

Timestamp when the reward was last updated.

rewardOperations.amount

string

Amount involved in this reward operation.

rewardOperations.transactionHash

string

Blockchain transaction hash for this reward operation.

rewardOperations.error

string

Error message if the reward operation failed.

rewardOperations.errorCode

string

Error code of the reward operation.

rewardOperations.revertReason

string

Blockchain revert reason of the reward operation.

rewardOperations.blockNumber

string<int64>

Block number of the reward operation.

rewardOperations.metadata

Metadata · object

Additional metadata as a free-form object.

rewardOperations.operationSteps

OperationStep · object[]

List of operation steps associated with this reward operation.

Show child attributes

rewardOperations.operationSteps.entity

string

required

Entity type, usually 'operation-step'.

rewardOperations.operationSteps.id

string

required

Unique identifier of the operation step.

rewardOperations.operationSteps.type

enum<string>

required

Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL).

Available options:

OPERATION_STEP_TYPE_AUTH_ESCROW,

OPERATION_STEP_TYPE_CROSSCHAIN,

OPERATION_STEP_TYPE_FLYWHEEL

rewardOperations.operationSteps.operationId

string

required

Identifier of the parent operation.

rewardOperations.operationSteps.operationType

enum<string>

required

Type of the parent operation (e.g., PAYMENT, REWARD).

Available options:

OPERATION_TYPE_PAYMENT,

OPERATION_TYPE_REWARD

rewardOperations.operationSteps.status

enum<string>

required

Current status of the operation step.

Available options:

OPERATION_STEP_STATUS_SUCCEEDED,

OPERATION_STEP_STATUS_FAILED,

OPERATION_STEP_STATUS_PENDING

rewardOperations.operationSteps.createdAt

string<date-time>

required

Timestamp when the operation step was created.

rewardOperations.operationSteps.updatedAt

string<date-time>

required

Timestamp when the operation step was last updated.

rewardOperations.operationSteps.params

Params · object

Parameters for the operation step as a free-form object.

rewardOperations.operationSteps.error

string

Error message if the operation step failed.

rewardOperations.operationSteps.errorCode

string

Error code if the operation step failed.

rewardOperations.operationSteps.transactions

Transaction · object[]

Blockchain transactions associated with this operation step.

Show child attributes

rewardOperations.operationSteps.transactions.entity

string

required

Entity type, usually 'transaction'.

rewardOperations.operationSteps.transactions.transactionHash

string

required

Blockchain transaction hash.

rewardOperations.operationSteps.transactions.blockNumber

string<int64>

required

Block number where the transaction was included.

rewardOperations.operationSteps.transactions.createdAt

string<date-time>

required

Timestamp when the transaction record was created.

rewardOperations.operationSteps.transactions.updatedAt

string<date-time>

required

Timestamp when the transaction record was last updated.

rewardOperations.operationSteps.transactions.revertReason

string

Revert reason if the transaction failed.

rewardOperations.operationSteps.transactions.operationStepId

string

Identifier of the operation step this transaction belongs to.

invalidRewardInputs

InvalidRewardInput · object[]

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

Show child attributes

invalidRewardInputs.rewardInput

Reward Input · object

The reward input that was invalid

Show child attributes

invalidRewardInputs.rewardInput.campaignAddress

string

required

The onchain address of the campaign

invalidRewardInputs.rewardInput.tokenAddress

string

required

The token address for the rewards

invalidRewardInputs.rewardInput.chainId

integer<int32>

required

The chain ID where the campaign is deployed

invalidRewardInputs.invalidReason

string

Reason why this reward input is invalid

Update payment link status

Charge payment

⌘I

PAYMENT ACCEPTANCE

Authorizations

Headers

Path Parameters

Body

Response