Create a payment intent

curl --request POST \
  --url https://api-sandbox.circle.com/v1/paymentIntents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "paymentMethods": [
    {
      "type": "blockchain",
      "chain": "ETH"
    }
  ],
  "merchantWalletId": "1000662322",
  "type": "continuous",
  "purposeOfTransfer": "PMT001",
  "metadata": {
    "customerExternalRef": "310c458a-18eb-4cbd-8a9a-586d9448ae69"
  }
}
'

import requests

url = "https://api-sandbox.circle.com/v1/paymentIntents"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "paymentMethods": [
        {
            "type": "blockchain",
            "chain": "ETH"
        }
    ],
    "merchantWalletId": "1000662322",
    "type": "continuous",
    "purposeOfTransfer": "PMT001",
    "metadata": { "customerExternalRef": "310c458a-18eb-4cbd-8a9a-586d9448ae69" }
}
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({
    idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    paymentMethods: [{type: 'blockchain', chain: 'ETH'}],
    merchantWalletId: '1000662322',
    type: 'continuous',
    purposeOfTransfer: 'PMT001',
    metadata: {customerExternalRef: '310c458a-18eb-4cbd-8a9a-586d9448ae69'}
  })
};

fetch('https://api-sandbox.circle.com/v1/paymentIntents', 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-sandbox.circle.com/v1/paymentIntents",
  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([
    'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    'paymentMethods' => [
        [
                'type' => 'blockchain',
                'chain' => 'ETH'
        ]
    ],
    'merchantWalletId' => '1000662322',
    'type' => 'continuous',
    'purposeOfTransfer' => 'PMT001',
    'metadata' => [
        'customerExternalRef' => '310c458a-18eb-4cbd-8a9a-586d9448ae69'
    ]
  ]),
  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-sandbox.circle.com/v1/paymentIntents"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentMethods\": [\n    {\n      \"type\": \"blockchain\",\n      \"chain\": \"ETH\"\n    }\n  ],\n  \"merchantWalletId\": \"1000662322\",\n  \"type\": \"continuous\",\n  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"310c458a-18eb-4cbd-8a9a-586d9448ae69\"\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-sandbox.circle.com/v1/paymentIntents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentMethods\": [\n    {\n      \"type\": \"blockchain\",\n      \"chain\": \"ETH\"\n    }\n  ],\n  \"merchantWalletId\": \"1000662322\",\n  \"type\": \"continuous\",\n  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"310c458a-18eb-4cbd-8a9a-586d9448ae69\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/paymentIntents")

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  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentMethods\": [\n    {\n      \"type\": \"blockchain\",\n      \"chain\": \"ETH\"\n    }\n  ],\n  \"merchantWalletId\": \"1000662322\",\n  \"type\": \"continuous\",\n  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"310c458a-18eb-4cbd-8a9a-586d9448ae69\"\n  }\n}"

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

{
  "data": {
    "amount": {
      "amount": "3.14",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F"
      }
    ],
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "amountPaid": {
      "amount": "3.14",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "3.14",
      "currency": "USD"
    },
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "3.14",
        "currency": "USD"
      }
    ],
    "paymentIds": [
      "69808f36-3e5e-4f37-bf82-ca79e4d70fc1"
    ],
    "refundIds": [
      "425dca6d-ac79-43b6-b0f9-43fdc51de91b"
    ],
    "timeline": [
      {
        "status": "created",
        "time": "2023-11-07T05:31:56Z",
        "context": "underpaid",
        "reason": "requested_by_merchant"
      }
    ],
    "expiresOn": "2020-04-10T02:13:30.000Z",
    "updateDate": "2020-04-10T02:13:30.000Z",
    "createDate": "2020-04-10T02:13:30.000Z",
    "merchantWalletId": "1000662322",
    "purposeOfTransfer": "PMT001",
    "customerExternalRef": "310c458a-18eb-4cbd-8a9a-586d9448ae69"
  }
}

{
  "code": 2,
  "message": "API parameter invalid."
}

