Embedded Payments

Generate and download documents

This guide walks you through the complete process of generating and retrieving documents for your clients. The API enables you to programmatically generate documents such as account confirmation letters. The process is asynchronous, you initiate generation, receive a unique document identifier, and retrieve the completed document once notified. Documents are generated on demand and delivered as PDF files through the API.

Initiate document generation

To generate a document, use the POST /v1/ documents endpoint. The system validates eligibility and returns a unique documentId.

When you start generation, specify the following in the request body:

The document type (for example, ACCOUNT_CONFIRMATION_LETTER)
The accountId (required for account related documents)

Sample request:

Json

{
  "type": "ACCOUNT_CONFIRMATION_LETTER",
  "parameters": {
    "accountId": "f5246c6eb2c742a19c9c79327a769708"
  }
}

Sample response:

Json

{
  "id": "ebeebce5-765d-4d9e-a89f-a7f923bbfa3b",
  "type": "ACCOUNT_CONFIRMATION_LETTER",
  "parameters": {
    "accountId": "f5246c6eb2c742a19c9c79327a769708"
  }
}

Response codes:

Response code for document generation
HTTP Status	Description
202	Successful response. Document generation has been accepted
400	Invalid payload (bad request)
500	Failure in generating the requested document

Download the generated document

After you receive the DOCUMENT_GENERATED webhook notification, use the GET /v1/documents/{documentId} endpoint to retrieve the document. The document is returned as a PDF file (application/pdf). You can download or display it to your end users.

Sample request:

Json

curl --request GET \
  --url 'https://api.payments.jpmorgan.com/api/v1/documents/ebeebce5-765d-4d9e-a89f-a7f923bbfa3b' \

Sample response:

Json

200 OK

Response codes:

Response code for generated document
HTTP Status	Description
200	Successful response
404	Document not found

Document types and eligibility

Each document type has specific eligibility criteria that must be met before generation can proceed.

Document types and eligibility
Document name	Type	Eligibility	Content
Account confirmation letter	`ACCOUNT_CONFIRMATION_LETTER`	Account type: Commerce, Payment and Processing accounts only. Account state: Must be either OPEN or PENDING_CLOSE	Dynamic fields (client name, account number, date) and static template which is ADA (Americans with Disability Act) compliant.

Events

The API publishes events to track the lifecycle of each document generation request. Webhook notifications are triggered for terminal states. Your application can respond to successful generation or failure in near real time.

DOCUMENT_GENERATED

Published when document generation completes successfully. This event triggers a webhook notification.

Sample response:

Json

{
  "documentId": "ebeebce5-765d-4d9e-a89f-a7f923bbfa3b",
  "documentType": "ACCOUNT_CONFIRMATION_LETTER",
  "parameters": {
    "accountId": "f5246c6eb2c742a19c9c79327a769708"
  }
}

DOCUMENT_FAILED

Published when document generation fails due to validation errors. This event triggers a webhook notification.

Sample response:

Json

{
  "documentId": "ebeebce5-765d-4d9e-a89f-a7f923bbfa3b",
  "documentType": "ACCOUNT_CONFIRMATION_LETTER",
  "parameters": {
    "accountId": "f5246c6eb2c742a19c9c79327a769708"
  },
  "error": {
    "title": "Document generation failed",
    "context": [
      {
        "code": "10199",
        "message": "Account category SAVINGS is not eligible for confirmation letter"
      }
    ]
  }
}

Error responses

Error responses follow a consistent structure. Each response includes: HTTP status, code, title, field, message and description.

Json

{
  "title": "Error Title",
  "httpStatus": 400,
  "context": [
    {
      "code": "10001",
      "location": "BODY",
      "field": "$.fieldName",
      "message": "Error message"
    }
  ]
}

Use the following codes to troubleshoot document generation and retrieval issues:

Errors codes reference
HTTP Status	Code	Title	Field	Message	Description
400	10001	Invalid data	$.type	The field must be present.	The type field is missing.
400	10001	Invalid data	$.parameters	The field must be present.	The parameters object is missing.
400	10001	Invalid data	$.parameters.accountId	The field must be present.	The accountId field is missing or blank.
400	10104	Invalid data	$.type	The field must have the expected value.	The document type is unsupported.
400	—	Invalid data	—	Request body should be valid JSON.	The request body contains invalid JSON.
404	—	Not found	—	—	The document was not found or generation failed.
404	—	Not found	—	Resource for ID {id} is currently being created.	The document is still pending.
500		Internal server error	—	—	An unexpected server error occurred.