Create a purchase quote

curl --request POST \
  --url https://api.perflo.ai/v1/purchase-quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'DPoP: <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "service_id": "<string>"
}
'

import requests

url = "https://api.perflo.ai/v1/purchase-quotes"

payload = { "service_id": "<string>" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "DPoP": "<api-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    DPoP: '<api-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({service_id: '<string>'})
};

fetch('https://api.perflo.ai/v1/purchase-quotes', 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.perflo.ai/v1/purchase-quotes",
  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([
    'service_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "DPoP: <api-key>",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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.perflo.ai/v1/purchase-quotes"

	payload := strings.NewReader("{\n  \"service_id\": \"<string>\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("DPoP", "<api-key>")
	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.perflo.ai/v1/purchase-quotes")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("DPoP", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"service_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.perflo.ai/v1/purchase-quotes")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["DPoP"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"service_id\": \"<string>\"\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "service_id": "<string>",
  "capability": "<string>",
  "price": {
    "asset": "<string>",
    "minor_units": "<string>"
  },
  "available": true,
  "unavailable_reason": "<string>",
  "executable": true,
  "quoted_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

POST

purchase-quotes

Create a purchase quote

curl --request POST \
  --url https://api.perflo.ai/v1/purchase-quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'DPoP: <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "service_id": "<string>"
}
'

import requests

url = "https://api.perflo.ai/v1/purchase-quotes"

payload = { "service_id": "<string>" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "DPoP": "<api-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    DPoP: '<api-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({service_id: '<string>'})
};

fetch('https://api.perflo.ai/v1/purchase-quotes', 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.perflo.ai/v1/purchase-quotes",
  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([
    'service_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "DPoP: <api-key>",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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.perflo.ai/v1/purchase-quotes"

	payload := strings.NewReader("{\n  \"service_id\": \"<string>\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("DPoP", "<api-key>")
	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.perflo.ai/v1/purchase-quotes")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("DPoP", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"service_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.perflo.ai/v1/purchase-quotes")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["DPoP"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"service_id\": \"<string>\"\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "service_id": "<string>",
  "capability": "<string>",
  "price": {
    "asset": "<string>",
    "minor_units": "<string>"
  },
  "available": true,
  "unavailable_reason": "<string>",
  "executable": true,
  "quoted_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "fields": [
    {
      "message": "<string>",
      "path": "<string>"
    }
  ],
  "request_id": "<string>",
  "retryable": true,
  "submission_uncertain": true
}

Authorizations

DPoP

string

header

required

Per-request RFC 9449 DPoP proof signed with ES256. Protected requests use Authorization: DPoP your_access_token_here. Create a new proof for the exact method and normalized target URI, and include the server nonce when challenged.

Authorization

string

header

required

OAuth 2.0 with RFC 9700 security practices. Discover exact environment endpoints from /.well-known/openid-configuration and /.well-known/oauth-authorization-server, and discover the resource from /.well-known/oauth-protected-resource. Authorization-code clients use PKCE S256, the exact environment resource, nonce with openid, and DPoP binding. Confidential clients also require PAR and private_key_jwt. Access and refresh tokens are sender-constrained with DPoP. purchases:execute is unavailable and omitted from this scope registry.

Headers

X-Request-Id

string

Optional caller request identifier. Unsafe values are replaced with a generated UUID.

Pattern: ^[A-Za-z0-9._~-]{8,128}$

Idempotency-Key

string

required

A new 256-bit random value encoded as 43 unpadded base64url characters. Reuse it only for the same request intent.

Pattern: ^[A-Za-z0-9_-]{43}$

Body

application/json

A request to observe current economics for one catalog service.

service_id

string

required

Stable public marketplace service identifier.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$

Response

The durable non-executable purchase quote.

A five-minute non-executable catalog observation without provider references.

string<uuid>

required

Gateway-owned durable quote identifier.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

service_id

string

required

Stable public marketplace service identifier.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$

capability

string

required

Stable public service capability.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

price

object

required

Observed catalog price.

Show child attributes

available

boolean

required

Whether the catalog service was currently routable.

unavailable_reason

string | null

required

Safe unavailability reason, or null when available.

Pattern: ^[a-z][a-z0-9_]{0,99}$

executable

boolean

required

Always false while exact purchase execution is blocked.

quoted_at

string<date-time>

required

Local time at which the catalog economics were observed.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

expires_at

string<date-time>

required

Local quote expiry exactly five minutes after observation.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

⌘I

system

operations

operation-webhooks

identity

kyc

accounts

activity

reference-data

authorization

services

cards

spending

purchases

beneficiaries

transfer-quotes

Create a purchase quote

Authorizations

Headers

Body

Response