Capture a payment session

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "1.00",
  "finalCapture": true,
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  }
}
'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures"

payload = {
    "amount": "1.00",
    "finalCapture": True,
    "metadata": {
        "customer_id": "cust_12345",
        "order_reference": "order-67890"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: '1.00',
    finalCapture: true,
    metadata: {customer_id: 'cust_12345', order_reference: 'order-67890'}
  })
};

fetch('https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '1.00',
    'finalCapture' => true,
    'metadata' => [
        'customer_id' => 'cust_12345',
        'order_reference' => 'order-67890'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures"

	payload := strings.NewReader("{\n  \"amount\": \"1.00\",\n  \"finalCapture\": true,\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"1.00\",\n  \"finalCapture\": true,\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"1.00\",\n  \"finalCapture\": true,\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "captureId": "capture_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "status": "pending",
  "amount": "1.00",
  "finalCapture": true,
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  },
  "createdAt": "2025-06-15T12:20:00.000Z",
  "updatedAt": "2025-06-15T12:20:00.000Z"
}

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid capture parameters."
}

{
  "errorType": "not_found",
  "errorMessage": "Payment session with the given ID does not exist."
}

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."
}

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later."
}

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later."
}

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. Please try again later."
}

POST

payment-sessions

{paymentSessionId}

captures

Capture a payment session

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "1.00",
  "finalCapture": true,
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  }
}
'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures"

payload = {
    "amount": "1.00",
    "finalCapture": True,
    "metadata": {
        "customer_id": "cust_12345",
        "order_reference": "order-67890"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: '1.00',
    finalCapture: true,
    metadata: {customer_id: 'cust_12345', order_reference: 'order-67890'}
  })
};

fetch('https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '1.00',
    'finalCapture' => true,
    'metadata' => [
        'customer_id' => 'cust_12345',
        'order_reference' => 'order-67890'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures"

	payload := strings.NewReader("{\n  \"amount\": \"1.00\",\n  \"finalCapture\": true,\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"1.00\",\n  \"finalCapture\": true,\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/captures")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"1.00\",\n  \"finalCapture\": true,\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "captureId": "capture_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "status": "pending",
  "amount": "1.00",
  "finalCapture": true,
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  },
  "createdAt": "2025-06-15T12:20:00.000Z",
  "updatedAt": "2025-06-15T12:20:00.000Z"
}

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid capture parameters."
}

{
  "errorType": "not_found",
  "errorMessage": "Payment session with the given ID does not exist."
}

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."
}

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later."
}

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later."
}

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. Please try again later."
}

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Headers

X-Idempotency-Key

string

An optional string request header for making requests safely retryable. When included, duplicate requests with the same key will return identical responses. Refer to our Idempotency docs for more information on using idempotency keys.

Required string length: 1 - 128

Path Parameters

paymentSessionId

string

required

The unique identifier of the payment session. The ID of the payment session, a UUID prefixed by paymentSession_.

Pattern: ^paymentSession_[a-f0-9\-]{36}$

Example:

"paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

Body

application/json

A request to create a capture for a payment session.

finalCapture

boolean

required

When true, this capture is treated as the final one for the authorization. Any remaining capturable balance is released back to the payer immediately after the capture settles. When false, the remaining capturable balance stays held and is available for subsequent partial captures (subject to captureExpiresAt). Has no effect if amount equals the full capturable balance, since no remaining balance exists to release.

Example:

true

amount

string

A decimal representation of the amount to capture, denominated in the session's asset. If omitted, the full remaining capturable amount is captured.

Example:

"1.00"

metadata

object

Optional metadata as key-value pairs. Use this to store additional structured information on a resource, such as customer IDs, order references, or any application-specific data. Up to 10 key/value pairs may be provided. Keys and values are both strings. Keys must be ≤ 40 characters; values must be ≤ 500 characters.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

externalReferenceId

string

An optional merchant-provided internal identifier for this manual capture, from the merchant's own system—not visible to the payer.

Maximum string length: 256

Example:

"merchant-capture-abc123"

customerDisplay

Operation Customer Display · object

Optional customer-facing display data for this manual capture, shown to the payer. Falls back to the session's orderCode when referenceCode is omitted.

Show child attributes

Example:

{ "referenceCode": "REF-ABC123" }

Response

Successfully created capture.

A collection of authorized funds. Multiple partial captures are allowed up to the authorized amount. Each capture settles funds to the merchant's target.

finalCapture

boolean

required

Example:

true

captureId

string

The unique identifier of the capture.

Pattern: ^capture_[a-f0-9\-]{36}$

Example:

"capture_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

paymentSessionId

string

The ID of the payment session this capture belongs to.

Pattern: ^paymentSession_[a-f0-9\-]{36}$

Example:

"paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

status

enum<string>

The current status of the capture.

Available options:

pending,

succeeded,

failed

Example:

"pending"

amount

string

A decimal representation of the captured amount, denominated in the session's asset.

Example:

"1.00"

error

object

An error that occurred during a payment operation.

Show child attributes

Example:

{
  "code": "insufficient_funds",
  "message": "The payer does not have sufficient funds.",
  "occurredAt": "2025-06-15T12:00:00.000Z"
}

metadata

object

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

externalReferenceId

string

A merchant-provided internal identifier for this capture, from the merchant's own system—not visible to the payer. A manual capture uses the caller-provided value; an auto-capture reuses the authorization's value and omits it when the authorization omitted it. It never falls back to PaymentSession.externalReferenceId.

Maximum string length: 256

Example:

"merchant-capture-abc123"

customerDisplay

Operation Customer Display · object

Customer-facing display data for this capture, shown to the payer. A manual capture falls back to the session's orderCode when referenceCode is omitted; an auto-capture reuses the authorization's referenceCode.

Show child attributes

Example:

{ "referenceCode": "REF-ABC123" }

onchainTransactions

object[]

The onchain transactions associated with this capture.

Show child attributes

Example:

[
  {
    "transactionHash": "0xdef456abc789012345678901234567890abcdef1234567890abcdef12345678",
    "network": "base"
  }
]

createdAt

string<date-time>

The UTC ISO 8601 timestamp at which the capture was created.

Example:

"2025-06-15T12:20:00.000Z"

updatedAt

string<date-time>

The UTC ISO 8601 timestamp at which the capture was last updated.

Example:

"2025-06-15T12:21:00.000Z"