Upload Attachment
Last updated
Last updated
The Upload Attachment API allows merchants to upload a file, generating a file_url that can be linked to transactions. Files can be uploaded independently or directly associated with a transaction by including or in the request.
Upload Before session_id Generation: Upload a file before creating a transaction, results generating file_url
Upload After session_id Generation: Add files to an existing transaction by providing session_id or order_no.
Update File After Payment: Replace an attached file after payment by uploading a new file to be associated with the existing transaction (i.e., attach the invoice).
Single file upload per request.
Direct transaction linking by including session_id or order_no.
Reusable file URLs for new transactions using in the .
Supports URL shortening for easier access with shortify_attachment_url (when session_id or order_no is provided).
Maximum file size: Upload limit is 2.5 MB.
Support for various file formats such as PDF, JPEG, PNG, DOC, DOCX, JPG, XLS, XLSX, and TXT.
Before using the Upload Attachment API, ensure the following conditions and setup steps are met for successful integration.
File Format and Compatibility When uploading a file, ensure it complies with the accepted file formats: PDF, JPEG, PNG, DOC, DOCX, JPG, XLS, XLSX, and TXT. The API will only process files with these extensions.
Request Body Format
All request parameters, must be sent using multipart/form-data. JSON format is not supported.
Options for Using the Upload Attachment API:
For cases where a file needs to be uploaded to the server before creating any transaction.
Upload the file independently to generate a file_url.
For cases where a file is uploaded to the server after the transaction has been created:
Include: session_id or order_no in the Upload Attachment API request payload to link the file directly to an existing transaction.
URL Shortening (Optional): When providing session_id or order_no, you may set shortify_attachment_url to true to receive a shortened file URL.
Supported Methods
The Upload Attachment API supports two options for uploading the file.
1. Request Payload
The merchant sends a request to the Upload Attachment API, using the following key parameters in a multipart/form-data format:
file (Required): The actual file to be uploaded, in one of the supported formats PDF, JPEG, PNG, DOC, DOCX, JPG, XLS, XLSX, and TXT.
2. Response Payload
Once the upload is complete, the API response includes:
file_url(Mandatory): The relative URL of the uploaded file in storage, which can be used to link the file to other transactions.
original_filename(Mandatory): The original name of the uploaded file.
1. Request Payload
The merchant sends a request to the Upload Attachment API, using the following key parameters in a multipart/form-data format:
file (Required): The actual file to be uploaded, in one of the supported formats PDF, JPEG, PNG, DOC, DOCX, JPG, XLS, XLSX, and TXT.
session_id or order_no(Required): To identify the transaction for which the file is being uploaded.
shortify_attachment_url (Optional): If set to true, the response will include a shortened URL for the uploaded attachment.
2. Response Payload
Once the upload is complete, the API response includes:
file_url(Mandatory): The relative URL of the uploaded file in storage, which can be used to link the file to other transactions.
original_filename(Mandatory): The original name of the uploaded file.
attachment_short_url(Conditional): A shortened URL for the uploaded file, available only when:
session_id or order_no is provided.
shortify_attachment_url is set to true.
This guide provides step-by-step instructions on how to use the Upload Attachment API. Follow these steps to successfully integrate and utilize the API.
Here only the file parameter is required in the Upload Attachment API request payload, as shown below:
1. Upload Attachment Request Payload
2. Upload Attachment Response Payload
3. Checkout Request Payload
4. Checkout Response Payload
The transaction identifiers must be included in the Upload Attachment API request payload.
Checkout Request Payload
Generated Transaction identifier:
Provided Transaction identifier:
Either the generated session_id or the merchant-provided order_no can be used to identify the transaction. In the following steps, we will use session_id as the reference.
2. Prepare the Upload Attachment Request Payload
Once you have the session_id from the payment transaction, prepare your request to upload the attachment.
Request Method: POST
API Endpoint: <<ottu-url>>/checkout/v1/upload-attachment/
Content-Type: multipart/form-data
3. Request Parameters
Ensure that your request includes the following parameters:
session_id: The session_id generated during the payment transaction.
file: The file path to be uploaded, ensuring it meets the supported file format requirements (PDF, JPEG, PNG, DOC, DOCX, JPG, XLS, XLSX, and TXT)
shortify_attachment_url (optional): Set to true if you prefer a shortened URL in the response.
4. Upload Attachment Request Payload
5. Upload Attachment Response Payload
If the request is successful, you will receive a response containing the uploaded file’s details, including the file_url and, if applicable, a shortened URL. Here's an example response:
To ensure a smooth and efficient integration with the Upload Attachment API, follow these best practices:
1. Validate File Types and Sizes
Check file formats: Ensure that the uploaded file adheres to the supported formats (pdf, jpeg, png, doc, docx, jpg, xls, xlsx, and txt). This prevents errors during the upload process.
2. Handle API Responses Efficiently
Check for errors: Always check the API response for success or failure indicators, and handle errors appropriately. Log any errors for further analysis.
Store important details: Save the file_url or attachment_short_url returned in the response for future reference or for displaying to users.
3. Optimize for Performance
Use short URLs wisely: Only set shortify_attachment_url to true if you intend to use the shortened URL. Avoid unnecessary operations if the original URL is sufficient.
4. Use session_id or order_no Correctly
The API supports the following file types: pdf, jpeg, png, doc, docx, jpg, xls, xlsx, and txt. Ensure that the file you are uploading is in one of these formats to avoid errors.
Yes, Ottu allows merchants to use a file_url generated from a Upload After session_id Generation, for different transactions.
No, the API does not support multiple files to be uploaded in a single request. It includes only one file per request.
If you try to upload a file with an unsupported format, the API will return an error indicating that the file type is invalid.
The shortify_attachment_url parameter, when set to true, will generate a shortened version of the URL for the uploaded attachment.
The API will return detailed error messages in the response body when an issue occurs, such as unsupported file types, invalid session_id, or file size limits being exceeded. Be sure to implement error handling in your code to display appropriate messages to users.
Use the generated file_url by adding it to the parameter in the when creating the transaction.
Create Transaction: Creating a new transaction using . This will result generated and (if provided).
For Further information, please refer to the section.
Upload a file before creating a transaction to generate a file_url. This file_url can then be included in the parameter of the when the transaction is created. This approach is ideal when the file should be accessible from the start of the transaction process.
file_urlis used to link the uploaded file to a new transaction by adding it to the parameter in the request.
Upload a file after the transaction is created. Include or in the upload request to link the file directly to the existing transaction. Optional URL shortening with shortify_attachment_url is available when session_id or order_no is provided. This scenario is helpful when file upload depends on transaction-specific data or upon successful transaction creation.
After the file is uploaded, the API returns a file_url. This URL can be used to link the uploaded file to a new transaction by including it in the parameter of the request payload.
1. Create a Payment Transaction Before uploading an attachment, a payment transaction must be created via the I. This transaction generates a , which is necessary for the next step.
Transaction identification: You can use either the generated or the merchant-provided to associate the attachment with the transaction. Be sure to use the correct identifier based on your transaction flow.
Merchants can use the I to create a new transaction and associate a file with it. This can be achieved by including the file through the parameter. However, because multipart/form-data does not support adding nested values to parameters (e.g., or ), it is often more practical to use the attachment_upload_url. This allows for a more flexible and reliable way to link files to transactions while preserving parameter structure.
The is generated when you create a payment transaction via the . You will use this session_id to associate the attachment with the transaction.
The file_url is the relative URL of an uploaded file generated by the Upload Attachment API. It can be used to attach the same file to other transactions by including it in the parameter of the request payload.
Upload a file, attach it to a transaction if session_id or order_no is provided and shorify if shortify_attachment_url is true.
Private API key to be provided in the format Api-Key <key>.
Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11loA writable field that accepts an attachment.
(?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$If set to true, the URL of the uploaded attachment will be shortened using a URL shortener service. if configured.This should be used when sharing the attachment URL via SMS or WhatsApp. This will only work with session_id or order_no.
falseThis is an optional identifier used to specify the payment transaction upon which the operation should be performed. You can use either the order_no or session_id field; at least one of these two identifiers must be provided to select the payment transaction that should be actioned.
Similar to order_no, session_id is an optional identifier used to specify the payment transaction for the operation. You must provide either order_no or session_id in order to select the appropriate payment transaction.