API Reference

Get details for an RFI

gethttps://api.circle.com/v1/cpn/payments/{paymentId}/rfis/{rfiId}

Reference
Playground

Retrieve details of a specific RFI for a payment. If the BFI initiates an RFI after the payment is created, the OFI will be notified via webhook. This webhook will detail what specific information the OFI needs to send.

After receiving the webhook. The OFI is expected to encrypt the requested data and send it to the BFI using CPN's RFI submit endpoint. Failure to respond to an RFI will result in a failed payment. The OFI will receive webhooks with the decision based on the submitted information.

Path parameters

rfiId

uuid

Required

The RFI id created previously.

paymentId

uuid

Required

The payment id created previously.

Response

200RfiResponse

Response Body

object

data

object

Required

Response schema for Request for Information (RFI) details

Show 8 properties

string

Required

System-generated unique identifier of the resource.

paymentId

string

Required

System-generated unique identifier of the resource.

status

string

Required

Status of the RFI (Request for Information)

Allowed valuesINFORMATION_REQUIREDIN_REVIEWAPPROVEDREJECTED

level

string

Required

Level of the RFI (Request for Information)

Allowed valuesLEVEL_1LEVEL_2LEVEL_3

expireDate

string

Required

Date and time when the resource expires

certificate

object

Show 4 properties

string

System-generated unique identifier of the resource.

certPem

string

Base64 encoded certificate in PEM format

domain

string

BFI domain which is available in the CommonName attribute of the cert

jwk

object

The public key for the BFI defined in RFC 7517

Show 5 properties

crv

string

The curve used for the EC key

kid

string

Key ID

kty

string

Key type

string

X coordinate for the EC public key

string

Y coordinate for the EC public key

fieldRequirements

object

Show 2 properties

version

integer

Version of the RFI requirement schema provided by CPN.

schema

object

JSON schema for the RFI requirements. Note that references use 'ref' instead of '$ref' to avoid YAML parsing issues.

fileRequirements

array of strings

Allowed valuesFORMATION_DOCUMENTORG_STRUCTUREINVOICEBENEFICIARY_OWNERS_DOCUMENTID_DOCUMENTPROOF_OF_ADDRESS_DOCUMENTADDITIONAL_DOCUMENTS

401NotAuthorizedResponse

Response Body

object

code

integer

Required

Code that corresponds to the error.

message

string

Required

Human-readable message that describes the error.

errors

array of objects

Array of detailed error descriptions

Show 3 properties

error

string

Required

Type of descriptive error

Allowed valuesMISSING_OR_INVALID_FIELD

location

string

The key or path where the error occurred

message

string

Required

Detailed description of the error

403ForbiddenResponse

Response Body

object

code

integer

Required

Code that corresponds to the error.

message

string

Required

Human-readable message that describes the error.

errors

array of objects

Array of detailed error descriptions

Show 3 properties

error

string

Required

Type of descriptive error

Allowed valuesMISSING_OR_INVALID_FIELD

location

string

The key or path where the error occurred

message

string

Required

Detailed description of the error

404NotFoundResponse

Response Body

object

code

integer

Required

Code that corresponds to the error.

message

string

Required

Human-readable message that describes the error.

errors

array of objects

Array of detailed error descriptions

Show 3 properties

error

string

Required

Type of descriptive error

Allowed valuesMISSING_OR_INVALID_FIELD

location

string

The key or path where the error occurred

message

string

Required

Detailed description of the error

RequestChoose a language

ResponseChoose an example

