Capture payment - Coinbase Developer Documentation

Capture payment

curl --request POST \
  --url https://payments.coinbase.com/api/v1/payments/{paymentId}/capture \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "amount": "<string>",
  "feeBps": 123,
  "feeReceiver": "<string>",
  "distributeRewards": [
    {
      "campaignAddress": "<string>",
      "tokenAddress": "<string>",
      "chainId": 123
    }
  ],
  "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}

capture

Capture payment

curl --request POST \
  --url https://payments.coinbase.com/api/v1/payments/{paymentId}/capture \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "amount": "<string>",
  "feeBps": 123,
  "feeReceiver": "<string>",
  "distributeRewards": [
    {
      "campaignAddress": "<string>",
      "tokenAddress": "<string>",
      "chainId": 123
    }
  ],
  "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 capture.

Body

application/json

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

amount

string

required

Amount to capture in the escrow protocol.

feeBps

integer<int32>

required

Fee in basis points.

feeReceiver

string

required

Address of the fee receiver.

distributeRewards

RewardInput · object[]

List of rewards to distribute during payment capture.

Show child attributes

distributeRewards.campaignAddress

string

required

The onchain address of the campaign

distributeRewards.tokenAddress

string

required

The token address for the rewards

distributeRewards.chainId

integer<int32>

required

The chain ID where the campaign is deployed

metadata

Metadata · object

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

Response

A successful response.

Response payload for payment capture 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

Charge payment

Void payment

⌘I

PAYMENT ACCEPTANCE

Authorizations

Headers

Path Parameters

Body

Response