diff --git a/openapi.json b/openapi.json
index 7d1c467..106f796 100644
--- a/openapi.json
+++ b/openapi.json
@@ -1723,9 +1723,9 @@
},
"/customers": {
"post": {
- "summary": "Start KYC",
- "description": "Start KYC process for the current user",
- "operationId": "startKyc",
+ "summary": "Create a customer",
+ "description": "Registra un customer. Restituisce 201 in caso di creazione o 409 in caso di duplicato.",
+ "operationId": "createCustomer",
"tags": [
"Customers"
],
@@ -1735,159 +1735,68 @@
}
],
"requestBody": {
- "description": "KYC request",
+ "required": true,
"content": {
"application/json": {
"schema": {
- "type": "object",
- "properties": {
- "redirectURL": {
- "type": "string",
- "format": "uri",
- "description": "URL where the user will be redirected after the KYC process is completed. If not specified, user will be redirected to the `/kyc/:identifier` endpoint wich will return the KYC data in JSON format.",
- "x-faker": "internet.url"
- },
- "canLogin": {
- "type": "boolean",
- "description": "If true, the user will be able to login using one of the supported identity providers and other information that FlowPay has about the user will be used to pre-fill the KYC data. If false, the user must provide all the required information even if FlowPay already has it.",
- "default": false
- },
- "flow": {
- "type": "string",
- "description": "Flow to be used for the KYC process. If not specified, user will be able to choose the flow.",
- "enum": [
- "consumer",
- "business"
- ]
- },
- "consumer": {
- "type": "object",
- "description": "Consumer data to be used to pre-fill the KYC",
- "properties": {
- "name": {
- "type": "string",
- "description": "Consumer name",
- "x-faker": "person.firstName"
- },
- "surname": {
- "type": "string",
- "description": "Consumer surname",
- "x-faker": "person.lastName"
- },
- "tin": {
- "$ref": "#/components/schemas/ConsumerTIN"
- },
- "email": {
- "type": "string",
- "format": "email",
- "description": "Consumer email address",
- "x-faker": "internet.email"
- },
- "phone": {
- "type": "string",
- "format": "phone",
- "description": "Consumer phone number",
- "x-faker": "phone.phoneNumber"
- },
- "address": {
- "type": "string",
- "description": "Consumer address",
- "x-faker": "address.streetAddress"
- },
- "birthDate": {
- "type": "string",
- "format": "datetime",
- "description": "Consumer birth date",
- "x-faker": "date.past"
- },
- "birthPlace": {
- "type": "string",
- "description": "Consumer birth place",
- "x-faker": "address.city"
- },
- "iban": {
- "type": "string",
- "description": "Consumer IBAN. If provided, FlowPay will use it to pre-validate ownership of the account, if autonomous IBAN check is not possibile, the IBAN will be used to find the bank where the account is held and the user will be asked to perform a Strong Customer Authentication with the bank.",
- "x-faker": "finance.iban"
- },
- "bank": {
- "type": "string",
- "description": "FlowPay identifier of the bank where the consumer holds the account. If provided, FlowPay will use it suggest the bank to the user during the Strong Customer Authentication process.
The identifier can be retrieved using the `/banks` endpoint.",
- "example": "Intesa Sanpaolo"
- }
- }
- },
- "company": {
- "type": "object",
- "description": "Company data to be used to pre-fill the KYC",
- "properties": {
- "name": {
- "type": "string",
- "description": "Company name",
- "x-faker": "company.companyName"
- },
- "tin": {
- "$ref": "#/components/schemas/BusinessTIN"
- },
- "country": {
- "type": "string",
- "description": "Company country",
- "x-faker": "address.country"
- },
- "email": {
- "type": "string",
- "format": "email",
- "description": "Company email address",
- "x-faker": "internet.email"
- },
- "certifiedEmail": {
- "type": "string",
- "format": "email",
- "description": "Company certified email address",
- "x-faker": "internet.email"
- },
- "phone": {
- "type": "string",
- "format": "phone",
- "description": "Company phone number",
- "x-faker": "phone.phoneNumber"
- },
- "address": {
- "type": "string",
- "description": "Company address",
- "x-faker": "address.streetAddress"
- },
- "iban": {
- "type": "string",
- "description": "Company IBAN. If provided, FlowPay will use it to pre-validate ownership of the account, if autonomous IBAN check is not possibile, the IBAN will be used to find the bank where the account is held and the user will be asked to perform a Strong Customer Authentication with the bank.",
- "x-faker": "finance.iban"
- },
- "bank": {
- "type": "string",
- "description": "FlowPay identifier of the bank where the company holds the account. If provided, FlowPay will use it suggest the bank to the user during the Strong Customer Authentication process.
The identifier can be retrieved using the `/banks` endpoint.",
- "example": "Intesa Sanpaolo"
- }
- }
- }
- },
- "required": []
+ "$ref": "#/components/schemas/CustomerCreate"
}
}
}
},
"responses": {
"201": {
- "description": "KYC started",
+ "description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
+ },
+ "examples": {
+ "created": {
+ "value": {
+ "id": "1a111111-2222-3333-4444-555555555555",
+ "createdAt": "2025-10-06T12:00:00Z",
+ "updatedAt": "2025-10-06T12:30:00Z",
+ "type": "consumer",
+ "client": "2b222222-3333-4444-5555-666666666666",
+ "entity": "3c333333-4444-5555-6666-777777777777",
+ "phoneNumber": "+390000000001",
+ "name": "Test",
+ "surname": "Customer",
+ "tin": "TSTCST00A00A000A",
+ "email": "test.customer@example.com",
+ "address": "Example Street 1, Milano",
+ "services": [
+ {
+ "service": "srtp"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "Conflict (customer already exists)",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
}
}
}
},
"400": {
- "$ref": "#/components/responses/BadRequest"
+ "description": "Bad request",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
}
}
},
@@ -3126,6 +3035,48 @@
}
}
},
+ "CustomerCreate": {
+ "type": "object",
+ "required": [
+ "tin",
+ "phoneNumber"
+ ],
+ "properties": {
+ "phoneNumber": {
+ "type": "string",
+ "description": "Numero mobile del cliente (E.164)",
+ "example": "+39333111222"
+ },
+ "services": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "enum": [
+ "srtp"
+ ]
+ },
+ "example": "[srtp]",
+ "description": "Servizi da attivare sul cliente"
+ },
+ "name": {
+ "type": "string",
+ "description": "Nome"
+ },
+ "surname": {
+ "type": "string",
+ "description": "Cognome"
+ },
+ "tin": {
+ "type": "string",
+ "description": "Codice fiscale (persona fisica) Optional when the customer entity already exists."
+ },
+ "email": {
+ "type": "string",
+ "format": "email",
+ "description": "Email del cliente"
+ }
+ }
+ },
"Customer": {
"type": "object",
"description": "Information about the customer registered from a payment request.",
@@ -3135,29 +3086,72 @@
"format": "uuid",
"description": "Unique identifier of the customer."
},
- "name": {
+ "createdAt": {
"type": "string",
- "description": "Full name as provided by the user."
+ "format": "date-time",
+ "description": "Customer creation timestamp."
},
- "providedName": {
+ "updatedAt": {
"type": "string",
- "description": "Full name as provided in the payment request."
+ "format": "date-time",
+ "description": "Customer update timestamp."
},
- "phoneNumber": {
- "$ref": "#/components/schemas/PhoneNumber",
- "description": "Mobile phone number of the registered customer. This field is present only if the phone number was provided in the payment request."
+ "type": {
+ "$ref": "#/components/schemas/CustomerType"
},
- "registrationRequestId": {
+ "client": {
"type": "string",
"format": "uuid",
- "description": "UUID of the payment request with which the customer was registered."
+ "description": "Client identifier owning the customer."
+ },
+ "entity": {
+ "type": "string",
+ "format": "uuid",
+ "description": "Related entity identifier."
+ },
+ "phoneNumber": {
+ "type": "string",
+ "description": "Mobile phone number of the registered customer."
+ },
+ "name": {
+ "type": "string",
+ "description": "Customer first name or display name."
+ },
+ "surname": {
+ "type": "string",
+ "description": "Customer surname."
+ },
+ "businessName": {
+ "type": "string",
+ "description": "Registered business name."
+ },
+ "tin": {
+ "type": "string",
+ "description": "Customer tax identifier."
+ },
+ "email": {
+ "type": "string",
+ "format": "email",
+ "description": "Customer email address."
+ },
+ "address": {
+ "type": "string",
+ "description": "Customer address."
+ },
+ "services": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/ServiceOutput"
+ },
+ "description": "Services currently configured for the customer."
}
- },
- "required": [
- "id",
- "name",
- "providedName",
- "registrationRequestId"
+ }
+ },
+ "CustomerType": {
+ "type": "string",
+ "enum": [
+ "consumer",
+ "business"
]
},
"Consumer": {
@@ -3203,6 +3197,29 @@
"description": "Italian fiscal code (16 alphanumeric characters).",
"pattern": "^[A-Z]{6}[0-9]{2}[A-Z][0-9]{2}[A-Z][0-9]{3}[A-Z]$"
},
+ "ServiceOutput": {
+ "type": "object",
+ "properties": {
+ "service": {
+ "type": "string"
+ }
+ }
+ },
+ "Error": {
+ "type": "object",
+ "required": [
+ "message"
+ ],
+ "properties": {
+ "message": {
+ "type": "string"
+ },
+ "details": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ },
"BusinessTIN": {
"type": "string",
"description": "European VAT number (format: ISO 2-letter country code followed by 8\u201312 alphanumeric characters).",