Authorize a payment session with a mandate

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/authorizations/mandate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  }
}
'

import requests

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

payload = {
    "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
    "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({
    mandateId: 'mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad',
    metadata: {customer_id: 'cust_12345', order_reference: 'order-67890'}
  })
};

fetch('https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/authorizations/mandate', 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}/authorizations/mandate",
  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([
    'mandateId' => 'mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad',
    '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}/authorizations/mandate"

	payload := strings.NewReader("{\n  \"mandateId\": \"mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad\",\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}/authorizations/mandate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"mandateId\": \"mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad\",\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}/authorizations/mandate")

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  \"mandateId\": \"mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad\",\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}"

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

{
  "authorizationId": "authorization_93d980d2-95f2-55fe-b9d3-2bd340cf10be",
  "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "status": "pending",
  "amount": "1.00",
  "source": {
    "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
    "network": "base",
    "asset": "usdc"
  },
  "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  },
  "createdAt": "2025-06-20T09:30:00.000Z",
  "updatedAt": "2025-06-20T09:30:00.000Z"
}

Payment Sessions

Authorize a payment session with a mandate

Merchant-initiated. The merchant draws against a mandate in approval_succeeded status using the mandate’s existing approval, so no fresh signature is required and the customer does not need to be present. The session must be in created status and the mandate must be in approval_succeeded status. When more than one mandate condition applies, the first match wins: an in-flight approval or revocation returns 409 (mandate_action_pending); revokedAt set returns 422 (mandate_revoked); canceledAt set returns 422 (mandate_canceled); a past expiresAt returns 400 (mandate_expired); any other status returns 422 (mandate_invalid_status).

It requires API key authentication: unlike the payer-present wallet flow there is no per-call signature to prove consent, so the merchant authenticates as the party entitled to draw against the mandate.

The charge must fall within the mandate’s policy. Exceeding maxPerAuthorization or maxPerPeriod returns 422 (mandate_policy_violation).

On authorization, a hold is placed on the payer’s funds. The authorization is returned in pending status and transitions asynchronously to succeeded or failed. If autoCapture is enabled on the session, a capture is automatically created after a successful authorization.

POST

payment-sessions

{paymentSessionId}

authorizations

mandate

Authorize a payment session with a mandate

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/authorizations/mandate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  }
}
'

import requests

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

payload = {
    "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
    "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({
    mandateId: 'mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad',
    metadata: {customer_id: 'cust_12345', order_reference: 'order-67890'}
  })
};

fetch('https://api.cdp.coinbase.com/platform/v2/payment-sessions/{paymentSessionId}/authorizations/mandate', 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}/authorizations/mandate",
  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([
    'mandateId' => 'mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad',
    '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}/authorizations/mandate"

	payload := strings.NewReader("{\n  \"mandateId\": \"mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad\",\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}/authorizations/mandate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"mandateId\": \"mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad\",\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}/authorizations/mandate")

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  \"mandateId\": \"mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad\",\n  \"metadata\": {\n    \"customer_id\": \"cust_12345\",\n    \"order_reference\": \"order-67890\"\n  }\n}"

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

{
  "authorizationId": "authorization_93d980d2-95f2-55fe-b9d3-2bd340cf10be",
  "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "status": "pending",
  "amount": "1.00",
  "source": {
    "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
    "network": "base",
    "asset": "usdc"
  },
  "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  },
  "createdAt": "2025-06-20T09:30:00.000Z",
  "updatedAt": "2025-06-20T09:30:00.000Z"
}

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 to authorize. 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 authorize a payment session against a mandate in approval_succeeded status, using the mandate's existing approval. No fresh signature is required. The charge must fall within the mandate's policy.

mandateId

string

required

The ID of the mandate to authorize against. Must be in approval_succeeded status.

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

Example:

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

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

customerDisplay

Operation Customer Display · object

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

Show child attributes

Example:

{ "referenceCode": "REF-ABC123" }

externalReferenceId

string

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

Maximum string length: 256

Example:

"merchant-authorization-abc123"

Response

Successfully created mandate authorization.

A hold placed on the payer's funds. Once authorized, the merchant can capture (collect) the funds. Only one authorization is allowed per session.

authorizationId

string

The unique identifier of the authorization.

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

Example:

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

paymentSessionId

string

The ID of the payment session this authorization belongs to.

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

Example:

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

status

enum<string>

The current status of the authorization.

Available options:

pending,

succeeded,

failed

Example:

"pending"

amount

string

A decimal representation of the authorized 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"
}

message

string

A human-readable message describing the outcome or status for display. Returned for x402 authorizations; omitted for other authorization flows unless documented otherwise.

Example:

"Your payment was successfully submitted"

metadata

object

Show child attributes

Example:

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

externalReferenceId

string

A merchant-provided internal identifier for this authorization, from the merchant's own system—not visible to the payer. Present only when supplied on the authorization request.

Maximum string length: 256

Example:

"merchant-authorization-abc123"

customerDisplay

Operation Customer Display · object

Customer-facing display data for this authorization, shown to the payer. Present when supplied on the authorization request or when the session's orderCode fallback applies; otherwise omitted.

Show child attributes

Example:

{ "referenceCode": "REF-ABC123" }

source

Payment Source Wallet · object

The payer for this authorization. For wallet authorizations, this is the blockchain address that signed the payloads. For Coinbase authorizations, this is the authenticated Coinbase account. This value is also reflected on the parent payment session's source field after a successful authorization.

Payment Source Wallet
Payment Source Coinbase

Show child attributes

Example:

{
  "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
  "network": "base",
  "asset": "usdc"
}

onchainTransactions

object[]

The onchain transactions associated with this authorization.

Show child attributes

Example:

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

createdAt

string<date-time>

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

Example:

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

updatedAt

string<date-time>

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

Example:

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