Upload KYC documents

The following API allows a merchant to upload customer's documents for KYC within a host-to-host SEPA Secure flow. In order for a customer to pass a KYC, at least 3 documents must be provided by a merchant:

• Photo: SELFIE

• Document ID (one of the following): PASSPORT, ID_CARD, DRIVERS, RESIDENCE_PERMIT

• Proof of address: UTILITY_BILL (can also be other documents than bill, see list)

Documents must follow the following rules:

• DRIVERS, ID_CARD - it is required to upload two sides

  • Use documentSubType parameter with FRONT_SIDE / BACK_SIDE values

• SELFIE, PASSPORT, UTILITY_BILL - it is required to upload one side

• RESIDENCE_PERMIT - can be one or two sides

The documents are not registered in SumSub after the upload is done. It is required to trigger the verification endpoint to start identity verification

Document quality

Submitted documents should meet the following criteria:

• Official and unexpired (passports, national IDs, etc.) and valid for at least 1 more month

• Fully visible — no cut-off edges, glare, or blur

• Not screenshots — original files or clear photos only

  • No edited, cropped, or screenshot versions

• Correct file format: JPG, PNG, or PDF, under 50MB

• Proof of address must be issued within the last 3 months and clearly show the client’s name and address.

Acceptable Proof of Address Documents

• Recent utility bill (electricity, gas, internet)

• Bank or credit card statement

• Local or national tax letter (issued within the past 12 months)

• Mortgage or rental agreement

• Official correspondence from a government authority

• Voter registration certificate

API specification

Uploads a KYC document for a customer.

put

Uploads a KYC (Know Your Customer) document for a specified customer.

Access to this endpoint requires a valid API key. The API key is sent in the x-api-key header.

Preconditions:

• The customer must have a user profile (see POST /customer/{id}/bank-transfer/user).

• The customer must have a KYC applicant (see POST /customer/{id}/bank-transfer/kyc/applicant).

Supported Document Types: One-sided documents (require documentType, content, country):

• PASSPORT

• RESIDENCE_PERMIT.

• UTILITY_BILL

• SELFIE.

Two-sided documents (require documentType, documentSubType, content, country):

• DRIVERS

• ID_CARD

• RESIDENCE_PERMIT.

Parameters:

• documentType: Type of document being uploaded.

• documentSubType: "FRONT_SIDE" or "BACK_SIDE" for two-sided documents.

• content: Base64-encoded document image. Must not exceed 500KB.

• country: Two-letter ISO 3166-1 alpha-2 country code.

Authorizations

api_key

x-api-keystringRequired

Path parameters

idstringRequired

Body

application/json

or

or

Responses

204

No Content

application/json

400

Bad request

application/json

401

Unauthorized

application/json

422

Unprocessable content

application/json

500

Internal server error

application/json

put

/customer/{id}/bank-transfer/kyc/document

HTTPcURLJavaScriptPython

PUT /api/v2/customer/{id}/bank-transfer/kyc/document HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "documentType": "PASSPORT",
  "content": "iVBORw0KGgoAAAANSUhEUgAA...",
  "country": "US"
}

Example 1Example 2

{
  "success": true,
  "data": null
}