> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://amer.developers.trustly.com/llms.txt. > For full documentation content, see https://amer.developers.trustly.com/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://amer.developers.trustly.com/_mcp/server. # Create or Update a Customer POST https://sandbox.trustly.one/api/v1/customers Content-Type: application/json Creates a new customer record in the merchant account. In cases when the customer was not created at the time an Authorization was established, use this endpoint to register customer details, such as name, email, and optional metadata, to support your integration. If an existing `customerId` or `externalId` is provided, the specified customer will be updated with any new or updated properties. To remove properties of an existing customer, set the property to `null`. Before using this endpoint, it may be helpful to call [Get Customer by ID](ref:get-customers-customerid) to obtain the relevant customer object. Reference: https://amer.developers.trustly.com/api-reference/api/customers/post-customers ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: Trustly API version: 1.0.0 paths: /customers: post: operationId: post-customers summary: Create or Update a Customer description: >- Creates a new customer record in the merchant account. In cases when the customer was not created at the time an Authorization was established, use this endpoint to register customer details, such as name, email, and optional metadata, to support your integration. If an existing `customerId` or `externalId` is provided, the specified customer will be updated with any new or updated properties. To remove properties of an existing customer, set the property to `null`. Before using this endpoint, it may be helpful to call [Get Customer by ID](ref:get-customers-customerid) to obtain the relevant customer object. tags: - subpackage_customers parameters: - name: externalId in: query description: The externalId that was passed when the Customer record was created. required: false schema: type: string - name: Authorization in: header description: '' required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Customers_post-customers_Response_200' requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/Customer' servers: - url: https://sandbox.trustly.one/api/v1 components: schemas: Address: type: object properties: address1: type: string description: Address line 1 (e.g., street or PO Box) address2: type: string description: Address line 2 (e.g., apartment, suite or unit number) city: type: string description: City, district, town or village state: type: string description: State, province or region code zip: type: string description: ZIP or Postal Code country: type: string description: >- 2 character [ISO Country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) required: - country description: Valid mailing or billing address associated with the customer title: Address CustomerCustomData: type: object properties: {} description: Object for sending merchant-specific custom data. title: CustomerCustomData DriverLicense: type: object properties: number: type: string description: Driver License number. state: type: string description: 2 character ISO State code. required: - number - state title: DriverLicense Customer: type: object properties: name: type: string description: Full name of the Customer taxId: type: string description: >- Customer tax ID (e.g. SSN [US], SIN [CA]). *May be required depending on industry and location.* address: $ref: '#/components/schemas/Address' phone: type: string description: Customer phone number. email: type: string description: Customer email address. dateOfBirth: type: string description: Customer date of birth. createdAt: type: integer description: The record created date and time as a UNIX timestamp. updatedAt: type: integer description: The record created date and time as a UNIX timestamp. customerId: type: string description: A unique Trustly customer identifier. externalId: type: string description: A unique merchant customer identifier. merchantId: type: string description: A unique Trustly merchant identifier. enrollDate: type: integer description: >- Date of the user's first transaction in your system, regardless of payment method used as a UNIX timestamp. vip: type: string description: >- Range that determines how low-risk the customer represents to the merchant currency: type: string description: Customer currency. balance: type: string description: >- Customer account balance (not associated with a financial institution account). organizationNumber: type: string description: Organization number for business accounts externalTier: type: string description: >- It should describe the customer''s rank to the merchant (e.g. Gold, Diamond, 4 stars, etc.) personId: type: string description: Unique customer identity throughout different banks. customData: $ref: '#/components/schemas/CustomerCustomData' description: Object for sending merchant-specific custom data. driverLicense: $ref: '#/components/schemas/DriverLicense' nationalId: type: string description: Customer National ID required: - name - address - phone - email description: >- The Trustly customer object, containing identification details and contact information. title: Customer Customers_post-customers_Response_200: type: object properties: customer: $ref: '#/components/schemas/Customer' title: Customers_post-customers_Response_200 securitySchemes: HTTPBasic: type: http scheme: basic description: '' ``` ## SDK Code Examples ```python Example import requests url = "https://sandbox.trustly.one/api/v1/customers" payload = { "name": "Joe User", "address": { "country": "US", "address1": "2000 Broadway St", "city": "Redwood City", "state": "CA", "zip": "94063" }, "phone": "+16505551212", "email": "joe.user@mail.com", "taxId": "012345678", "createdAt": 1555696836548, "updatedAt": 1555696836548, "customerId": "1002580963", "externalId": "4567890", "merchantId": "1002463580", "enrollDate": 1555696836548, "driverLicense": { "number": "A1234567", "state": "CA" } } headers = { "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, auth=("", "")) print(response.json()) ``` ```javascript Example const url = 'https://sandbox.trustly.one/api/v1/customers'; const credentials = btoa(":"); const options = { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json' }, body: '{"name":"Joe User","address":{"country":"US","address1":"2000 Broadway St","city":"Redwood City","state":"CA","zip":"94063"},"phone":"+16505551212","email":"joe.user@mail.com","taxId":"012345678","createdAt":1555696836548,"updatedAt":1555696836548,"customerId":"1002580963","externalId":"4567890","merchantId":"1002463580","enrollDate":1555696836548,"driverLicense":{"number":"A1234567","state":"CA"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://sandbox.trustly.one/api/v1/customers" payload := strings.NewReader("{\n \"name\": \"Joe User\",\n \"address\": {\n \"country\": \"US\",\n \"address1\": \"2000 Broadway St\",\n \"city\": \"Redwood City\",\n \"state\": \"CA\",\n \"zip\": \"94063\"\n },\n \"phone\": \"+16505551212\",\n \"email\": \"joe.user@mail.com\",\n \"taxId\": \"012345678\",\n \"createdAt\": 1555696836548,\n \"updatedAt\": 1555696836548,\n \"customerId\": \"1002580963\",\n \"externalId\": \"4567890\",\n \"merchantId\": \"1002463580\",\n \"enrollDate\": 1555696836548,\n \"driverLicense\": {\n \"number\": \"A1234567\",\n \"state\": \"CA\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.SetBasicAuth("", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Example require 'uri' require 'net/http' url = URI("https://sandbox.trustly.one/api/v1/customers") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request.basic_auth("", "") request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"Joe User\",\n \"address\": {\n \"country\": \"US\",\n \"address1\": \"2000 Broadway St\",\n \"city\": \"Redwood City\",\n \"state\": \"CA\",\n \"zip\": \"94063\"\n },\n \"phone\": \"+16505551212\",\n \"email\": \"joe.user@mail.com\",\n \"taxId\": \"012345678\",\n \"createdAt\": 1555696836548,\n \"updatedAt\": 1555696836548,\n \"customerId\": \"1002580963\",\n \"externalId\": \"4567890\",\n \"merchantId\": \"1002463580\",\n \"enrollDate\": 1555696836548,\n \"driverLicense\": {\n \"number\": \"A1234567\",\n \"state\": \"CA\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java Example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://sandbox.trustly.one/api/v1/customers") .basicAuth("", "") .header("Content-Type", "application/json") .body("{\n \"name\": \"Joe User\",\n \"address\": {\n \"country\": \"US\",\n \"address1\": \"2000 Broadway St\",\n \"city\": \"Redwood City\",\n \"state\": \"CA\",\n \"zip\": \"94063\"\n },\n \"phone\": \"+16505551212\",\n \"email\": \"joe.user@mail.com\",\n \"taxId\": \"012345678\",\n \"createdAt\": 1555696836548,\n \"updatedAt\": 1555696836548,\n \"customerId\": \"1002580963\",\n \"externalId\": \"4567890\",\n \"merchantId\": \"1002463580\",\n \"enrollDate\": 1555696836548,\n \"driverLicense\": {\n \"number\": \"A1234567\",\n \"state\": \"CA\"\n }\n}") .asString(); ``` ```php Example request('POST', 'https://sandbox.trustly.one/api/v1/customers', [ 'body' => '{ "name": "Joe User", "address": { "country": "US", "address1": "2000 Broadway St", "city": "Redwood City", "state": "CA", "zip": "94063" }, "phone": "+16505551212", "email": "joe.user@mail.com", "taxId": "012345678", "createdAt": 1555696836548, "updatedAt": 1555696836548, "customerId": "1002580963", "externalId": "4567890", "merchantId": "1002463580", "enrollDate": 1555696836548, "driverLicense": { "number": "A1234567", "state": "CA" } }', 'headers' => [ 'Content-Type' => 'application/json', ], 'auth' => ['', ''], ]); echo $response->getBody(); ``` ```csharp Example using RestSharp; using RestSharp.Authenticators; var client = new RestClient("https://sandbox.trustly.one/api/v1/customers"); client.Authenticator = new HttpBasicAuthenticator("", ""); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"Joe User\",\n \"address\": {\n \"country\": \"US\",\n \"address1\": \"2000 Broadway St\",\n \"city\": \"Redwood City\",\n \"state\": \"CA\",\n \"zip\": \"94063\"\n },\n \"phone\": \"+16505551212\",\n \"email\": \"joe.user@mail.com\",\n \"taxId\": \"012345678\",\n \"createdAt\": 1555696836548,\n \"updatedAt\": 1555696836548,\n \"customerId\": \"1002580963\",\n \"externalId\": \"4567890\",\n \"merchantId\": \"1002463580\",\n \"enrollDate\": 1555696836548,\n \"driverLicense\": {\n \"number\": \"A1234567\",\n \"state\": \"CA\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example import Foundation let credentials = Data(":".utf8).base64EncodedString() let headers = [ "Authorization": "Basic \(credentials)", "Content-Type": "application/json" ] let parameters = [ "name": "Joe User", "address": [ "country": "US", "address1": "2000 Broadway St", "city": "Redwood City", "state": "CA", "zip": "94063" ], "phone": "+16505551212", "email": "joe.user@mail.com", "taxId": "012345678", "createdAt": 1555696836548, "updatedAt": 1555696836548, "customerId": "1002580963", "externalId": "4567890", "merchantId": "1002463580", "enrollDate": 1555696836548, "driverLicense": [ "number": "A1234567", "state": "CA" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox.trustly.one/api/v1/customers")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```