Skip to content

Commit bee086f

Browse files
author
Adyen Automation
committed
spec release
1 parent 3a16b41 commit bee086f

2 files changed

Lines changed: 627 additions & 0 deletions

File tree

‎json/DocumentCollectorService-v1.json‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
{
2+
"openapi" : "3.1.0",
3+
"servers" : [ {
4+
"url" : "https://document-collector-test.adyen.com/v1",
5+
"description" : "Test Environment"
6+
}, {
7+
"url" : "https://document-collector-live.adyen.com/v1",
8+
"description" : "Live Environment"
9+
} ],
10+
"info" : {
11+
"title" : "Cross-border Invoices API",
12+
"description" : "The Cross-border Invoices API enables merchants processing payments in INR to upload auditing documentation (invoices) in PDF format for each cross-border transaction. This is a regulatory requirement under the Reserve Bank of India (RBI) guidelines for cross-border payments.\n\n## Authentication\nYour Adyen contact will provide your API credential and an API key. To connect to the API, add an `X-API-Key` header with the API key as the value, for example:\n\n```\ncurl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using basic authentication. For example:\n\n```\ncurl\n-H \"Content-Type: application/json\" \\\n-U \"ws@Company.YOUR_COMPANY\":\"YOUR_WS_PASSWORD\" \\\n...\n```\n\n## Versioning\nThe Cross-border Invoices API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://document-collector-test.adyen.com/v1/crossBorderInvoices\n```\n\n## Going live\nWhen going live, your Adyen contact will provide your API credential for the live environment. You can then use the username and password to send requests to `https://document-collector-live.adyen.com/v1`.\n\n",
13+
"termsOfService" : "https://www.adyen.com/legal/terms-and-conditions",
14+
"contact" : {
15+
"name" : "Adyen Developer Experience team",
16+
"url" : "https://github.com/Adyen/adyen-openapi"
17+
},
18+
"version" : "1"
19+
},
20+
"tags" : [ {
21+
"name" : "Documents"
22+
} ],
23+
"paths" : {
24+
"/crossBorderInvoices" : {
25+
"post" : {
26+
"tags" : [ "Documents" ],
27+
"summary" : "Upload a document",
28+
"description" : "Uploads a document for a merchant account.",
29+
"operationId" : "post-crossBorderInvoices",
30+
"requestBody" : {
31+
"content" : {
32+
"multipart/form-data" : {
33+
"schema" : {
34+
"required" : [ "context", "file", "merchantAccount" ],
35+
"type" : "object",
36+
"properties" : {
37+
"context" : {
38+
"$ref" : "#/components/schemas/DocumentContext"
39+
},
40+
"file" : {
41+
"type" : "string",
42+
"description" : "The PDF file to upload. Filename must be {pspReference}.pdf",
43+
"format" : "binary"
44+
},
45+
"merchantAccount" : {
46+
"maxLength" : 255,
47+
"minLength" : 1,
48+
"pattern" : "^[a-zA-Z0-9_]*$",
49+
"type" : "string",
50+
"description" : "The merchant account that the document belongs to",
51+
"example" : "YourMerchantAccount"
52+
}
53+
}
54+
}
55+
}
56+
}
57+
},
58+
"responses" : {
59+
"201" : {
60+
"description" : "Document uploaded successfully.",
61+
"content" : {
62+
"application/json" : {
63+
"schema" : {
64+
"$ref" : "#/components/schemas/DocumentUploadResponse"
65+
},
66+
"examples" : {
67+
"upload-document-201" : {
68+
"summary" : "Document uploaded successfully",
69+
"description" : "upload-document-201",
70+
"value" : {
71+
"pspReference" : "QRMJC25GDZRKDM92",
72+
"merchantAccount" : "YourMerchantAccount",
73+
"context" : "paCbInvoice",
74+
"fileName" : "QRMJC25GDZRKDM92.pdf"
75+
}
76+
}
77+
}
78+
}
79+
}
80+
},
81+
"400" : {
82+
"description" : "Bad request.",
83+
"content" : {
84+
"application/json" : {
85+
"schema" : {
86+
"$ref" : "#/components/schemas/DefaultErrorResponseEntity"
87+
},
88+
"examples" : {
89+
"upload-document-400" : {
90+
"summary" : "Bad request — malformed multipart request",
91+
"description" : "upload-document-400",
92+
"value" : {
93+
"type" : "https://docs.adyen.com/errors/invalid-request",
94+
"title" : "Bad Request",
95+
"status" : 400,
96+
"errorCode" : "00_400"
97+
}
98+
}
99+
}
100+
}
101+
}
102+
},
103+
"401" : {
104+
"description" : "Unauthorized.",
105+
"content" : {
106+
"application/json" : {
107+
"schema" : {
108+
"$ref" : "#/components/schemas/DefaultErrorResponseEntity"
109+
},
110+
"examples" : {
111+
"upload-document-401" : {
112+
"summary" : "Unauthorized — missing or invalid credentials",
113+
"description" : "upload-document-401",
114+
"value" : {
115+
"type" : "https://docs.adyen.com/errors/unauthorized",
116+
"title" : "Unauthorized",
117+
"status" : 401,
118+
"errorCode" : "00_401"
119+
}
120+
}
121+
}
122+
}
123+
}
124+
},
125+
"403" : {
126+
"description" : "Forbidden.",
127+
"content" : {
128+
"application/json" : {
129+
"schema" : {
130+
"$ref" : "#/components/schemas/DefaultErrorResponseEntity"
131+
},
132+
"examples" : {
133+
"upload-document-403" : {
134+
"summary" : "Forbidden — insufficient permissions",
135+
"description" : "upload-document-403",
136+
"value" : {
137+
"type" : "https://docs.adyen.com/errors/forbidden",
138+
"title" : "Forbidden",
139+
"detail" : "Caller does not have access to the requested account",
140+
"status" : 403,
141+
"errorCode" : "00_403"
142+
}
143+
}
144+
}
145+
}
146+
}
147+
},
148+
"422" : {
149+
"description" : "Unprocessable Entity. The request contains invalid fields.",
150+
"content" : {
151+
"application/json" : {
152+
"schema" : {
153+
"$ref" : "#/components/schemas/DefaultErrorResponseEntity"
154+
},
155+
"examples" : {
156+
"upload-document-422" : {
157+
"summary" : "Unprocessable entity — validation failed",
158+
"description" : "upload-document-422",
159+
"value" : {
160+
"type" : "https://docs.adyen.com/errors/validation",
161+
"title" : "The request is missing required fields or contains invalid data.",
162+
"status" : 422,
163+
"errorCode" : "29_001",
164+
"invalidFields" : [ {
165+
"name" : "file",
166+
"value" : "",
167+
"message" : "File must be a PDF named {pspReference}.pdf"
168+
} ]
169+
}
170+
}
171+
}
172+
}
173+
}
174+
},
175+
"500" : {
176+
"description" : "Internal server error.",
177+
"content" : {
178+
"application/json" : {
179+
"schema" : {
180+
"$ref" : "#/components/schemas/DefaultErrorResponseEntity"
181+
},
182+
"examples" : {
183+
"upload-document-500" : {
184+
"summary" : "Internal server error",
185+
"description" : "upload-document-500",
186+
"value" : {
187+
"type" : "https://docs.adyen.com/errors/internal-server-error",
188+
"title" : "Internal Server Error",
189+
"status" : 500,
190+
"errorCode" : "00_500"
191+
}
192+
}
193+
}
194+
}
195+
}
196+
}
197+
},
198+
"security" : [ {
199+
"ApiKeyAuth" : [ ]
200+
}, {
201+
"BasicAuth" : [ ]
202+
} ],
203+
"x-methodName" : "uploadCrossBorderInvoice",
204+
"x-sortIndex" : 0
205+
}
206+
}
207+
},
208+
"components" : {
209+
"schemas" : {
210+
"DefaultErrorResponseEntity" : {
211+
"type" : "object",
212+
"properties" : {
213+
"detail" : {
214+
"type" : "string",
215+
"description" : "A human-readable explanation specific to this occurrence of the problem."
216+
},
217+
"errorCode" : {
218+
"type" : "string",
219+
"description" : "Unique business error code."
220+
},
221+
"instance" : {
222+
"type" : "string",
223+
"description" : "A URI that identifies the specific occurrence of the problem if applicable."
224+
},
225+
"invalidFields" : {
226+
"type" : "array",
227+
"description" : "Array of fields with validation errors when applicable.",
228+
"items" : {
229+
"$ref" : "#/components/schemas/InvalidField"
230+
}
231+
},
232+
"requestId" : {
233+
"type" : "string",
234+
"description" : "The unique reference for the request."
235+
},
236+
"status" : {
237+
"type" : "integer",
238+
"description" : "The HTTP status code.",
239+
"format" : "int32"
240+
},
241+
"title" : {
242+
"type" : "string",
243+
"description" : "A short, human-readable summary of the problem type."
244+
},
245+
"type" : {
246+
"type" : "string",
247+
"description" : "A URI that identifies the validation error type. It points to human-readable documentation for the problem type."
248+
}
249+
},
250+
"description" : "Standardized error response following RFC-7807 format",
251+
"externalDocs" : {
252+
"url" : "https://www.rfc-editor.org/rfc/rfc7807"
253+
}
254+
},
255+
"DocumentContext" : {
256+
"type" : "string",
257+
"description" : "The document context indicating the type of document being uploaded",
258+
"enum" : [ "paCbInvoice" ]
259+
},
260+
"DocumentUploadResponse" : {
261+
"type" : "object",
262+
"properties" : {
263+
"context" : {
264+
"type" : "string",
265+
"description" : "The document context indicating the type of document.",
266+
"example" : "paCbInvoice"
267+
},
268+
"fileName" : {
269+
"type" : "string",
270+
"description" : "The name of the uploaded file.",
271+
"example" : "QRMJC25GDZRKDM92.pdf"
272+
},
273+
"merchantAccount" : {
274+
"type" : "string",
275+
"description" : "The merchant account that the document belongs to.",
276+
"example" : "YourMerchantAccount"
277+
},
278+
"pspReference" : {
279+
"type" : "string",
280+
"description" : "The PSP reference extracted from the filename.",
281+
"example" : "QRMJC25GDZRKDM92"
282+
}
283+
},
284+
"description" : "The uploaded document resource"
285+
},
286+
"InvalidField" : {
287+
"required" : [ "message", "name", "value" ],
288+
"type" : "object",
289+
"properties" : {
290+
"message" : {
291+
"type" : "string",
292+
"description" : "Description of the validation error."
293+
},
294+
"name" : {
295+
"type" : "string",
296+
"description" : "The field that has an invalid value."
297+
},
298+
"value" : {
299+
"type" : "string",
300+
"description" : "The invalid value."
301+
}
302+
}
303+
}
304+
},
305+
"securitySchemes" : {
306+
"ApiKeyAuth" : {
307+
"type" : "apiKey",
308+
"name" : "X-API-Key",
309+
"in" : "header"
310+
},
311+
"BasicAuth" : {
312+
"type" : "http",
313+
"scheme" : "basic"
314+
}
315+
}
316+
},
317+
"jsonSchemaDialect" : "https://spec.openapis.org/oas/3.1/dialect/base",
318+
"security" : [ {
319+
"ApiKeyAuth" : [ ]
320+
}, {
321+
"BasicAuth" : [ ]
322+
} ]
323+
}

0 commit comments

Comments
 (0)