1{
2  "data": {
3    "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
4    "paymentId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
5    "status": "APPROVED",
6    "level": "LEVEL_1",
7    "expireDate": "2023-01-01T12:04:05Z",
8    "certificate": {
9      "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
10      "certPem": "LS0tLS1CRUdJT...",
11      "domain": "api.circle.com",
12      "jwk": {
13        "crv": "P-256",
14        "kid": "263521881931753643998528753619816524468853605762",
15        "kty": "EC",
16        "x": "KnxBe8fb2mL_Ve9-tqjGSkGgE9f0yohMkAvH_InaFtE",
17        "y": "D41cVUpiKcey4LJKNFtUtmVHDWRmhjZapPLfryX5b1o"
18      }
19    },
20    "fieldRequirements": {
21      "version": 1,
22      "schema": {
23        "type": "object",
24        "$defs": {
25          "address": {
26            "type": "object",
27            "required": [
28              "street",
29              "city",
30              "country"
31            ],
32            "properties": {
33              "city": {
34                "type": "string",
35                "description": "City name"
36              },
37              "street": {
38                "type": "string",
39                "description": "Street address"
40              },
41              "country": {
42                "type": "string",
43                "pattern": "^[A-Z]{2}$",
44                "description": "Country code (e.g., US, GB)"
45              },
46              "postalCode": {
47                "type": "string",
48                "description": "Postal or ZIP code"
49              },
50              "stateProvince": {
51                "type": "string",
52                "description": "State or province"
53              }
54            },
55            "description": "Full address"
56          },
57          "individual": {
58            "type": "object",
59            "required": [
60              "name",
61              "address",
62              "dateOfBirth"
63            ],
64            "properties": {
65              "name": {
66                "type": "string",
67                "description": "Individual's full name"
68              },
69              "address": {
70                "ref": "#/$defs/address"
71              },
72              "dateOfBirth": {
73                "type": "string",
74                "format": "date",
75                "description": "Individual's date of birth (YYYY-MM-DD)"
76              }
77            },
78            "description": "Individual's RFI data"
79          },
80          "beneficiaryOwner": {
81            "type": "object",
82            "required": [
83              "name",
84              "address",
85              "dateOfBirth",
86              "percentage"
87            ],
88            "properties": {
89              "name": {
90                "type": "string",
91                "description": "Individual's full name"
92              },
93              "address": {
94                "ref": "#/$defs/address"
95              },
96              "percentage": {
97                "type": "number",
98                "description": "Company ownership percentage"
99              },
100              "dateOfBirth": {
101                "type": "string",
102                "format": "date",
103                "description": "Individual's date of birth (YYYY-MM-DD)"
104              }
105            },
106            "description": "Beneficiary owner's RFI data"
107          },
108          "intermediaryBeneficiaryOwner": {
109            "type": "object",
110            "required": [
111              "name",
112              "address",
113              "dateOfFormation",
114              "countryOfFormation",
115              "percentage"
116            ],
117            "properties": {
118              "name": {
119                "type": "string",
120                "description": "Business legal name"
121              },
122              "address": {
123                "ref": "#/$defs/address"
124              },
125              "percentage": {
126                "type": "number",
127                "description": "Company ownership percentage"
128              },
129              "dateOfFormation": {
130                "type": "string",
131                "format": "date",
132                "description": "Company formation date (YYYY-MM-DD)"
133              },
134              "countryOfFormation": {
135                "type": "string",
136                "pattern": "^[A-Z]{2}$",
137                "description": "Entity formation country"
138              }
139            },
140            "description": "Intermediary beneficiary owner's RFI data"
141          }
142        },
143        "title": "RFI Requirements",
144        "$schema": "https://json-schema.org/draft/2020-12/schema",
145        "required": [
146          "SOURCE_OF_FUNDS",
147          "METHOD_OF_VERIFICATION",
148          "NAME",
149          "TRADE_NAME",
150          "NATIONAL_IDENTIFICATION_NUMBER",
151          "DATE_OF_FORMATION",
152          "COUNTRY_OF_FORMATION",
153          "ENTITY_TYPE",
154          "INDUSTRY_TYPE",
155          "ADDRESS",
156          "AUTHORIZED_SIGNATORIES",
157          "BENEFICIARY_OWNERSHIP"
158        ],
159        "properties": {
160          "NAME": {
161            "type": "string",
162            "description": "Business legal registered name"
163          },
164          "EMAIL": {
165            "type": "string",
166            "description": "Business contact email address"
167          },
168          "PHONE": {
169            "type": "string",
170            "description": "Business contact phone number"
171          },
172          "ADDRESS": {
173            "ref": "#/$defs/address"
174          },
175          "WEBSITE": {
176            "type": "string",
177            "description": "Business website URL"
178          },
179          "TRADE_NAME": {
180            "type": "string",
181            "description": "Business trade name or DBA (Doing Business As)"
182          },
183          "ENTITY_TYPE": {
184            "type": "string",
185            "description": "Business structure type (Corporation, LLC, Partnership, etc.)"
186          },
187          "INDUSTRY_TYPE": {
188            "type": "string",
189            "description": "Business activity classification"
190          },
191          "SOURCE_OF_FUNDS": {
192            "type": "string",
193            "description": "Transaction source of funds"
194          },
195          "DATE_OF_FORMATION": {
196            "type": "string",
197            "format": "date",
198            "description": "Company formation date (YYYY-MM-DD)"
199          },
200          "BENEFICIARY_OWNERS": {
201            "ref": "#/$defs/beneficiaryOwner"
202          },
203          "COUNTRY_OF_FORMATION": {
204            "type": "string",
205            "pattern": "^[A-Z]{2}$",
206            "description": "Entity formation country"
207          },
208          "BENEFICIARY_OWNERSHIP": {
209            "type": "boolean",
210            "description": "Whether any individuals or intermediaries own 25% or more of the company"
211          },
212          "AUTHORIZED_SIGNATORIES": {
213            "ref": "#/$defs/individual"
214          },
215          "METHOD_OF_VERIFICATION": {
216            "type": "string",
217            "description": "Verification method used"
218          },
219          "NATIONAL_IDENTIFICATION_NUMBER": {
220            "type": "string",
221            "description": "Business identification number (e.g., Tax ID)"
222          },
223          "INTERMEDIARY_BENEFICIARY_OWNERS": {
224            "ref": "#/$defs/intermediaryBeneficiaryOwner"
225          }
226        },
227        "description": "RFI Data Requirements"
228      }
229    },
230    "fileRequirements": [
231      "FORMATION_DOCUMENT"
232    ]
233  }
234}

Did this page help you?

Developer Terms Service Terms Privacy Policy Acceptable Use Your Privacy Choices

Cookie Policy