Checkout.com files.upload fails with purpose_required: broken form-data handling, fixed in 3.3.0

TL;DR

Upgrade checkout-sdk-node to 3.3.0 or later, where the file upload serialization is fixed. When a file upload fails with purpose_required even though you set the purpose, suspect the SDK's form handling before your own code.

Steps

1. Upgrade checkout-sdk-node to 3.3.0 or later, where the file upload serialization is fixed. If you are stuck on an older version, skip the SDK for uploads and call the files endpoint directly with your HTTP client, passing purpose as a URL query parameter and the file as multipart body. When a file upload fails with purpose_required even though you set the purpose, suspect the SDK's form handling before your own code.

Expected: A Checkout maintainer confirmed the bug and found the deeper cause: the SDK handed a form-data v4 instance to native fetch, which cannot serialize it, so the field never arrived.

When to use

You are seeing this: If you are stuck on an older version, skip the SDK for uploads and call the files endpoint directly with your HTTP client, passing purpose as a URL query parameter and the file as multipart body. Use this skill when you run into "Checkout.com files.upload fails with purpose_required: broken form-data handling, fixed in 3.3.0".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: 3.3.0. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Issue checkout/checkout-sdk-node#418 (closed, 4 comments): files.upload with a file stream and a purpose like disputeevidence always failed with purposerequired and purpose_invalid. The reporter showed the raw API works when purpose goes in the URL query string, while the SDK stuffed it into multipart form data. A Checkout maintainer confirmed the bug and found the deeper cause: the SDK handed a form-data v4 instance to native fetch, which cannot serialize it, so the field never arrived.

Verified resolution: Upgrade checkout-sdk-node to 3.3.0 or later, where the file upload serialization is fixed. If you are stuck on an older version, skip the SDK for uploads and call the files endpoint directly with your HTTP client, passing purpose as a URL query parameter and the file as multipart body. When a file upload fails with purpose_required even though you set the purpose, suspect the SDK's form handling before your own code.

Source URL: https://github.com/checkout/checkout-sdk-node/issues/418