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

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
Path parameters
idstringRequired
Body
any ofOptional
or
or
Responses
204

No Content

application/json
put
/customer/{id}/bank-transfer/kyc/document
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"
}
{
  "success": true,
  "data": null
}

Last updated