diff --git a/openapi.json b/openapi.json index 7b95b9e..3392255 100644 --- a/openapi.json +++ b/openapi.json @@ -1602,29 +1602,7 @@ "$ref": "#/components/schemas/ErrorExtended" }, { - "type": "object", - "required": [ - "instance", - "error_code", - "error_message" - ], - "properties": { - "instance": { - "type": "string", - "description": "Unique identifier of this error occurrence.", - "example": "32a44c6c-85d3-49e8-86bf-a5bba98c4621" - }, - "error_code": { - "type": "string", - "description": "Platform code for the error.", - "example": "INVALID" - }, - "error_message": { - "type": "string", - "description": "Short description of the error.", - "example": "customer_id" - } - } + "$ref": "#/components/schemas/CustomerValidationError" } ] }, @@ -5573,7 +5551,7 @@ } } }, - "description": "Creates a Checkout for a Reader.\n\nThis process is asynchronous and the actual transaction may take some time to be started on the device.\n\n\nThere are some caveats when using this endpoint:\n* The target device must be online, otherwise checkout won't be accepted\n* After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected.\n\n\n**Note**: If the target device is a Solo, it must be in version 3.3.24.3 or higher.\n", + "description": "Creates a Checkout for a Reader.\n\nThis process is asynchronous and the actual transaction may take some time to be started on the device.\n\n\nThere are some caveats when using this endpoint:\n* The target device must be online, otherwise checkout won't be accepted\n* After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected.\n\n\n**Note**: If the target device is a Solo, it must be in version 3.3.24.3 or higher.\n\n\n**Affiliate metadata**: Optionally include an `affiliate` object to attach integrator metadata to the payment.\nWhen provided, the affiliate key is validated against Identity Admin, stored server-side for approximately 600 seconds,\nand merged into the downstream payment when the reader starts the transaction using the returned `client_transaction_id`.\nAffiliate metadata is not sent to the device during checkout creation.\n", "operationId": "CreateReaderCheckout", "parameters": [ { @@ -5622,16 +5600,22 @@ "400": { "content": { "application/json": { + "example": { + "errors": { + "detail": "Invalid affiliate key.", + "type": "INVALID_AFFILIATE_KEY" + } + }, "schema": { "$ref": "#/components/schemas/CreateReaderCheckoutError" } }, "application/problem+json": { "example": { - "detail": "Bad Request", + "detail": "Invalid affiliate key.", "status": 400, - "title": "Bad Request", - "type": "https://developer.sumup.com/problem/bad-request" + "title": "Invalid Affiliate Key", + "type": "https://developer.sumup.com/problem/invalid-affiliate-key" }, "schema": { "$ref": "#/components/schemas/Problem" @@ -5690,11 +5674,23 @@ } }, "application/problem+json": { - "example": { - "detail": "Validation failed", - "status": 422, - "title": "Unprocessable Entity", - "type": "https://developer.sumup.com/problem/validation-error" + "examples": { + "PaymentMethodNotAllowed": { + "value": { + "detail": "Payment method not allowed for this merchant.", + "status": 422, + "title": "Payment Method Not Allowed", + "type": "https://developer.sumup.com/problem/payment-method-not-allowed" + } + }, + "ValidationError": { + "value": { + "detail": "Validation failed", + "status": 422, + "title": "Unprocessable Content", + "type": "https://developer.sumup.com/problem/validation-error" + } + } }, "schema": { "$ref": "#/components/schemas/Problem" @@ -6768,6 +6764,33 @@ } } }, + "CustomerValidationError": { + "title": "Customer Validation Error", + "description": "Details of a customer validation error.", + "type": "object", + "required": [ + "instance", + "error_code", + "error_message" + ], + "properties": { + "instance": { + "type": "string", + "description": "Unique identifier of this error occurrence.", + "example": "32a44c6c-85d3-49e8-86bf-a5bba98c4621" + }, + "error_code": { + "type": "string", + "description": "Platform code for the error.", + "example": "INVALID" + }, + "error_message": { + "type": "string", + "description": "Short description of the error.", + "example": "customer_id" + } + } + }, "Error": { "title": "Error", "type": "object", @@ -9818,6 +9841,15 @@ } } }, + "PaymentMethodNotAllowed": { + "description": "Error returned when the requested payment method is not supported for the merchant (e.g. pix for non-BR merchants).", + "value": { + "errors": { + "detail": "Payment method not allowed for this merchant.", + "type": "PAYMENT_METHOD_NOT_ALLOWED" + } + } + }, "ReaderBusy": { "description": "Error returned when a checkout was requested in the last 60 seconds.", "value": { @@ -9883,6 +9915,7 @@ "client_transaction_id": "00e33a36-c99b-4cb2-b635-b90c1455c9c8", "created_at": "2026-07-07T20:41:16.315434Z", "installments": 1, + "payment_failure_reason": null, "payment_status": "pending", "payment_type": "card", "reader_firmware_version": "3.3.3.21", @@ -9901,10 +9934,11 @@ "data": { "properties": { "card_type": { - "description": "Type of the card. Required for some countries", + "description": "Type of the card, or null when no card type was specified.", "enum": [ "credit", - "debit" + "debit", + null ], "type": [ "string", @@ -10029,6 +10063,7 @@ "reader_firmware_version", "installments", "payment_status", + "payment_failure_reason", "valid_until", "created_at", "updated_at", @@ -10202,6 +10237,8 @@ "type": { "description": "Key indicating type of error", "enum": [ + "INVALID_AFFILIATE_KEY", + "APP_OUTDATED", "INVALID_BEARER_TOKEN", "INVALID_USER_AGENT", "NOT_ENOUGH_UNPAID_PAYOUTS", @@ -10238,7 +10275,7 @@ "type": "string" }, "client_transaction_id": { - "description": "The client transaction ID is a unique identifier for the transaction that is generated for the client.\n\nIt can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get).\n", + "description": "**SumUp API flow.** Unique identifier for this checkout-generated transaction.\n\nPass this value as `terminal.client_id` when the reader creates the terminal so\ncheckout metadata (including affiliate sent here) is merged into the payment.\n\nSDK clients do not use this field for affiliate metadata; they send affiliate in\n`terminal.affiliate` on `POST /api/terminals` instead.\n", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "string" } @@ -10291,7 +10328,7 @@ "type": "object" }, "CreateReaderCheckoutRequest": { - "description": "Reader Checkout", + "description": "Reader Checkout request for SumUp API clients.\n\nSumUp API integrators send affiliate metadata in the `affiliate` field below. SDK clients\nuse `POST /api/terminals` with `terminal.affiliate` instead.\n", "example": { "aade": { "provider_id": "123", @@ -10302,7 +10339,10 @@ "app_id": "com.example.app", "foreign_transaction_id": "123456", "key": "ef7b684a-d6f4-4e93-9b1b-6acdd6564a8e", - "tags": {} + "tags": { + "custom_key_1": "custom_value_1", + "custom_key_2": "custom_value_2" + } }, "card_type": "debit", "description": "This is a description...", @@ -10348,46 +10388,51 @@ "type": "object" }, "affiliate": { - "description": "Affiliate metadata for the transaction.\nIt is a field that allow for integrators to track the source of the transaction.\n", - "properties": { - "app_id": { - "description": "Application ID of the affiliate.\nIt is a unique identifier for the application and should be set by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page.\n", - "example": "com.example.app", - "type": "string" - }, - "foreign_transaction_id": { - "description": "Foreign transaction ID of the affiliate.\nIt is a unique identifier for the transaction.\nIt can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get).\n", - "example": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f", - "type": "string" - }, - "key": { - "description": "Key of the affiliate.\nIt is a unique identifier for the key and should be generated by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page.\n", - "example": "123e4567-e89b-12d3-a456-426614174000", - "type": "string" - }, - "tags": { - "additionalProperties": true, - "description": "Additional metadata for the transaction.\nIt is key-value object that can be associated with the transaction.\n", - "example": { - "custom_key_1": "custom_value_1", - "custom_key_2": "custom_value_2" + "allOf": [ + { + "description": "Shared affiliate metadata fields.\n\nWhere to send this object depends on the client type: SDK clients use\n`terminal.affiliate` on `POST /api/terminals`; SumUp API clients use the\n`affiliate` field on Reader Checkout.\n", + "properties": { + "app_id": { + "description": "Integrator application identifier from the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page.\nRequired when the affiliate object is provided.\n", + "example": "com.example.app", + "type": "string" + }, + "foreign_transaction_id": { + "description": "Integrator-owned transaction reference. Optional.\nForwarded to terminal-hub and can be used later to fetch the transaction via the [Transactions API](https://developer.sumup.com/api/transactions/get).\n", + "example": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f", + "type": "string" + }, + "key": { + "description": "Affiliate key generated in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page.\nRequired when the affiliate object is provided. Validated against Identity Admin when both `app_id` and `key` are present.\n", + "example": "123e4567-e89b-12d3-a456-426614174000", + "type": "string" + }, + "tags": { + "additionalProperties": true, + "description": "Optional key-value metadata associated with the transaction.\nForwarded to terminal-hub together with the payment.\n", + "example": { + "custom_key_1": "custom_value_1", + "custom_key_2": "custom_value_2" + }, + "type": "object" + } }, - "type": "object" + "required": [ + "app_id", + "key" + ], + "title": "Affiliate", + "type": [ + "object", + "null" + ] } - }, - "required": [ - "app_id", - "key", - "foreign_transaction_id" ], - "title": "Affiliate", - "type": [ - "object", - "null" - ] + "description": "**SumUp API clients:** affiliate ingress for Reader Checkout.\n\nSend integrator metadata here when creating a checkout. When `app_id` and `key` are both\npresent, the key is validated against Identity Admin, stored server-side, and merged into\nthe payment when the reader starts the transaction using the returned `client_transaction_id`\nas `terminal.client_id`.\n\nSDK clients send affiliate on `POST /api/terminals` instead.\n", + "type": "null" }, "card_type": { - "description": "The card type of the card used for the transaction.\nIs is required only for some countries (e.g: Brazil).\n", + "description": "The card type of the card used for the transaction.\nIt is required only for some countries (e.g: Brazil).\n", "enum": [ "credit", "debit" @@ -10400,7 +10445,7 @@ "type": "string" }, "installments": { - "description": "Number of installments for the transaction.\nIt may vary according to the merchant country.\nFor example, in Brazil, the maximum number of installments is 12.\n\nOmit if the merchant country does support installments.\nOtherwise, the checkout will be rejected.\n", + "description": "Number of installments for the transaction.\nIt may vary according to the merchant country.\nFor example, in Brazil, the maximum number of installments is 12.\n\nOmit if the merchant country does not support installments.\nOtherwise, the checkout will be rejected.\n", "example": 1, "minimum": 1, "type": [ @@ -10408,6 +10453,16 @@ "null" ] }, + "payment_type": { + "default": "card", + "description": "The payment method type for the transaction. Defaults to `card`.\n\nUse `pix` to initiate a Pix QR-code payment flow on the device.\nPix is only supported for Brazilian merchants; other merchants will receive a 422 error.\n", + "enum": [ + "card", + "pix" + ], + "example": "card", + "type": "string" + }, "return_url": { "description": "Webhook URL to which the payment result will be sent.\nIt must be a HTTPS url.\n", "example": "https://www.example.com", @@ -10415,13 +10470,18 @@ "type": "string" }, "tip_rates": { - "description": "List of tipping rates to be displayed to the cardholder.\nThe rates are in percentage and should be between 0.01 and 0.99.\nThe list should be sorted in ascending order.\n", + "description": "Exactly three distinct tipping rates to be displayed to the cardholder.\nEach rate is a fraction between 0.01 and 1.00 in increments of 0.01.\nThe rates are sorted in ascending order by the server.\n", "items": { "format": "float", + "maximum": 1, + "minimum": 0.01, "multipleOf": 0.01, "type": "number" }, - "type": "array" + "maxItems": 3, + "minItems": 3, + "type": "array", + "uniqueItems": true }, "tip_timeout": { "default": 30, diff --git a/src/main/java/com/sumup/sdk/clients/ReadersAsyncClient.java b/src/main/java/com/sumup/sdk/clients/ReadersAsyncClient.java index bdd1764..630dc28 100644 --- a/src/main/java/com/sumup/sdk/clients/ReadersAsyncClient.java +++ b/src/main/java/com/sumup/sdk/clients/ReadersAsyncClient.java @@ -92,7 +92,12 @@ public CompletableFuture create( * The target device must be online, otherwise checkout won't be accepted * After the checkout is * accepted, the system has 60 seconds to start the payment on the target device. During this * time, any other checkout for the same device will be rejected. **Note**: If the target device - * is a Solo, it must be in version 3.3.24.3 or higher. + * is a Solo, it must be in version 3.3.24.3 or higher. **Affiliate metadata**: Optionally include + * an `affiliate` object to attach integrator metadata to the payment. When provided, the + * affiliate key is validated against Identity Admin, stored server-side for approximately 600 + * seconds, and merged into the downstream payment when the reader starts the transaction using + * the returned `client_transaction_id`. Affiliate metadata is not sent to the device during + * checkout creation. * *

Operation ID: CreateReaderCheckout * @@ -121,7 +126,12 @@ public CompletableFuture crea * The target device must be online, otherwise checkout won't be accepted * After the checkout is * accepted, the system has 60 seconds to start the payment on the target device. During this * time, any other checkout for the same device will be rejected. **Note**: If the target device - * is a Solo, it must be in version 3.3.24.3 or higher. + * is a Solo, it must be in version 3.3.24.3 or higher. **Affiliate metadata**: Optionally include + * an `affiliate` object to attach integrator metadata to the payment. When provided, the + * affiliate key is validated against Identity Admin, stored server-side for approximately 600 + * seconds, and merged into the downstream payment when the reader starts the transaction using + * the returned `client_transaction_id`. Affiliate metadata is not sent to the device during + * checkout creation. * *

Operation ID: CreateReaderCheckout * diff --git a/src/main/java/com/sumup/sdk/clients/ReadersClient.java b/src/main/java/com/sumup/sdk/clients/ReadersClient.java index 983f09b..b296af3 100644 --- a/src/main/java/com/sumup/sdk/clients/ReadersClient.java +++ b/src/main/java/com/sumup/sdk/clients/ReadersClient.java @@ -91,7 +91,12 @@ public com.sumup.sdk.models.Reader create( * The target device must be online, otherwise checkout won't be accepted * After the checkout is * accepted, the system has 60 seconds to start the payment on the target device. During this * time, any other checkout for the same device will be rejected. **Note**: If the target device - * is a Solo, it must be in version 3.3.24.3 or higher. + * is a Solo, it must be in version 3.3.24.3 or higher. **Affiliate metadata**: Optionally include + * an `affiliate` object to attach integrator metadata to the payment. When provided, the + * affiliate key is validated against Identity Admin, stored server-side for approximately 600 + * seconds, and merged into the downstream payment when the reader starts the transaction using + * the returned `client_transaction_id`. Affiliate metadata is not sent to the device during + * checkout creation. * *

Operation ID: CreateReaderCheckout * @@ -119,7 +124,12 @@ public com.sumup.sdk.models.CreateReaderCheckoutResponse createCheckout( * The target device must be online, otherwise checkout won't be accepted * After the checkout is * accepted, the system has 60 seconds to start the payment on the target device. During this * time, any other checkout for the same device will be rejected. **Note**: If the target device - * is a Solo, it must be in version 3.3.24.3 or higher. + * is a Solo, it must be in version 3.3.24.3 or higher. **Affiliate metadata**: Optionally include + * an `affiliate` object to attach integrator metadata to the payment. When provided, the + * affiliate key is validated against Identity Admin, stored server-side for approximately 600 + * seconds, and merged into the downstream payment when the reader starts the transaction using + * the returned `client_transaction_id`. Affiliate metadata is not sent to the device during + * checkout creation. * *

Operation ID: CreateReaderCheckout * diff --git a/src/main/java/com/sumup/sdk/models/Affiliate2.java b/src/main/java/com/sumup/sdk/models/Affiliate2.java deleted file mode 100644 index d8b1e9e..0000000 --- a/src/main/java/com/sumup/sdk/models/Affiliate2.java +++ /dev/null @@ -1,118 +0,0 @@ -// Code generated by sumup-java/codegen. DO NOT EDIT. -package com.sumup.sdk.models; - -import java.util.Objects; - -/** - * Affiliate metadata for the transaction. It is a field that allow for integrators to track the - * source of the transaction. - */ -public record Affiliate2( - /** - * Application ID of the affiliate. It is a unique identifier for the application and should be - * set by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) - * page. - */ - String appId, - - /** - * Foreign transaction ID of the affiliate. It is a unique identifier for the transaction. It - * can be used later to fetch the transaction details via the [Transactions - * API](https://developer.sumup.com/api/transactions/get). - */ - String foreignTransactionId, - - /** - * Key of the affiliate. It is a unique identifier for the key and should be generated by the - * integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page. - */ - String key, - - /** - * Additional metadata for the transaction. It is key-value object that can be associated with - * the transaction. - */ - java.util.Map tags) { - /** - * Creates a builder for Affiliate2. - * - * @return Builder that constructs immutable Affiliate2 instances. - */ - public static Builder builder() { - return new Builder(); - } - - /** Builder for Affiliate2 instances. */ - public static final class Builder { - private String appId; - private String foreignTransactionId; - private String key; - private java.util.Map tags; - - private Builder() {} - - /** - * Sets the value for {@code appId}. - * - * @param appId Application ID of the affiliate. It is a unique identifier for the application - * and should be set by the integrator in the [Affiliate - * Keys](https://developer.sumup.com/affiliate-keys) page. - * @return This builder instance. - */ - public Builder appId(String appId) { - this.appId = appId; - return this; - } - - /** - * Sets the value for {@code foreignTransactionId}. - * - * @param foreignTransactionId Foreign transaction ID of the affiliate. It is a unique - * identifier for the transaction. It can be used later to fetch the transaction details via - * the [Transactions API](https://developer.sumup.com/api/transactions/get). - * @return This builder instance. - */ - public Builder foreignTransactionId(String foreignTransactionId) { - this.foreignTransactionId = foreignTransactionId; - return this; - } - - /** - * Sets the value for {@code key}. - * - * @param key Key of the affiliate. It is a unique identifier for the key and should be - * generated by the integrator in the [Affiliate - * Keys](https://developer.sumup.com/affiliate-keys) page. - * @return This builder instance. - */ - public Builder key(String key) { - this.key = key; - return this; - } - - /** - * Sets the value for {@code tags}. - * - * @param tags Additional metadata for the transaction. It is key-value object that can be - * associated with the transaction. - * @return This builder instance. - */ - public Builder tags(java.util.Map tags) { - this.tags = tags; - return this; - } - - /** - * Builds an immutable Affiliate2 instance. - * - * @return Immutable Affiliate2. - */ - public Affiliate2 build() { - return new Affiliate2( - Objects.requireNonNull(appId, "appId"), - Objects.requireNonNull(foreignTransactionId, "foreignTransactionId"), - Objects.requireNonNull(key, "key"), - tags); - } - } -} diff --git a/src/main/java/com/sumup/sdk/models/BadRequestErrorsType.java b/src/main/java/com/sumup/sdk/models/BadRequestErrorsType.java index a421bbc..6051d48 100644 --- a/src/main/java/com/sumup/sdk/models/BadRequestErrorsType.java +++ b/src/main/java/com/sumup/sdk/models/BadRequestErrorsType.java @@ -7,6 +7,9 @@ /** Key indicating type of error */ public final class BadRequestErrorsType { + public static final BadRequestErrorsType INVALID_AFFILIATE_KEY = + new BadRequestErrorsType("INVALID_AFFILIATE_KEY"); + public static final BadRequestErrorsType APP_OUTDATED = new BadRequestErrorsType("APP_OUTDATED"); public static final BadRequestErrorsType INVALID_BEARER_TOKEN = new BadRequestErrorsType("INVALID_BEARER_TOKEN"); public static final BadRequestErrorsType INVALID_USER_AGENT = diff --git a/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequest.java b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequest.java index abfaac8..927e8db 100644 --- a/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequest.java +++ b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequest.java @@ -3,7 +3,11 @@ import java.util.Objects; -/** Reader Checkout */ +/** + * Reader Checkout request for SumUp API clients. SumUp API integrators send affiliate metadata in + * the `affiliate` field below. SDK clients use `POST /api/terminals` with `terminal.affiliate` + * instead. + */ public record CreateReaderCheckoutRequest( /** * Optional object containing data for transactions from ERP integrators in Greece that comply @@ -14,13 +18,16 @@ public record CreateReaderCheckoutRequest( com.sumup.sdk.models.CreateReaderCheckoutRequestAade aade, /** - * Affiliate metadata for the transaction. It is a field that allow for integrators to track the - * source of the transaction. + * **SumUp API clients:** affiliate ingress for Reader Checkout. Send integrator metadata here + * when creating a checkout. When `app_id` and `key` are both present, the key is validated + * against Identity Admin, stored server-side, and merged into the payment when the reader + * starts the transaction using the returned `client_transaction_id` as `terminal.client_id`. + * SDK clients send affiliate on `POST /api/terminals` instead. */ - com.sumup.sdk.models.Affiliate2 affiliate, + com.sumup.sdk.models.CreateReaderCheckoutRequestAffiliate affiliate, /** - * The card type of the card used for the transaction. Is is required only for some countries + * The card type of the card used for the transaction. It is required only for some countries * (e.g: Brazil). */ com.sumup.sdk.models.CreateReaderCheckoutRequestCardType cardType, @@ -31,16 +38,24 @@ public record CreateReaderCheckoutRequest( /** * Number of installments for the transaction. It may vary according to the merchant country. * For example, in Brazil, the maximum number of installments is 12. Omit if the merchant - * country does support installments. Otherwise, the checkout will be rejected. + * country does not support installments. Otherwise, the checkout will be rejected. */ Long installments, + /** + * The payment method type for the transaction. Defaults to `card`. Use `pix` to initiate a Pix + * QR-code payment flow on the device. Pix is only supported for Brazilian merchants; other + * merchants will receive a 422 error. + */ + com.sumup.sdk.models.CreateReaderCheckoutRequestPaymentType paymentType, + /** Webhook URL to which the payment result will be sent. It must be a HTTPS url. */ String returnUrl, /** - * List of tipping rates to be displayed to the cardholder. The rates are in percentage and - * should be between 0.01 and 0.99. The list should be sorted in ascending order. + * Exactly three distinct tipping rates to be displayed to the cardholder. Each rate is a + * fraction between 0.01 and 1.00 in increments of 0.01. The rates are sorted in ascending order + * by the server. */ java.util.List tipRates, @@ -68,10 +83,11 @@ public static Builder builder() { /** Builder for CreateReaderCheckoutRequest instances. */ public static final class Builder { private com.sumup.sdk.models.CreateReaderCheckoutRequestAade aade; - private com.sumup.sdk.models.Affiliate2 affiliate; + private com.sumup.sdk.models.CreateReaderCheckoutRequestAffiliate affiliate; private com.sumup.sdk.models.CreateReaderCheckoutRequestCardType cardType; private String description; private Long installments; + private com.sumup.sdk.models.CreateReaderCheckoutRequestPaymentType paymentType; private String returnUrl; private java.util.List tipRates; private Long tipTimeout; @@ -96,11 +112,15 @@ public Builder aade(com.sumup.sdk.models.CreateReaderCheckoutRequestAade aade) { /** * Sets the value for {@code affiliate}. * - * @param affiliate Affiliate metadata for the transaction. It is a field that allow for - * integrators to track the source of the transaction. + * @param affiliate **SumUp API clients:** affiliate ingress for Reader Checkout. Send + * integrator metadata here when creating a checkout. When `app_id` and `key` are both + * present, the key is validated against Identity Admin, stored server-side, and merged into + * the payment when the reader starts the transaction using the returned + * `client_transaction_id` as `terminal.client_id`. SDK clients send affiliate on `POST + * /api/terminals` instead. * @return This builder instance. */ - public Builder affiliate(com.sumup.sdk.models.Affiliate2 affiliate) { + public Builder affiliate(com.sumup.sdk.models.CreateReaderCheckoutRequestAffiliate affiliate) { this.affiliate = affiliate; return this; } @@ -108,7 +128,7 @@ public Builder affiliate(com.sumup.sdk.models.Affiliate2 affiliate) { /** * Sets the value for {@code cardType}. * - * @param cardType The card type of the card used for the transaction. Is is required only for + * @param cardType The card type of the card used for the transaction. It is required only for * some countries (e.g: Brazil). * @return This builder instance. */ @@ -133,7 +153,7 @@ public Builder description(String description) { * * @param installments Number of installments for the transaction. It may vary according to the * merchant country. For example, in Brazil, the maximum number of installments is 12. Omit - * if the merchant country does support installments. Otherwise, the checkout will be + * if the merchant country does not support installments. Otherwise, the checkout will be * rejected. * @return This builder instance. */ @@ -142,6 +162,20 @@ public Builder installments(Long installments) { return this; } + /** + * Sets the value for {@code paymentType}. + * + * @param paymentType The payment method type for the transaction. Defaults to `card`. Use `pix` + * to initiate a Pix QR-code payment flow on the device. Pix is only supported for Brazilian + * merchants; other merchants will receive a 422 error. + * @return This builder instance. + */ + public Builder paymentType( + com.sumup.sdk.models.CreateReaderCheckoutRequestPaymentType paymentType) { + this.paymentType = paymentType; + return this; + } + /** * Sets the value for {@code returnUrl}. * @@ -157,9 +191,9 @@ public Builder returnUrl(String returnUrl) { /** * Sets the value for {@code tipRates}. * - * @param tipRates List of tipping rates to be displayed to the cardholder. The rates are in - * percentage and should be between 0.01 and 0.99. The list should be sorted in ascending - * order. + * @param tipRates Exactly three distinct tipping rates to be displayed to the cardholder. Each + * rate is a fraction between 0.01 and 1.00 in increments of 0.01. The rates are sorted in + * ascending order by the server. * @return This builder instance. */ public Builder tipRates(java.util.List tipRates) { @@ -205,6 +239,7 @@ public CreateReaderCheckoutRequest build() { cardType, description, installments, + paymentType, returnUrl, tipRates, tipTimeout, diff --git a/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestAffiliate.java b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestAffiliate.java new file mode 100644 index 0000000..f93338f --- /dev/null +++ b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestAffiliate.java @@ -0,0 +1,123 @@ +// Code generated by sumup-java/codegen. DO NOT EDIT. +package com.sumup.sdk.models; + +import java.util.Objects; + +/** + * **SumUp API clients:** affiliate ingress for Reader Checkout. Send integrator metadata here when + * creating a checkout. When `app_id` and `key` are both present, the key is validated against + * Identity Admin, stored server-side, and merged into the payment when the reader starts the + * transaction using the returned `client_transaction_id` as `terminal.client_id`. SDK clients send + * affiliate on `POST /api/terminals` instead. + */ +public record CreateReaderCheckoutRequestAffiliate( + /** + * Integrator application identifier from the [Affiliate + * Keys](https://developer.sumup.com/affiliate-keys) page. Required when the affiliate object is + * provided. + */ + String appId, + + /** + * Integrator-owned transaction reference. Optional. Forwarded to terminal-hub and can be used + * later to fetch the transaction via the [Transactions + * API](https://developer.sumup.com/api/transactions/get). + */ + String foreignTransactionId, + + /** + * Affiliate key generated in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) + * page. Required when the affiliate object is provided. Validated against Identity Admin when + * both `app_id` and `key` are present. + */ + String key, + + /** + * Optional key-value metadata associated with the transaction. Forwarded to terminal-hub + * together with the payment. + */ + java.util.Map tags) { + /** + * Creates a builder for CreateReaderCheckoutRequestAffiliate. + * + * @return Builder that constructs immutable CreateReaderCheckoutRequestAffiliate instances. + */ + public static Builder builder() { + return new Builder(); + } + + /** Builder for CreateReaderCheckoutRequestAffiliate instances. */ + public static final class Builder { + private String appId; + private String foreignTransactionId; + private String key; + private java.util.Map tags; + + private Builder() {} + + /** + * Sets the value for {@code appId}. + * + * @param appId Integrator application identifier from the [Affiliate + * Keys](https://developer.sumup.com/affiliate-keys) page. Required when the affiliate + * object is provided. + * @return This builder instance. + */ + public Builder appId(String appId) { + this.appId = appId; + return this; + } + + /** + * Sets the value for {@code foreignTransactionId}. + * + * @param foreignTransactionId Integrator-owned transaction reference. Optional. Forwarded to + * terminal-hub and can be used later to fetch the transaction via the [Transactions + * API](https://developer.sumup.com/api/transactions/get). + * @return This builder instance. + */ + public Builder foreignTransactionId(String foreignTransactionId) { + this.foreignTransactionId = foreignTransactionId; + return this; + } + + /** + * Sets the value for {@code key}. + * + * @param key Affiliate key generated in the [Affiliate + * Keys](https://developer.sumup.com/affiliate-keys) page. Required when the affiliate + * object is provided. Validated against Identity Admin when both `app_id` and `key` are + * present. + * @return This builder instance. + */ + public Builder key(String key) { + this.key = key; + return this; + } + + /** + * Sets the value for {@code tags}. + * + * @param tags Optional key-value metadata associated with the transaction. Forwarded to + * terminal-hub together with the payment. + * @return This builder instance. + */ + public Builder tags(java.util.Map tags) { + this.tags = tags; + return this; + } + + /** + * Builds an immutable CreateReaderCheckoutRequestAffiliate instance. + * + * @return Immutable CreateReaderCheckoutRequestAffiliate. + */ + public CreateReaderCheckoutRequestAffiliate build() { + return new CreateReaderCheckoutRequestAffiliate( + Objects.requireNonNull(appId, "appId"), + foreignTransactionId, + Objects.requireNonNull(key, "key"), + tags); + } + } +} diff --git a/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestCardType.java b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestCardType.java index f0af7d9..d1013c7 100644 --- a/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestCardType.java +++ b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestCardType.java @@ -6,7 +6,7 @@ import java.util.Objects; /** - * The card type of the card used for the transaction. Is is required only for some countries (e.g: + * The card type of the card used for the transaction. It is required only for some countries (e.g: * Brazil). */ public final class CreateReaderCheckoutRequestCardType { diff --git a/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestPaymentType.java b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestPaymentType.java new file mode 100644 index 0000000..620d3a9 --- /dev/null +++ b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutRequestPaymentType.java @@ -0,0 +1,61 @@ +// Code generated by sumup-java/codegen. DO NOT EDIT. +package com.sumup.sdk.models; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonValue; +import java.util.Objects; + +/** + * The payment method type for the transaction. Defaults to `card`. Use `pix` to initiate a Pix + * QR-code payment flow on the device. Pix is only supported for Brazilian merchants; other + * merchants will receive a 422 error. + */ +public final class CreateReaderCheckoutRequestPaymentType { + public static final CreateReaderCheckoutRequestPaymentType CARD = + new CreateReaderCheckoutRequestPaymentType("card"); + public static final CreateReaderCheckoutRequestPaymentType PIX = + new CreateReaderCheckoutRequestPaymentType("pix"); + + private final String value; + + private CreateReaderCheckoutRequestPaymentType(String value) { + this.value = Objects.requireNonNull(value, "value"); + } + + /** + * Creates a CreateReaderCheckoutRequestPaymentType for a value not yet known to this SDK version. + * + * @param value Wire value sent to or received from the API. + * @return Open enum value wrapping {@code value}. + */ + public static CreateReaderCheckoutRequestPaymentType of(String value) { + return new CreateReaderCheckoutRequestPaymentType(value); + } + + @JsonValue + public String getValue() { + return value; + } + + @Override + public String toString() { + return value; + } + + @JsonCreator + public static CreateReaderCheckoutRequestPaymentType fromValue(String value) { + return value == null ? null : new CreateReaderCheckoutRequestPaymentType(value); + } + + @Override + public boolean equals(Object other) { + return this == other + || (other instanceof CreateReaderCheckoutRequestPaymentType that + && this.value.equals(that.value)); + } + + @Override + public int hashCode() { + return value.hashCode(); + } +} diff --git a/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutResponseData.java b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutResponseData.java index 017b63a..a5e7633 100644 --- a/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutResponseData.java +++ b/src/main/java/com/sumup/sdk/models/CreateReaderCheckoutResponseData.java @@ -8,9 +8,11 @@ public record CreateReaderCheckoutResponseData( String checkoutId, /** - * The client transaction ID is a unique identifier for the transaction that is generated for - * the client. It can be used later to fetch the transaction details via the [Transactions - * API](https://developer.sumup.com/api/transactions/get). + * **SumUp API flow.** Unique identifier for this checkout-generated transaction. Pass this + * value as `terminal.client_id` when the reader creates the terminal so checkout metadata + * (including affiliate sent here) is merged into the payment. SDK clients do not use this field + * for affiliate metadata; they send affiliate in `terminal.affiliate` on `POST /api/terminals` + * instead. */ String clientTransactionId) { /** @@ -43,10 +45,11 @@ public Builder checkoutId(String checkoutId) { /** * Sets the value for {@code clientTransactionId}. * - * @param clientTransactionId The client transaction ID is a unique identifier for the - * transaction that is generated for the client. It can be used later to fetch the - * transaction details via the [Transactions - * API](https://developer.sumup.com/api/transactions/get). + * @param clientTransactionId **SumUp API flow.** Unique identifier for this checkout-generated + * transaction. Pass this value as `terminal.client_id` when the reader creates the terminal + * so checkout metadata (including affiliate sent here) is merged into the payment. SDK + * clients do not use this field for affiliate metadata; they send affiliate in + * `terminal.affiliate` on `POST /api/terminals` instead. * @return This builder instance. */ public Builder clientTransactionId(String clientTransactionId) { diff --git a/src/main/java/com/sumup/sdk/models/CustomerValidationError.java b/src/main/java/com/sumup/sdk/models/CustomerValidationError.java new file mode 100644 index 0000000..dd0c77a --- /dev/null +++ b/src/main/java/com/sumup/sdk/models/CustomerValidationError.java @@ -0,0 +1,78 @@ +// Code generated by sumup-java/codegen. DO NOT EDIT. +package com.sumup.sdk.models; + +import java.util.Objects; + +/** Details of a customer validation error. */ +public record CustomerValidationError( + /** Platform code for the error. */ + String errorCode, + + /** Short description of the error. */ + String errorMessage, + + /** Unique identifier of this error occurrence. */ + String instance) { + /** + * Creates a builder for CustomerValidationError. + * + * @return Builder that constructs immutable CustomerValidationError instances. + */ + public static Builder builder() { + return new Builder(); + } + + /** Builder for CustomerValidationError instances. */ + public static final class Builder { + private String errorCode; + private String errorMessage; + private String instance; + + private Builder() {} + + /** + * Sets the value for {@code errorCode}. + * + * @param errorCode Platform code for the error. + * @return This builder instance. + */ + public Builder errorCode(String errorCode) { + this.errorCode = errorCode; + return this; + } + + /** + * Sets the value for {@code errorMessage}. + * + * @param errorMessage Short description of the error. + * @return This builder instance. + */ + public Builder errorMessage(String errorMessage) { + this.errorMessage = errorMessage; + return this; + } + + /** + * Sets the value for {@code instance}. + * + * @param instance Unique identifier of this error occurrence. + * @return This builder instance. + */ + public Builder instance(String instance) { + this.instance = instance; + return this; + } + + /** + * Builds an immutable CustomerValidationError instance. + * + * @return Immutable CustomerValidationError. + */ + public CustomerValidationError build() { + return new CustomerValidationError( + Objects.requireNonNull(errorCode, "errorCode"), + Objects.requireNonNull(errorMessage, "errorMessage"), + Objects.requireNonNull(instance, "instance")); + } + } +} diff --git a/src/main/java/com/sumup/sdk/models/GetReaderCheckoutResponseData.java b/src/main/java/com/sumup/sdk/models/GetReaderCheckoutResponseData.java index 9cd8ac9..50e6c13 100644 --- a/src/main/java/com/sumup/sdk/models/GetReaderCheckoutResponseData.java +++ b/src/main/java/com/sumup/sdk/models/GetReaderCheckoutResponseData.java @@ -4,7 +4,7 @@ import java.util.Objects; public record GetReaderCheckoutResponseData( - /** Type of the card. Required for some countries */ + /** Type of the card, or null when no card type was specified. */ com.sumup.sdk.models.GetReaderCheckoutResponseDataCardType cardType, /** Unique identifier for the checkout */ @@ -81,7 +81,7 @@ private Builder() {} /** * Sets the value for {@code cardType}. * - * @param cardType Type of the card. Required for some countries + * @param cardType Type of the card, or null when no card type was specified. * @return This builder instance. */ public Builder cardType(com.sumup.sdk.models.GetReaderCheckoutResponseDataCardType cardType) { diff --git a/src/main/java/com/sumup/sdk/models/GetReaderCheckoutResponseDataCardType.java b/src/main/java/com/sumup/sdk/models/GetReaderCheckoutResponseDataCardType.java index 4a8eb01..fe07808 100644 --- a/src/main/java/com/sumup/sdk/models/GetReaderCheckoutResponseDataCardType.java +++ b/src/main/java/com/sumup/sdk/models/GetReaderCheckoutResponseDataCardType.java @@ -5,12 +5,14 @@ import com.fasterxml.jackson.annotation.JsonValue; import java.util.Objects; -/** Type of the card. Required for some countries */ +/** Type of the card, or null when no card type was specified. */ public final class GetReaderCheckoutResponseDataCardType { public static final GetReaderCheckoutResponseDataCardType CREDIT = new GetReaderCheckoutResponseDataCardType("credit"); public static final GetReaderCheckoutResponseDataCardType DEBIT = new GetReaderCheckoutResponseDataCardType("debit"); + public static final GetReaderCheckoutResponseDataCardType NULL = + new GetReaderCheckoutResponseDataCardType("null"); private final String value;