{ "openapi" : "3.1.0", "info" : { "title" : "Document Collector API", "description" : "The Document Collector API enables merchants to upload supporting documentation required for payment processing. Currently, it supports uploading cross-border invoices in PDF format for transactions processed in INR, as required 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: multipart/form-data\" \\\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: multipart/form-data\" \\\n-U \"ws@Company.YOUR_COMPANY\":\"YOUR_WS_PASSWORD\" \\\n...\n```\n\n## Versioning\nThe Document Collector 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", "termsOfService" : "https://www.adyen.com/legal/terms-and-conditions", "contact" : { "name" : "Adyen Developer Experience team", "url" : "https://github.com/Adyen/adyen-openapi" }, "version" : "1" }, "servers" : [ { "url" : "https://document-collector-test.adyen.com/v1", "description" : "Test Environment" }, { "url" : "https://document-collector-live.adyen.com/v1", "description" : "Live Environment" } ], "security" : [ { "ApiKeyAuth" : [ ] }, { "BasicAuth" : [ ] } ], "tags" : [ { "name" : "Documents" } ], "paths" : { "/crossBorderInvoices" : { "post" : { "tags" : [ "Documents" ], "summary" : "Upload a document", "description" : "Uploads a document for a merchant account.", "operationId" : "post-crossBorderInvoices", "requestBody" : { "content" : { "multipart/form-data" : { "schema" : { "$ref" : "#/components/schemas/DocumentUploadRequest" }, "examples" : { "upload-document" : { "summary" : "Upload a cross-border invoice document", "description" : "upload-document", "value" : { "file" : "(binary PDF named {pspReference}.pdf)", "context" : "paCbInvoice", "merchantAccount" : "YourMerchantAccount" } } } } } }, "responses" : { "201" : { "description" : "Document uploaded successfully.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DocumentUploadResponse" }, "examples" : { "upload-document-201" : { "summary" : "Document uploaded successfully", "description" : "upload-document-201", "value" : { "pspReference" : "QRMJC25GDZRKDM92", "merchantAccount" : "YourMerchantAccount", "context" : "paCbInvoice", "fileName" : "QRMJC25GDZRKDM92.pdf" } } } } } }, "400" : { "description" : "Bad request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "upload-document-400" : { "summary" : "Bad request — malformed multipart request", "description" : "upload-document-400", "value" : { "type" : "https://docs.adyen.com/errors/invalid-request", "title" : "Bad Request", "status" : 400, "errorCode" : "00_400" } } } } } }, "401" : { "description" : "Unauthorized.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "upload-document-401" : { "summary" : "Unauthorized — missing or invalid credentials", "description" : "upload-document-401", "value" : { "type" : "https://docs.adyen.com/errors/unauthorized", "title" : "Unauthorized", "status" : 401, "errorCode" : "00_401" } } } } } }, "403" : { "description" : "Forbidden.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "upload-document-403" : { "summary" : "Forbidden — insufficient permissions", "description" : "upload-document-403", "value" : { "type" : "https://docs.adyen.com/errors/forbidden", "title" : "Forbidden", "detail" : "Caller does not have access to the requested account", "status" : 403, "errorCode" : "00_403" } } } } } }, "422" : { "description" : "Unprocessable Entity. The request contains invalid fields.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "upload-document-422" : { "summary" : "Unprocessable entity — validation failed", "description" : "upload-document-422", "value" : { "type" : "https://docs.adyen.com/errors/validation", "title" : "The request is missing required fields or contains invalid data.", "status" : 422, "errorCode" : "29_001", "invalidFields" : [ { "name" : "file", "value" : "", "message" : "File must be a PDF named {pspReference}.pdf" } ] } } } } } }, "500" : { "description" : "Internal server error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "upload-document-500" : { "summary" : "Internal server error", "description" : "upload-document-500", "value" : { "type" : "https://docs.adyen.com/errors/internal-server-error", "title" : "Internal Server Error", "status" : 500, "errorCode" : "00_500" } } } } } } }, "security" : [ { "ApiKeyAuth" : [ ] }, { "BasicAuth" : [ ] } ], "x-methodName" : "uploadCrossBorderInvoice", "x-sortIndex" : 0 } } }, "components" : { "schemas" : { "DefaultErrorResponseEntity" : { "type" : "object", "description" : "Standardized error response following RFC-7807 format", "externalDocs" : { "url" : "https://www.rfc-editor.org/rfc/rfc7807" }, "properties" : { "detail" : { "type" : "string", "description" : "A human-readable explanation specific to this occurrence of the problem." }, "errorCode" : { "type" : "string", "description" : "Unique business error code." }, "instance" : { "type" : "string", "description" : "A URI that identifies the specific occurrence of the problem if applicable." }, "invalidFields" : { "type" : "array", "description" : "Array of fields with validation errors when applicable.", "items" : { "$ref" : "#/components/schemas/InvalidField" } }, "requestId" : { "type" : "string", "description" : "The unique reference for the request." }, "status" : { "type" : "integer", "format" : "int32", "description" : "The HTTP status code." }, "title" : { "type" : "string", "description" : "A short, human-readable summary of the problem type." }, "type" : { "type" : "string", "description" : "A URI that identifies the validation error type. It points to human-readable documentation for the problem type." } } }, "DocumentContext" : { "type" : "string", "description" : "The document context indicating the type of document being uploaded.\n Possible values: **paCbInvoice**.", "enum" : [ "paCbInvoice" ] }, "DocumentUploadRequest" : { "type" : "object", "properties" : { "context" : { "$ref" : "#/components/schemas/DocumentContext", "description" : "The document context indicating the type of document being uploaded.\n Possible values: **paCbInvoice**." }, "file" : { "type" : "string", "format" : "binary", "description" : "The PDF file to upload. Filename must be {pspReference}.pdf" }, "merchantAccount" : { "type" : "string", "description" : "The merchant account that the document belongs to.", "example" : "YourMerchantAccount", "maxLength" : 255, "minLength" : 1, "pattern" : "^[a-zA-Z0-9_]*$" } }, "required" : [ "context", "file", "merchantAccount" ] }, "DocumentUploadResponse" : { "type" : "object", "description" : "The uploaded document resource", "properties" : { "context" : { "type" : "string", "description" : "The document context indicating the type of document.", "example" : "paCbInvoice" }, "fileName" : { "type" : "string", "description" : "The name of the uploaded file.", "example" : "QRMJC25GDZRKDM92.pdf" }, "merchantAccount" : { "type" : "string", "description" : "The merchant account that the document belongs to.", "example" : "YourMerchantAccount" }, "pspReference" : { "type" : "string", "description" : "The PSP reference extracted from the filename.", "example" : "QRMJC25GDZRKDM92" } } }, "InvalidField" : { "type" : "object", "properties" : { "message" : { "type" : "string", "description" : "Description of the validation error." }, "name" : { "type" : "string", "description" : "The field that has an invalid value." }, "value" : { "type" : "string", "description" : "The invalid value." } }, "required" : [ "message", "name", "value" ] } }, "securitySchemes" : { "ApiKeyAuth" : { "type" : "apiKey", "name" : "X-API-Key", "in" : "header" }, "BasicAuth" : { "type" : "http", "scheme" : "basic" } } }, "jsonSchemaDialect" : "https://spec.openapis.org/oas/3.1/dialect/base" }