Files - KetaPay Docs

Upload a file once with POST /files, then refer to it by id. JPEG, PNG, HEIC, WebP, PDF and MP4, up to 25 MB each.

Purposes

A file’s purpose decides who may upload it and where it can be used.

Purpose	Proof needed	Used in
`agreement`	Your key	Checkout session `attachments`
`delivery`	Your key and the seller’s customer token	Milestone delivery `attachments`
`dispute_evidence`	Your key and the buyer’s or seller’s customer token	Dispute evidence `files`

A file can only be used by the customer who uploaded it, and only for its purpose. Unused files are deleted after 24 hours.

Upload

import { readFile } from 'node:fs/promises'

const file = await ketapay.files.create({
  file: await readFile('./proof-of-delivery.pdf'),
  filename: 'proof-of-delivery.pdf',
  purpose: 'delivery',
}, { customerToken: sellerToken })

curl https://api.ketapay.com/v1/files \
  -H "Authorization: Bearer $KETAPAY_SECRET_KEY" \
  -H "KetaPay-Customer-Token: $SELLER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F purpose=delivery \
  -F file=@proof-of-delivery.pdf

Use it

await ketapay.escrows.milestones.deliver(
  escrowId,
  milestoneId,
  {
    note: 'Delivered to the front desk, signed by A. Obi',
    attachments: [{ file: file.id }],
  },
  { customerToken: sellerToken },
)

Checkout sessions also take files by URL (attachments: [{ url, name }], images: [{ url }]): KetaPay fetches and keeps a copy when the session is created, so the record of the deal can’t change later.