{
  "code": 4,
  "message": "Unauthorized."
}

{
  "code": 3,
  "message": "Missing permission."
}

{
  "code": 404,
  "message": "Not found."
}

{
  "code": 2,
  "message": "Invalid value for field 'expiresOn'"
}

{
  "code": -1,
  "message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}

{
  "code": 2,
  "message": "API parameter invalid.",
  "externalMessage": "The provided amount exceeds the maximum allowed.",
  "errors": [
    {
      "error": "invalid_value",
      "message": "The operation and assetType combination is invalid.",
      "location": "assetType"
    }
  ]
}

Create a payment intent

Create a continuous or transient payment intent. Always set type: when it is omitted, the default type depends on account configuration.

Digital Asset Accounts: crypto payments are available only for custody accounts (purpose: custody) and are for third-party payments only. They are not supported when the distributor or the end user is under the Circle FR (CIRCLE_FR) or Circle SG (CIRCLE_SG) legal entity. Set merchantWalletId to the accountId of the end user’s custody account. Requests that target the master wallet, either by omitting merchantWalletId or by passing the distributor’s own master wallet ID, are rejected with 403.

purposeOfTransfer is required for Circle Inc (CIRCLE_INC) entities with Managed Payments enabled and optional otherwise. PMT006 is not allowed.

POST

paymentIntents

Create a payment intent

curl --request POST \
  --url https://api-sandbox.circle.com/v1/paymentIntents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "paymentMethods": [
    {
      "type": "blockchain",
      "chain": "ETH"
    }
  ],
  "merchantWalletId": "1000662322",
  "type": "continuous",
  "purposeOfTransfer": "PMT001",
  "metadata": {
    "customerExternalRef": "310c458a-18eb-4cbd-8a9a-586d9448ae69"
  }
}
'

import requests

url = "https://api-sandbox.circle.com/v1/paymentIntents"

payload = {
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "paymentMethods": [
        {
            "type": "blockchain",
            "chain": "ETH"
        }
    ],
    "merchantWalletId": "1000662322",
    "type": "continuous",
    "purposeOfTransfer": "PMT001",
    "metadata": { "customerExternalRef": "310c458a-18eb-4cbd-8a9a-586d9448ae69" }
}
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({
    idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    paymentMethods: [{type: 'blockchain', chain: 'ETH'}],
    merchantWalletId: '1000662322',
    type: 'continuous',
    purposeOfTransfer: 'PMT001',
    metadata: {customerExternalRef: '310c458a-18eb-4cbd-8a9a-586d9448ae69'}
  })
};

fetch('https://api-sandbox.circle.com/v1/paymentIntents', 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-sandbox.circle.com/v1/paymentIntents",
  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([
    'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
    'paymentMethods' => [
        [
                'type' => 'blockchain',
                'chain' => 'ETH'
        ]
    ],
    'merchantWalletId' => '1000662322',
    'type' => 'continuous',
    'purposeOfTransfer' => 'PMT001',
    'metadata' => [
        'customerExternalRef' => '310c458a-18eb-4cbd-8a9a-586d9448ae69'
    ]
  ]),
  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-sandbox.circle.com/v1/paymentIntents"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentMethods\": [\n    {\n      \"type\": \"blockchain\",\n      \"chain\": \"ETH\"\n    }\n  ],\n  \"merchantWalletId\": \"1000662322\",\n  \"type\": \"continuous\",\n  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"310c458a-18eb-4cbd-8a9a-586d9448ae69\"\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-sandbox.circle.com/v1/paymentIntents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentMethods\": [\n    {\n      \"type\": \"blockchain\",\n      \"chain\": \"ETH\"\n    }\n  ],\n  \"merchantWalletId\": \"1000662322\",\n  \"type\": \"continuous\",\n  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"310c458a-18eb-4cbd-8a9a-586d9448ae69\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/paymentIntents")

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  \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n  \"paymentMethods\": [\n    {\n      \"type\": \"blockchain\",\n      \"chain\": \"ETH\"\n    }\n  ],\n  \"merchantWalletId\": \"1000662322\",\n  \"type\": \"continuous\",\n  \"purposeOfTransfer\": \"PMT001\",\n  \"metadata\": {\n    \"customerExternalRef\": \"310c458a-18eb-4cbd-8a9a-586d9448ae69\"\n  }\n}"

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

{
  "data": {
    "amount": {
      "amount": "3.14",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F"
      }
    ],
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "amountPaid": {
      "amount": "3.14",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "3.14",
      "currency": "USD"
    },
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "3.14",
        "currency": "USD"
      }
    ],
    "paymentIds": [
      "69808f36-3e5e-4f37-bf82-ca79e4d70fc1"
    ],
    "refundIds": [
      "425dca6d-ac79-43b6-b0f9-43fdc51de91b"
    ],
    "timeline": [
      {
        "status": "created",
        "time": "2023-11-07T05:31:56Z",
        "context": "underpaid",
        "reason": "requested_by_merchant"
      }
    ],
    "expiresOn": "2020-04-10T02:13:30.000Z",
    "updateDate": "2020-04-10T02:13:30.000Z",
    "createDate": "2020-04-10T02:13:30.000Z",
    "merchantWalletId": "1000662322",
    "purposeOfTransfer": "PMT001",
    "customerExternalRef": "310c458a-18eb-4cbd-8a9a-586d9448ae69"
  }
}

{
  "code": 2,
  "message": "API parameter invalid."
}

{
  "code": 4,
  "message": "Unauthorized."
}

{
  "code": 3,
  "message": "Missing permission."
}

{
  "code": 404,
  "message": "Not found."
}

{
  "code": 2,
  "message": "Invalid value for field 'expiresOn'"
}

{
  "code": -1,
  "message": "Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4"
}

{
  "code": 2,
  "message": "API parameter invalid.",
  "externalMessage": "The provided amount exceeds the maximum allowed.",
  "errors": [
    {
      "error": "invalid_value",
      "message": "The operation and assetType combination is invalid.",
      "location": "assetType"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Continuous payment intent
Transient payment intent

idempotencyKey

string<uuid>

required

Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests.

Example:

"ba943ff1-ca16-49b2-ba55-1057e70ca5c7"

currency

enum<string>

required

Desired currency for the payment.

Available options:

USD,

EUR

settlementCurrency

enum<string>

required

Desired currency for the payments to settle in. This must match the currency used for the payment.

Available options:

USD,

EUR

paymentMethods

object[]

required

Exactly one blockchain payment method.

Required array length: 1 element

Show child attributes

merchantWalletId

string

required

The accountId of the end user's custody account that receives the payment. Required for Digital Asset Accounts: omitting it, or passing the distributor's own master wallet ID, is rejected with 403.

Maximum string length: 36

Example:

"1000662322"

type

enum<string>

required

Payment intent type. Must be set to continuous for continuous payment intents.

Available options:

continuous

purposeOfTransfer

enum<string>

Payment reason code describing the purpose of the transfer for the payment intent.

Required for Circle Inc (CIRCLE_INC) entities with Managed Payments enabled. Optional otherwise.

PMT006 (Transfer to own account) is not allowed for payment intents. A missing value (when required) or a disallowed or invalid value returns error code INVALID_PURPOSE_OF_TRANSFER.

Available options:

PMT000,

PMT001,

PMT002,

PMT003,

PMT004,

PMT005,

PMT007,

PMT008,

PMT009,

PMT010,

PMT011,

PMT012,

PMT013,

PMT014,

PMT015,

PMT016,

PMT017,

PMT018,

PMT019,

PMT020,

PMT021,

PMT022,

PMT023,

PMT024,

PMT025,

PMT026,

PMT027,

PMT028,

PMT029,

PMT030

Example:

"PMT001"

metadata

object

Optional metadata associated with the payment intent.

Show child attributes

Response

Successfully created a payment intent.

data

object

A transient payment intent.

Option 1
Option 2

Show child attributes