diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index bc21dce..b006054 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -11,6 +11,8 @@ import "github.com/sumup/sumup-go" - [Variables](<#variables>) - [type Address](<#Address>) - [type AddressLegacy](<#AddressLegacy>) +- [type Affiliate](<#Affiliate>) +- [type Amount](<#Amount>) - [type Attributes](<#Attributes>) - [type BadRequest](<#BadRequest>) - [func \(e \*BadRequest\) Error\(\) string](<#BadRequest.Error>) @@ -125,6 +127,12 @@ import "github.com/sumup/sumup-go" - [type FinancialPayoutStatus](<#FinancialPayoutStatus>) - [type FinancialPayoutType](<#FinancialPayoutType>) - [type FinancialPayouts](<#FinancialPayouts>) +- [type GetReaderCheckoutResponse](<#GetReaderCheckoutResponse>) +- [type GetReaderCheckoutResponseData](<#GetReaderCheckoutResponseData>) +- [type GetReaderCheckoutResponseDataCardType](<#GetReaderCheckoutResponseDataCardType>) +- [type GetReaderCheckoutResponseDataPaymentType](<#GetReaderCheckoutResponseDataPaymentType>) +- [type GetReaderCheckoutResponseDataStatus](<#GetReaderCheckoutResponseDataStatus>) +- [type GetReaderCheckoutResponseDataTotalAmount](<#GetReaderCheckoutResponseDataTotalAmount>) - [type HorizontalAccuracy](<#HorizontalAccuracy>) - [type HostedCheckout](<#HostedCheckout>) - [type Invite](<#Invite>) @@ -212,18 +220,25 @@ import "github.com/sumup/sumup-go" - [type ReaderID](<#ReaderID>) - [type ReaderName](<#ReaderName>) - [type ReaderPairingCode](<#ReaderPairingCode>) +- [type ReaderPaymentRequestParams](<#ReaderPaymentRequestParams>) +- [type ReaderPaymentResponse](<#ReaderPaymentResponse>) +- [type ReaderPaymentResponseData](<#ReaderPaymentResponseData>) - [type ReaderStatus](<#ReaderStatus>) - [type ReadersClient](<#ReadersClient>) - [func NewReadersClient\(c \*client.Client\) \*ReadersClient](<#NewReadersClient>) - [func \(c \*ReadersClient\) Create\(ctx context.Context, merchantCode string, body ReadersCreateParams\) \(\*Reader, error\)](<#ReadersClient.Create>) - [func \(c \*ReadersClient\) CreateCheckout\(ctx context.Context, merchantCode string, readerID string, body ReadersCreateCheckoutParams\) \(\*CreateReaderCheckoutResponse, error\)](<#ReadersClient.CreateCheckout>) + - [func \(c \*ReadersClient\) CreateGoCheckout\(ctx context.Context, merchantCode string, readerID ReaderID, body ReadersCreateGoCheckoutParams, params ReadersCreateGoCheckoutParams\) \(\*ReaderPaymentResponse, error\)](<#ReadersClient.CreateGoCheckout>) - [func \(c \*ReadersClient\) Delete\(ctx context.Context, merchantCode string, readerID ReaderID\) error](<#ReadersClient.Delete>) - [func \(c \*ReadersClient\) Get\(ctx context.Context, merchantCode string, readerID ReaderID, params ReadersGetParams\) \(\*Reader, error\)](<#ReadersClient.Get>) + - [func \(c \*ReadersClient\) GetCheckout\(ctx context.Context, merchantCode string, readerID string, checkoutID string\) \(\*GetReaderCheckoutResponse, error\)](<#ReadersClient.GetCheckout>) - [func \(c \*ReadersClient\) GetStatus\(ctx context.Context, merchantCode string, readerID string\) \(\*StatusResponse, error\)](<#ReadersClient.GetStatus>) - [func \(c \*ReadersClient\) List\(ctx context.Context, merchantCode string\) \(\*ReadersListResponse, error\)](<#ReadersClient.List>) - [func \(c \*ReadersClient\) TerminateCheckout\(ctx context.Context, merchantCode string, readerID string\) error](<#ReadersClient.TerminateCheckout>) - [func \(c \*ReadersClient\) Update\(ctx context.Context, merchantCode string, readerID ReaderID, body ReadersUpdateParams\) \(\*Reader, error\)](<#ReadersClient.Update>) - [type ReadersCreateCheckoutParams](<#ReadersCreateCheckoutParams>) +- [type ReadersCreateGoCheckoutParams](<#ReadersCreateGoCheckoutParams>) + - [func \(p \*ReadersCreateGoCheckoutParams\) QueryValues\(\) url.Values](<#ReadersCreateGoCheckoutParams.QueryValues>) - [type ReadersCreateParams](<#ReadersCreateParams>) - [type ReadersGetParams](<#ReadersGetParams>) - [func \(p \*ReadersGetParams\) QueryValues\(\) url.Values](<#ReadersGetParams.QueryValues>) @@ -430,6 +445,32 @@ type AddressLegacy struct { } ``` + +## type [Affiliate]() + +Affiliate is a schema definition. + +```go +type Affiliate struct { + AppID string `json:"app_id"` + Key string `json:"key"` +} +``` + + +## type [Amount]() + +Amount is a schema definition. + +```go +type Amount struct { + // Currency ISO 4217 code + Currency string `json:"currency"` + // Amount in minor units (e.g. cents). + Value int `json:"value"` +} +``` + ## type [Attributes]() @@ -440,7 +481,7 @@ type Attributes map[string]any ``` -## type [BadRequest]() +## type [BadRequest]() 400 Bad Request @@ -451,7 +492,7 @@ type BadRequest struct { ``` -### func \(\*BadRequest\) [Error]() +### func \(\*BadRequest\) [Error]() ```go func (e *BadRequest) Error() string @@ -460,7 +501,7 @@ func (e *BadRequest) Error() string -## type [BadRequestErrors]() +## type [BadRequestErrors]() BadRequestErrors is a schema definition. @@ -474,7 +515,7 @@ type BadRequestErrors struct { ``` -## type [BadRequestErrorsType]() +## type [BadRequestErrorsType]() Key indicating type of error @@ -1641,7 +1682,7 @@ type CountryCode string ``` -## type [CreateCheckoutRequest]() +## type [CreateCheckoutRequest]() Reader Checkout @@ -1696,7 +1737,7 @@ type CreateCheckoutRequest struct { ``` -## type [CreateCheckoutRequestAADE]() +## type [CreateCheckoutRequestAADE]() Optional object containing data for transactions from ERP integrators in Greece that comply with the AADE 1155 protocol. When such regulatory/business requirements apply, this object must be provided and contains the data needed to validate the transaction with the AADE signature provider. @@ -1712,7 +1753,7 @@ type CreateCheckoutRequestAADE struct { ``` -## type [CreateCheckoutRequestAffiliate]() +## type [CreateCheckoutRequestAffiliate]() Affiliate metadata for the transaction. It is a field that allow for integrators to track the source of the transaction. @@ -1735,7 +1776,7 @@ type CreateCheckoutRequestAffiliate struct { ``` -## type [CreateCheckoutRequestAffiliateTags]() +## type [CreateCheckoutRequestAffiliateTags]() Additional metadata for the transaction. It is key\-value object that can be associated with the transaction. @@ -1744,7 +1785,7 @@ type CreateCheckoutRequestAffiliateTags map[string]any ``` -## type [CreateCheckoutRequestCardType]() +## type [CreateCheckoutRequestCardType]() The card type of the card used for the transaction. Is is required only for some countries \(e.g: Brazil\). @@ -1762,7 +1803,7 @@ const ( ``` -## type [CreateCheckoutRequestTotalAmount]() +## type [CreateCheckoutRequestTotalAmount]() Amount structure. @@ -1786,7 +1827,7 @@ type CreateCheckoutRequestTotalAmount struct { ``` -## type [CreateReaderCheckoutError]() +## type [CreateReaderCheckoutError]() Error description @@ -1797,7 +1838,7 @@ type CreateReaderCheckoutError struct { ``` -### func \(\*CreateReaderCheckoutError\) [Error]() +### func \(\*CreateReaderCheckoutError\) [Error]() ```go func (e *CreateReaderCheckoutError) Error() string @@ -1806,7 +1847,7 @@ func (e *CreateReaderCheckoutError) Error() string -## type [CreateReaderCheckoutErrorErrors]() +## type [CreateReaderCheckoutErrorErrors]() CreateReaderCheckoutErrorErrors is a schema definition. @@ -1820,7 +1861,7 @@ type CreateReaderCheckoutErrorErrors struct { ``` -## type [CreateReaderCheckoutResponse]() +## type [CreateReaderCheckoutResponse]() CreateReaderCheckoutResponse is a schema definition. @@ -1831,12 +1872,14 @@ type CreateReaderCheckoutResponse struct { ``` -## type [CreateReaderCheckoutResponseData]() +## type [CreateReaderCheckoutResponseData]() CreateReaderCheckoutResponseData is a schema definition. ```go type CreateReaderCheckoutResponseData struct { + // The checkout ID is a unique identifier for the checkout. + CheckoutID *string `json:"checkout_id,omitempty"` // 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). @@ -1845,7 +1888,7 @@ type CreateReaderCheckoutResponseData struct { ``` -## type [CreateReaderCheckoutUnprocessableEntity]() +## type [CreateReaderCheckoutUnprocessableEntity]() Unprocessable entity @@ -1856,7 +1899,7 @@ type CreateReaderCheckoutUnprocessableEntity struct { ``` -### func \(\*CreateReaderCheckoutUnprocessableEntity\) [Error]() +### func \(\*CreateReaderCheckoutUnprocessableEntity\) [Error]() ```go func (e *CreateReaderCheckoutUnprocessableEntity) Error() string @@ -1865,7 +1908,7 @@ func (e *CreateReaderCheckoutUnprocessableEntity) Error() string -## type [CreateReaderCheckoutUnprocessableEntityErrors]() +## type [CreateReaderCheckoutUnprocessableEntityErrors]() CreateReaderCheckoutUnprocessableEntityErrors is a schema definition. @@ -1874,7 +1917,7 @@ type CreateReaderCheckoutUnprocessableEntityErrors map[string]any ``` -## type [CreateReaderTerminateError]() +## type [CreateReaderTerminateError]() Error description @@ -1885,7 +1928,7 @@ type CreateReaderTerminateError struct { ``` -### func \(\*CreateReaderTerminateError\) [Error]() +### func \(\*CreateReaderTerminateError\) [Error]() ```go func (e *CreateReaderTerminateError) Error() string @@ -1894,7 +1937,7 @@ func (e *CreateReaderTerminateError) Error() string -## type [CreateReaderTerminateErrorErrors]() +## type [CreateReaderTerminateErrorErrors]() CreateReaderTerminateErrorErrors is a schema definition. @@ -1908,7 +1951,7 @@ type CreateReaderTerminateErrorErrors struct { ``` -## type [CreateReaderTerminateUnprocessableEntity]() +## type [CreateReaderTerminateUnprocessableEntity]() Unprocessable entity @@ -1919,7 +1962,7 @@ type CreateReaderTerminateUnprocessableEntity struct { ``` -### func \(\*CreateReaderTerminateUnprocessableEntity\) [Error]() +### func \(\*CreateReaderTerminateUnprocessableEntity\) [Error]() ```go func (e *CreateReaderTerminateUnprocessableEntity) Error() string @@ -1928,7 +1971,7 @@ func (e *CreateReaderTerminateUnprocessableEntity) Error() string -## type [CreateReaderTerminateUnprocessableEntityErrors]() +## type [CreateReaderTerminateUnprocessableEntityErrors]() CreateReaderTerminateUnprocessableEntityErrors is a schema definition. @@ -2424,6 +2467,140 @@ Ordered list of payout and payout\-deduction records. type FinancialPayouts []FinancialPayout ``` + +## type [GetReaderCheckoutResponse]() + +GetReaderCheckoutResponse is a schema definition. + +```go +type GetReaderCheckoutResponse struct { + Data GetReaderCheckoutResponseData `json:"data"` +} +``` + + +## type [GetReaderCheckoutResponseData]() + +GetReaderCheckoutResponseData is a schema definition. + +```go +type GetReaderCheckoutResponseData struct { + // Type of the card. Required for some countries + CardType nullable.Field[GetReaderCheckoutResponseDataCardType] `json:"card_type"` + // Unique identifier for the checkout + // Format: uuid + CheckoutID string `json:"checkout_id"` + // Client transaction identifier associated with the checkout + ClientTransactionID string `json:"client_transaction_id"` + // Checkout creation timestamp + CreatedAt time.Time `json:"created_at"` + // Number of installments for the transaction. Required for some countries. + Installments nullable.Field[int] `json:"installments"` + // Payment failure reason + PaymentFailureReason *nullable.Field[string] `json:"payment_failure_reason,omitempty"` + // Payment status from payments v2 event + PaymentStatus nullable.Field[string] `json:"payment_status"` + // Type of the payment. Required for some countries + PaymentType GetReaderCheckoutResponseDataPaymentType `json:"payment_type"` + // Reader firmware version + ReaderFirmwareVersion string `json:"reader_firmware_version"` + // Device serial number + ReaderSerialNumber string `json:"reader_serial_number"` + // Current status of the checkout + Status GetReaderCheckoutResponseDataStatus `json:"status"` + // Amount structure. + // + // The amount is represented as an integer value altogether with the currency and the minor unit. + // + // For example, EUR 1.00 is represented as value 100 with minor unit of 2. + TotalAmount GetReaderCheckoutResponseDataTotalAmount `json:"total_amount"` + // Checkout last update timestamp + UpdatedAt time.Time `json:"updated_at"` + // Checkout expiration timestamp. After this time, the checkout will be automatically cancelled. + ValidUntil nullable.Field[time.Time] `json:"valid_until"` +} +``` + + +## type [GetReaderCheckoutResponseDataCardType]() + +Type of the card. Required for some countries + +```go +type GetReaderCheckoutResponseDataCardType string +``` + + + +```go +const ( + GetReaderCheckoutResponseDataCardTypeCredit GetReaderCheckoutResponseDataCardType = "credit" + GetReaderCheckoutResponseDataCardTypeDebit GetReaderCheckoutResponseDataCardType = "debit" +) +``` + + +## type [GetReaderCheckoutResponseDataPaymentType]() + +Type of the payment. Required for some countries + +```go +type GetReaderCheckoutResponseDataPaymentType string +``` + + + +```go +const ( + GetReaderCheckoutResponseDataPaymentTypeCard GetReaderCheckoutResponseDataPaymentType = "card" + GetReaderCheckoutResponseDataPaymentTypePix GetReaderCheckoutResponseDataPaymentType = "pix" +) +``` + + +## type [GetReaderCheckoutResponseDataStatus]() + +Current status of the checkout + +```go +type GetReaderCheckoutResponseDataStatus string +``` + + + +```go +const ( + GetReaderCheckoutResponseDataStatusCancelled GetReaderCheckoutResponseDataStatus = "cancelled" + GetReaderCheckoutResponseDataStatusFailed GetReaderCheckoutResponseDataStatus = "failed" + GetReaderCheckoutResponseDataStatusPending GetReaderCheckoutResponseDataStatus = "pending" + GetReaderCheckoutResponseDataStatusSuccessful GetReaderCheckoutResponseDataStatus = "successful" +) +``` + + +## type [GetReaderCheckoutResponseDataTotalAmount]() + +Amount structure. + +The amount is represented as an integer value altogether with the currency and the minor unit. + +For example, EUR 1.00 is represented as value 100 with minor unit of 2. + +```go +type GetReaderCheckoutResponseDataTotalAmount struct { + // Currency ISO 4217 code + Currency string `json:"currency"` + // The minor units of the currency. + // It represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit + // is 0. + // Min: 0 + MinorUnit int `json:"minor_unit"` + // Integer value of the amount. + // Min: 0 + Value int `json:"value"` +} +``` + ## type [HorizontalAccuracy]() @@ -3255,7 +3432,7 @@ type Metadata map[string]any ``` -## type [NotFound]() +## type [NotFound]() 404 Not Found @@ -3266,7 +3443,7 @@ type NotFound struct { ``` -### func \(\*NotFound\) [Error]() +### func \(\*NotFound\) [Error]() ```go func (e *NotFound) Error() string @@ -3275,7 +3452,7 @@ func (e *NotFound) Error() string -## type [NotFoundErrors]() +## type [NotFoundErrors]() NotFoundErrors is a schema definition. @@ -3825,7 +4002,7 @@ type Product struct { ``` -## type [Reader]() +## type [Reader]() A physical card reader device that can accept in\-person payments. @@ -3835,11 +4012,7 @@ type Reader struct { CreatedAt time.Time `json:"created_at"` // Information about the underlying physical device. Device ReaderDevice `json:"device"` - // Unique identifier of the object. - // - // Note that this identifies the instance of the physical devices pairing with your SumUp account. If you [delete](https://developer.sumup.com/api/readers/delete-reader) - // a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device. - // + // Unique identifier of the reader that the payment is initiated on. // Min length: 30 // Max length: 30 ID ReaderID `json:"id"` @@ -3870,7 +4043,7 @@ type Reader struct { ``` -## type [ReaderDevice]() +## type [ReaderDevice]() Information about the underlying physical device. @@ -3884,7 +4057,7 @@ type ReaderDevice struct { ``` -## type [ReaderDeviceModel]() +## type [ReaderDeviceModel]() Identifier of the model of the device. @@ -3902,20 +4075,16 @@ const ( ``` -## type [ReaderID]() +## type [ReaderID]() -Unique identifier of the object. - -Note that this identifies the instance of the physical devices pairing with your SumUp account. If you \[delete\]\(https://developer.sumup.com/api/readers/delete-reader\) a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device. - -Min length: 30 Max length: 30 +Unique identifier of the reader that the payment is initiated on. Min length: 30 Max length: 30 ```go type ReaderID string ``` -## type [ReaderName]() +## type [ReaderName]() Custom human\-readable, user\-defined name for easier identification of the reader. Max length: 500 @@ -3924,7 +4093,7 @@ type ReaderName string ``` -## type [ReaderPairingCode]() +## type [ReaderPairingCode]() The pairing code is a 8 or 9 character alphanumeric string that is displayed on a SumUp Device after initiating the pairing. It is used to link the physical device to the created pairing. Min length: 8 Max length: 9 @@ -3932,8 +4101,49 @@ The pairing code is a 8 or 9 character alphanumeric string that is displayed on type ReaderPairingCode string ``` + +## type [ReaderPaymentRequestParams]() + +ReaderPaymentRequestParams is a schema definition. + +```go +type ReaderPaymentRequestParams struct { + Affiliate *Affiliate `json:"affiliate,omitempty"` + // Caller-supplied correlation identifier, used as the idempotency key. + ClientTransactionID string `json:"client_transaction_id"` + // Optional tip amount in minor units, added on top of total_amount. + TipAmount *int `json:"tip_amount,omitempty"` + TotalAmount Amount `json:"total_amount"` +} +``` + + +## type [ReaderPaymentResponse]() + +ReaderPaymentResponse is a schema definition. + +```go +type ReaderPaymentResponse struct { + Data *ReaderPaymentResponseData `json:"data,omitempty"` +} +``` + + +## type [ReaderPaymentResponseData]() + +ReaderPaymentResponseData is a schema definition. + +```go +type ReaderPaymentResponseData struct { + // Caller-supplied correlation identifier that was provided in the request. + ClientTransactionID *string `json:"client_transaction_id,omitempty"` + // Transaction code returned by the acquirer/processing entity after processing the transaction. + TransactionCode *string `json:"transaction_code,omitempty"` +} +``` + -## type [ReaderStatus]() +## type [ReaderStatus]() The status of the reader object gives information about the current state of the reader. @@ -3957,12 +4167,10 @@ const ( ``` -## type [ReadersClient]() +## type [ReadersClient]() ReadersClient provides access to the Readers API. -A reader represents a device that accepts payments. You can use the SumUp Solo to accept in\-person payments. - ```go type ReadersClient struct { // contains filtered or unexported fields @@ -3970,7 +4178,7 @@ type ReadersClient struct { ``` -### func [NewReadersClient]() +### func [NewReadersClient]() ```go func NewReadersClient(c *client.Client) *ReadersClient @@ -3979,7 +4187,7 @@ func NewReadersClient(c *client.Client) *ReadersClient -### func \(\*ReadersClient\) [Create]() +### func \(\*ReadersClient\) [Create]() ```go func (c *ReadersClient) Create(ctx context.Context, merchantCode string, body ReadersCreateParams) (*Reader, error) @@ -3988,7 +4196,7 @@ func (c *ReadersClient) Create(ctx context.Context, merchantCode string, body Re Create a new Reader for the merchant account. -### func \(\*ReadersClient\) [CreateCheckout]() +### func \(\*ReadersClient\) [CreateCheckout]() ```go func (c *ReadersClient) CreateCheckout(ctx context.Context, merchantCode string, readerID string, body ReadersCreateCheckoutParams) (*CreateReaderCheckoutResponse, error) @@ -4002,8 +4210,19 @@ There are some caveats when using this endpoint: \* The target device must be on \*\*Note\*\*: If the target device is a Solo, it must be in version 3.3.24.3 or higher. + +### func \(\*ReadersClient\) [CreateGoCheckout]() + +```go +func (c *ReadersClient) CreateGoCheckout(ctx context.Context, merchantCode string, readerID ReaderID, body ReadersCreateGoCheckoutParams, params ReadersCreateGoCheckoutParams) (*ReaderPaymentResponse, error) +``` + +Initiates a payment on the SumUp Go terminal identified by the reader ID. + +Use \`client\_transaction\_id\` as an idempotency key: retrying the request with the same value returns the result of the original payment instead of creating a duplicate. + -### func \(\*ReadersClient\) [Delete]() +### func \(\*ReadersClient\) [Delete]() ```go func (c *ReadersClient) Delete(ctx context.Context, merchantCode string, readerID ReaderID) error @@ -4012,7 +4231,7 @@ func (c *ReadersClient) Delete(ctx context.Context, merchantCode string, readerI Delete a reader. -### func \(\*ReadersClient\) [Get]() +### func \(\*ReadersClient\) [Get]() ```go func (c *ReadersClient) Get(ctx context.Context, merchantCode string, readerID ReaderID, params ReadersGetParams) (*Reader, error) @@ -4020,8 +4239,17 @@ func (c *ReadersClient) Get(ctx context.Context, merchantCode string, readerID R Retrieve a Reader. + +### func \(\*ReadersClient\) [GetCheckout]() + +```go +func (c *ReadersClient) GetCheckout(ctx context.Context, merchantCode string, readerID string, checkoutID string) (*GetReaderCheckoutResponse, error) +``` + +Get a Checkout for a Reader. + -### func \(\*ReadersClient\) [GetStatus]() +### func \(\*ReadersClient\) [GetStatus]() ```go func (c *ReadersClient) GetStatus(ctx context.Context, merchantCode string, readerID string) (*StatusResponse, error) @@ -4042,7 +4270,7 @@ This endpoint allows you to retrieve updates from the connected card reader, inc \*\*Note\*\*: If the target device is a Solo, it must be in version 3.3.39.0 or higher. -### func \(\*ReadersClient\) [List]() +### func \(\*ReadersClient\) [List]() ```go func (c *ReadersClient) List(ctx context.Context, merchantCode string) (*ReadersListResponse, error) @@ -4051,7 +4279,7 @@ func (c *ReadersClient) List(ctx context.Context, merchantCode string) (*Readers List all readers of the merchant. -### func \(\*ReadersClient\) [TerminateCheckout]() +### func \(\*ReadersClient\) [TerminateCheckout]() ```go func (c *ReadersClient) TerminateCheckout(ctx context.Context, merchantCode string, readerID string) error @@ -4068,7 +4296,7 @@ If a transaction is successfully terminated and \`return\_url\` was provided on \*\*Note\*\*: If the target device is a Solo, it must be in version 3.3.28.0 or higher. -### func \(\*ReadersClient\) [Update]() +### func \(\*ReadersClient\) [Update]() ```go func (c *ReadersClient) Update(ctx context.Context, merchantCode string, readerID ReaderID, body ReadersUpdateParams) (*Reader, error) @@ -4077,7 +4305,7 @@ func (c *ReadersClient) Update(ctx context.Context, merchantCode string, readerI Update a Reader. -## type [ReadersCreateCheckoutParams]() +## type [ReadersCreateCheckoutParams]() @@ -4085,8 +4313,29 @@ Update a Reader. type ReadersCreateCheckoutParams = CreateCheckoutRequest ``` + +## type [ReadersCreateGoCheckoutParams]() + +ReadersCreateGoCheckoutParams are query parameters for CreateGoReaderCheckout. + +```go +type ReadersCreateGoCheckoutParams struct { + // Access token in the format 'Bearer {token}'. + Authorization string +} +``` + + +### func \(\*ReadersCreateGoCheckoutParams\) [QueryValues]() + +```go +func (p *ReadersCreateGoCheckoutParams) QueryValues() url.Values +``` + +QueryValues converts [ReadersCreateGoCheckoutParams](<#ReadersCreateGoCheckoutParams>) into \[url.Values\]. + -## type [ReadersCreateParams]() +## type [ReadersCreateParams]() ReadersCreateParams is a schema definition. @@ -4108,7 +4357,7 @@ type ReadersCreateParams struct { ``` -## type [ReadersGetParams]() +## type [ReadersGetParams]() ReadersGetParams are query parameters for GetReader. @@ -4126,7 +4375,7 @@ type ReadersGetParams struct { ``` -### func \(\*ReadersGetParams\) [QueryValues]() +### func \(\*ReadersGetParams\) [QueryValues]() ```go func (p *ReadersGetParams) QueryValues() url.Values @@ -4135,7 +4384,7 @@ func (p *ReadersGetParams) QueryValues() url.Values QueryValues converts [ReadersGetParams](<#ReadersGetParams>) into \[url.Values\]. -## type [ReadersListResponse]() +## type [ReadersListResponse]() ReadersListResponse is a schema definition. @@ -4146,7 +4395,7 @@ type ReadersListResponse struct { ``` -## type [ReadersUpdateParams]() +## type [ReadersUpdateParams]() ReadersUpdateParams is a schema definition. @@ -4648,7 +4897,7 @@ type RolesUpdateParams struct { ``` -## type [StatusResponse]() +## type [StatusResponse]() Status of a device @@ -4659,7 +4908,7 @@ type StatusResponse struct { ``` -## type [StatusResponseData]() +## type [StatusResponseData]() StatusResponseData is a schema definition. @@ -4685,7 +4934,7 @@ type StatusResponseData struct { ``` -## type [StatusResponseDataConnectionType]() +## type [StatusResponseDataConnectionType]() Type of connection used by the device @@ -4708,7 +4957,7 @@ const ( ``` -## type [StatusResponseDataState]() +## type [StatusResponseDataState]() Latest state of the device @@ -4730,7 +4979,7 @@ const ( ``` -## type [StatusResponseDataStatus]() +## type [StatusResponseDataStatus]() Status of a device @@ -5805,7 +6054,7 @@ type TransactionsRefundResponse json.RawMessage ``` -## type [Unauthorized]() +## type [Unauthorized]() 401 Unauthorized @@ -5816,7 +6065,7 @@ type Unauthorized struct { ``` -### func \(\*Unauthorized\) [Error]() +### func \(\*Unauthorized\) [Error]() ```go func (e *Unauthorized) Error() string @@ -5825,7 +6074,7 @@ func (e *Unauthorized) Error() string -## type [UnauthorizedErrors]() +## type [UnauthorizedErrors]() UnauthorizedErrors is a schema definition. @@ -5840,7 +6089,7 @@ type UnauthorizedErrors struct { ``` -## type [UnauthorizedErrorsType]() +## type [UnauthorizedErrorsType]() Key indicating type of error. Present only for typed 401 responses \(e.g. invalid token, invalid password\). Absent for generic unauthorized responses. @@ -6186,7 +6435,7 @@ const APIVersion = "1.0.0" ```go -const Version = "0.17.1" // x-release-please-version +const Version = "0.17.2" // x-release-please-version ``` # nullable diff --git a/openapi.json b/openapi.json index de333ee..04f9652 100755 --- a/openapi.json +++ b/openapi.json @@ -3030,6 +3030,171 @@ ] } }, + "/v0/merchants/{merchant_code}/readers/{reader_id}/go-checkout": { + "post": { + "operationId": "CreateGoReaderCheckout", + "summary": "Create a Go Reader Payment", + "description": "Initiates a payment on the SumUp Go terminal identified by the reader ID.\n\nUse `client_transaction_id` as an idempotency key: retrying the request with the same value returns the result of the original payment instead of creating a duplicate.", + "parameters": [ + { + "name": "Authorization", + "in": "header", + "description": "Access token in the format 'Bearer {token}'.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "merchant_code", + "in": "path", + "description": "Short unique identifier for the merchant.", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } + }, + { + "name": "reader_id", + "in": "path", + "description": "The unique identifier of the reader.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReaderID" + } + } + ], + "requestBody": { + "description": "Payment details to initiate on the reader.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReaderPaymentRequestParams" + } + } + } + }, + "responses": { + "200": { + "description": "Returns the result of the payment initiated on the reader.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReaderPaymentResponse" + } + } + } + }, + "400": { + "description": "The request is invalid.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://developer.sumup.com/problem/bad-request", + "title": "Bad Request", + "status": 400, + "detail": "Request validation failed." + } + } + } + }, + "401": { + "description": "Authentication failed or missing required scope.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://developer.sumup.com/problem/unauthorized", + "title": "Unauthorized", + "status": 401, + "detail": "Authentication credentials are missing or invalid." + } + } + } + }, + "404": { + "description": "The requested Reader resource does not exist.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://developer.sumup.com/problem/not-found", + "title": "Requested resource couldn't be found.", + "status": 404, + "detail": "The requested resource doesn't exist or does not belong to you." + } + } + } + }, + "422": { + "description": "The request could not be processed as it violates a business rule.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://developer.sumup.com/problem/validation-error", + "title": "Unprocessable Entity", + "status": 422, + "detail": "Validation failed." + } + } + } + }, + "500": { + "description": "An unexpected error occurred while processing the request.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://developer.sumup.com/problem/internal-server-error", + "title": "Internal Server Error", + "status": 500, + "detail": "An unexpected error occurred while processing the request." + } + } + } + } + }, + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "payments", + "readers.write" + ] + } + ], + "tags": [ + "Readers" + ], + "x-codegen": { + "method_name": "create_go_checkout", + "ignore": true + }, + "x-permissions": [ + "readers_checkout_create" + ], + "x-scopes": [ + "payments", + "readers.write" + ] + } + }, "/v0.1/memberships": { "get": { "operationId": "ListMemberships", @@ -5711,6 +5876,122 @@ "readers.write" ] } + }, + "/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout/{checkout_id}": { + "get": { + "operationId": "GetReaderCheckout", + "summary": "Get a Reader Checkout", + "description": "Get a Checkout for a Reader.\n", + "parameters": [ + { + "name": "merchant_code", + "in": "path", + "description": "Merchant Code", + "required": true, + "schema": { + "type": "string" + }, + "example": "MC0X0ABC" + }, + { + "name": "reader_id", + "in": "path", + "description": "The unique identifier of the Reader", + "required": true, + "schema": { + "type": "string" + }, + "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65" + }, + { + "name": "checkout_id", + "in": "path", + "description": "The unique identifier of the Checkout", + "required": true, + "schema": { + "type": "string" + }, + "example": "74ecff66-1655-43ed-8ce3-193f49fa602f" + } + ], + "responses": { + "200": { + "description": "The Checkout got successfully retrieved for the given reader.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetReaderCheckoutResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateReaderCheckoutError" + } + }, + "application/problem+json": { + "example": { + "detail": "Unauthorized", + "status": 401, + "title": "Unauthorized", + "type": "https://developer.sumup.com/problem/unauthorized" + }, + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "404": { + "description": "Response when given reader or checkout is not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + }, + "application/problem+json": { + "example": { + "detail": "The requested resource doesn't exist or does not belong to you.", + "status": 404, + "title": "Requested resource couldn't be found.", + "type": "https://developer.sumup.com/problem/not-found" + }, + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + } + }, + "callbacks": {}, + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "readers.read" + ] + } + ], + "tags": [ + "Readers" + ], + "x-codegen": { + "method_name": "get_checkout" + }, + "x-permissions": [ + "readers_checkout_view" + ], + "x-scopes": [ + "readers.read" + ] + } } }, "components": { @@ -8066,6 +8347,97 @@ "type": "string", "title": "Transaction ID" }, + "Affiliate": { + "type": "object", + "properties": { + "app_id": { + "type": "string", + "example": "com.example.app" + }, + "key": { + "type": "string", + "example": "123e4567-e89b-12d3-a456-426614174000" + } + }, + "required": [ + "app_id", + "key" + ] + }, + "Amount": { + "type": "object", + "properties": { + "currency": { + "description": "Currency ISO 4217 code", + "type": "string", + "example": "MXN" + }, + "value": { + "description": "Amount in minor units (e.g. cents).", + "type": "integer", + "example": 1000 + } + }, + "required": [ + "currency", + "value" + ] + }, + "ReaderID": { + "description": "Unique identifier of the reader that the payment is initiated on.", + "type": "string", + "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", + "maxLength": 30, + "minLength": 30 + }, + "ReaderPaymentRequestParams": { + "type": "object", + "properties": { + "affiliate": { + "$ref": "#/components/schemas/Affiliate" + }, + "client_transaction_id": { + "description": "Caller-supplied correlation identifier, used as the idempotency key.", + "type": "string", + "example": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f" + }, + "tip_amount": { + "description": "Optional tip amount in minor units, added on top of total_amount.", + "type": "integer", + "example": 100 + }, + "total_amount": { + "$ref": "#/components/schemas/Amount" + } + }, + "required": [ + "total_amount", + "client_transaction_id" + ] + }, + "ReaderPaymentResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ReaderPaymentResponseData" + } + } + }, + "ReaderPaymentResponseData": { + "type": "object", + "properties": { + "client_transaction_id": { + "description": "Caller-supplied correlation identifier that was provided in the request.", + "type": "string", + "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + }, + "transaction_code": { + "description": "Transaction code returned by the acquirer/processing entity after processing the transaction.", + "type": "string", + "example": "TEENSK4W2K" + } + } + }, "MembershipStatus": { "description": "The status of the membership.", "type": "string", @@ -9246,13 +9618,6 @@ ], "title": "Reader" }, - "ReaderID": { - "description": "Unique identifier of the object.\n\nNote that this identifies the instance of the physical devices pairing with your SumUp account. If you [delete](https://developer.sumup.com/api/readers/delete-reader) a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.", - "type": "string", - "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", - "maxLength": 30, - "minLength": 30 - }, "ReaderName": { "description": "Custom human-readable, user-defined name for easier identification of the reader.", "type": "string", @@ -9393,6 +9758,165 @@ ], "title": "CreateReaderCheckoutError" }, + "GetReaderCheckoutResponse": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "card_type": { + "description": "Type of the card. Required for some countries", + "type": "string", + "enum": [ + "credit", + "debit" + ], + "nullable": true + }, + "checkout_id": { + "description": "Unique identifier for the checkout", + "type": "string", + "format": "uuid" + }, + "client_transaction_id": { + "description": "Client transaction identifier associated with the checkout", + "type": "string" + }, + "created_at": { + "description": "Checkout creation timestamp", + "type": "string", + "format": "date-time" + }, + "installments": { + "description": "Number of installments for the transaction. Required for some countries.", + "type": "integer", + "nullable": true + }, + "payment_failure_reason": { + "description": "Payment failure reason", + "type": "string", + "nullable": true + }, + "payment_status": { + "description": "Payment status from payments v2 event", + "type": "string", + "nullable": true + }, + "payment_type": { + "description": "Type of the payment. Required for some countries", + "type": "string", + "enum": [ + "card", + "pix" + ] + }, + "reader_firmware_version": { + "description": "Reader firmware version", + "type": "string" + }, + "reader_serial_number": { + "description": "Device serial number", + "type": "string" + }, + "status": { + "description": "Current status of the checkout", + "type": "string", + "enum": [ + "pending", + "successful", + "failed", + "cancelled" + ] + }, + "total_amount": { + "description": "Amount structure.\n\nThe amount is represented as an integer value altogether with the currency and the minor unit.\n\nFor example, EUR 1.00 is represented as value 100 with minor unit of 2.\n", + "type": "object", + "example": { + "currency": "EUR", + "minor_unit": 2, + "value": 1000 + }, + "properties": { + "currency": { + "description": "Currency ISO 4217 code", + "type": "string", + "example": "EUR" + }, + "minor_unit": { + "description": "The minor units of the currency.\nIt represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0.\n", + "type": "integer", + "example": 2, + "minimum": 0 + }, + "value": { + "description": "Integer value of the amount.", + "type": "integer", + "example": 1000, + "minimum": 0 + } + }, + "required": [ + "currency", + "minor_unit", + "value" + ], + "title": "Money" + }, + "updated_at": { + "description": "Checkout last update timestamp", + "type": "string", + "format": "date-time" + }, + "valid_until": { + "description": "Checkout expiration timestamp. After this time, the checkout will be automatically cancelled.", + "type": "string", + "format": "date-time", + "nullable": true + } + }, + "required": [ + "checkout_id", + "client_transaction_id", + "reader_serial_number", + "payment_type", + "card_type", + "reader_firmware_version", + "installments", + "payment_status", + "valid_until", + "created_at", + "updated_at", + "status", + "total_amount" + ] + } + }, + "example": { + "data": { + "card_type": "credit", + "checkout_id": "00e33a36-c99b-4cb2-b635-b90c1455c9c8", + "client_transaction_id": "00e33a36-c99b-4cb2-b635-b90c1455c9c8", + "created_at": "2026-07-07T20:41:16.315434Z", + "installments": 1, + "payment_status": "pending", + "payment_type": "card", + "reader_firmware_version": "3.3.3.21", + "reader_serial_number": "1234567890", + "status": "pending", + "total_amount": { + "currency": "EUR", + "minor_unit": 2, + "value": 10000 + }, + "updated_at": "2026-07-07T20:42:18.117244Z", + "valid_until": "2026-07-07T20:41:16.315434Z" + } + }, + "required": [ + "data" + ], + "title": "GetReaderCheckoutResponse" + }, "StatusResponse": { "description": "Status of a device", "type": "object", @@ -9577,6 +10101,11 @@ "data": { "type": "object", "properties": { + "checkout_id": { + "description": "The checkout ID is a unique identifier for the checkout.\n", + "type": "string", + "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + }, "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", "type": "string", @@ -9590,6 +10119,7 @@ }, "example": { "data": { + "checkout_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "client_transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, @@ -10676,6 +11206,70 @@ } } }, + "BadRequest": { + "description": "The request is invalid.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://developer.sumup.com/problem/bad-request", + "title": "Bad Request", + "status": 400, + "detail": "Request validation failed." + } + } + } + }, + "Unauthorized": { + "description": "Authentication failed or missing required scope.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://developer.sumup.com/problem/unauthorized", + "title": "Unauthorized", + "status": 401, + "detail": "Authentication credentials are missing or invalid." + } + } + } + }, + "NotFound": { + "description": "The requested Reader resource does not exist.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://developer.sumup.com/problem/not-found", + "title": "Requested resource couldn't be found.", + "status": 404, + "detail": "The requested resource doesn't exist or does not belong to you." + } + } + } + }, + "InternalError": { + "description": "An unexpected error occurred while processing the request.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + }, + "example": { + "type": "https://developer.sumup.com/problem/internal-server-error", + "title": "Internal Server Error", + "status": 500, + "detail": "An unexpected error occurred while processing the request." + } + } + } + }, "ListMemberships": { "description": "Returns a list of Membership objects.", "content": { @@ -10848,6 +11442,9 @@ } ] }, + { + "name": "Readers" + }, { "name": "Members", "description": "Endpoints to manage account members. Members are users that have membership within merchant accounts.", @@ -10886,15 +11483,6 @@ "$ref": "#/components/schemas/Merchant" } ] - }, - { - "name": "Readers", - "description": "A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments.", - "x-core-objects": [ - { - "$ref": "#/components/schemas/Reader" - } - ] } ] -} +} \ No newline at end of file diff --git a/readers.go b/readers.go index 3a03aa2..e05f3f5 100755 --- a/readers.go +++ b/readers.go @@ -14,6 +14,20 @@ import ( "github.com/sumup/sumup-go/nullable" ) +// Affiliate is a schema definition. +type Affiliate struct { + AppID string `json:"app_id"` + Key string `json:"key"` +} + +// Amount is a schema definition. +type Amount struct { + // Currency ISO 4217 code + Currency string `json:"currency"` + // Amount in minor units (e.g. cents). + Value int `json:"value"` +} + // 400 Bad Request type BadRequest struct { Errors BadRequestErrors `json:"errors"` @@ -180,6 +194,8 @@ type CreateReaderCheckoutResponse struct { // CreateReaderCheckoutResponseData is a schema definition. type CreateReaderCheckoutResponseData struct { + // The checkout ID is a unique identifier for the checkout. + CheckoutID *string `json:"checkout_id,omitempty"` // 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). @@ -233,6 +249,92 @@ func (e *CreateReaderTerminateUnprocessableEntity) Error() string { var _ error = (*CreateReaderTerminateUnprocessableEntity)(nil) +// GetReaderCheckoutResponse is a schema definition. +type GetReaderCheckoutResponse struct { + Data GetReaderCheckoutResponseData `json:"data"` +} + +// GetReaderCheckoutResponseData is a schema definition. +type GetReaderCheckoutResponseData struct { + // Type of the card. Required for some countries + CardType nullable.Field[GetReaderCheckoutResponseDataCardType] `json:"card_type"` + // Unique identifier for the checkout + // Format: uuid + CheckoutID string `json:"checkout_id"` + // Client transaction identifier associated with the checkout + ClientTransactionID string `json:"client_transaction_id"` + // Checkout creation timestamp + CreatedAt time.Time `json:"created_at"` + // Number of installments for the transaction. Required for some countries. + Installments nullable.Field[int] `json:"installments"` + // Payment failure reason + PaymentFailureReason *nullable.Field[string] `json:"payment_failure_reason,omitempty"` + // Payment status from payments v2 event + PaymentStatus nullable.Field[string] `json:"payment_status"` + // Type of the payment. Required for some countries + PaymentType GetReaderCheckoutResponseDataPaymentType `json:"payment_type"` + // Reader firmware version + ReaderFirmwareVersion string `json:"reader_firmware_version"` + // Device serial number + ReaderSerialNumber string `json:"reader_serial_number"` + // Current status of the checkout + Status GetReaderCheckoutResponseDataStatus `json:"status"` + // Amount structure. + // + // The amount is represented as an integer value altogether with the currency and the minor unit. + // + // For example, EUR 1.00 is represented as value 100 with minor unit of 2. + TotalAmount GetReaderCheckoutResponseDataTotalAmount `json:"total_amount"` + // Checkout last update timestamp + UpdatedAt time.Time `json:"updated_at"` + // Checkout expiration timestamp. After this time, the checkout will be automatically cancelled. + ValidUntil nullable.Field[time.Time] `json:"valid_until"` +} + +// Type of the card. Required for some countries +type GetReaderCheckoutResponseDataCardType string + +const ( + GetReaderCheckoutResponseDataCardTypeCredit GetReaderCheckoutResponseDataCardType = "credit" + GetReaderCheckoutResponseDataCardTypeDebit GetReaderCheckoutResponseDataCardType = "debit" +) + +// Type of the payment. Required for some countries +type GetReaderCheckoutResponseDataPaymentType string + +const ( + GetReaderCheckoutResponseDataPaymentTypeCard GetReaderCheckoutResponseDataPaymentType = "card" + GetReaderCheckoutResponseDataPaymentTypePix GetReaderCheckoutResponseDataPaymentType = "pix" +) + +// Current status of the checkout +type GetReaderCheckoutResponseDataStatus string + +const ( + GetReaderCheckoutResponseDataStatusCancelled GetReaderCheckoutResponseDataStatus = "cancelled" + GetReaderCheckoutResponseDataStatusFailed GetReaderCheckoutResponseDataStatus = "failed" + GetReaderCheckoutResponseDataStatusPending GetReaderCheckoutResponseDataStatus = "pending" + GetReaderCheckoutResponseDataStatusSuccessful GetReaderCheckoutResponseDataStatus = "successful" +) + +// Amount structure. +// +// The amount is represented as an integer value altogether with the currency and the minor unit. +// +// For example, EUR 1.00 is represented as value 100 with minor unit of 2. +type GetReaderCheckoutResponseDataTotalAmount struct { + // Currency ISO 4217 code + Currency string `json:"currency"` + // The minor units of the currency. + // It represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit + // is 0. + // Min: 0 + MinorUnit int `json:"minor_unit"` + // Integer value of the amount. + // Min: 0 + Value int `json:"value"` +} + // 404 Not Found type NotFound struct { Errors NotFoundErrors `json:"errors"` @@ -256,11 +358,7 @@ type Reader struct { CreatedAt time.Time `json:"created_at"` // Information about the underlying physical device. Device ReaderDevice `json:"device"` - // Unique identifier of the object. - // - // Note that this identifies the instance of the physical devices pairing with your SumUp account. If you [delete](https://developer.sumup.com/api/readers/delete-reader) - // a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device. - // + // Unique identifier of the reader that the payment is initiated on. // Min length: 30 // Max length: 30 ID ReaderID `json:"id"` @@ -305,11 +403,7 @@ const ( ReaderDeviceModelVirtualSolo ReaderDeviceModel = "virtual-solo" ) -// Unique identifier of the object. -// -// Note that this identifies the instance of the physical devices pairing with your SumUp account. If you [delete](https://developer.sumup.com/api/readers/delete-reader) -// a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device. -// +// Unique identifier of the reader that the payment is initiated on. // Min length: 30 // Max length: 30 type ReaderID string @@ -324,6 +418,29 @@ type ReaderName string // Max length: 9 type ReaderPairingCode string +// ReaderPaymentRequestParams is a schema definition. +type ReaderPaymentRequestParams struct { + Affiliate *Affiliate `json:"affiliate,omitempty"` + // Caller-supplied correlation identifier, used as the idempotency key. + ClientTransactionID string `json:"client_transaction_id"` + // Optional tip amount in minor units, added on top of total_amount. + TipAmount *int `json:"tip_amount,omitempty"` + TotalAmount Amount `json:"total_amount"` +} + +// ReaderPaymentResponse is a schema definition. +type ReaderPaymentResponse struct { + Data *ReaderPaymentResponseData `json:"data,omitempty"` +} + +// ReaderPaymentResponseData is a schema definition. +type ReaderPaymentResponseData struct { + // Caller-supplied correlation identifier that was provided in the request. + ClientTransactionID *string `json:"client_transaction_id,omitempty"` + // Transaction code returned by the acquirer/processing entity after processing the transaction. + TransactionCode *string `json:"transaction_code,omitempty"` +} + // The status of the reader object gives information about the current state of the reader. // // Possible values: @@ -444,6 +561,8 @@ type ReadersCreateParams struct { PairingCode ReaderPairingCode `json:"pairing_code"` } +type ReadersCreateGoCheckoutParams = ReaderPaymentRequestParams + type ReadersCreateCheckoutParams = CreateCheckoutRequest // ReadersUpdateParams is a schema definition. @@ -457,6 +576,21 @@ type ReadersUpdateParams struct { Name *ReaderName `json:"name,omitempty"` } +// ReadersCreateGoCheckoutParams are query parameters for CreateGoReaderCheckout. +type ReadersCreateGoCheckoutParams struct { + // Access token in the format 'Bearer {token}'. + Authorization string +} + +// QueryValues converts [ReadersCreateGoCheckoutParams] into [url.Values]. +func (p *ReadersCreateGoCheckoutParams) QueryValues() url.Values { + q := make(url.Values) + + q.Set("Authorization", p.Authorization) + + return q +} + // ReadersGetParams are query parameters for GetReader. type ReadersGetParams struct { // Return the reader only if it has been modified after the specified timestamp given in the headers. @@ -486,8 +620,6 @@ type ReadersListResponse struct { } // ReadersClient provides access to the Readers API. -// -// A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments. type ReadersClient struct { c *client.Client } @@ -574,6 +706,69 @@ func (c *ReadersClient) Create(ctx context.Context, merchantCode string, body Re } } +// Initiates a payment on the SumUp Go terminal identified by the reader ID. +// +// Use `client_transaction_id` as an idempotency key: retrying the request with the same value returns the result +// of the original payment instead of creating a duplicate. +func (c *ReadersClient) CreateGoCheckout(ctx context.Context, merchantCode string, readerID ReaderID, body ReadersCreateGoCheckoutParams, params ReadersCreateGoCheckoutParams) (*ReaderPaymentResponse, error) { + path := fmt.Sprintf("/v0/merchants/%v/readers/%v/go-checkout", merchantCode, readerID) + + resp, err := c.c.Call(ctx, http.MethodPost, path, client.WithJSONBody(body), client.WithQueryValues(params.QueryValues())) + if err != nil { + return nil, fmt.Errorf("call %s %s: %w", http.MethodPost, path, err) + } + defer func() { + _ = resp.Body.Close() + }() + + switch resp.StatusCode { + case http.StatusOK: + var v ReaderPaymentResponse + if err := json.NewDecoder(resp.Body).Decode(&v); err != nil { + return nil, fmt.Errorf("decode response: %s", err.Error()) + } + + return &v, nil + case http.StatusBadRequest: + var apiErr Problem + if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil { + return nil, fmt.Errorf("read error response: %s", err.Error()) + } + + return nil, &apiErr + case http.StatusUnauthorized: + var apiErr Problem + if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil { + return nil, fmt.Errorf("read error response: %s", err.Error()) + } + + return nil, &apiErr + case http.StatusNotFound: + var apiErr Problem + if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil { + return nil, fmt.Errorf("read error response: %s", err.Error()) + } + + return nil, &apiErr + case http.StatusUnprocessableEntity: + var apiErr Problem + if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil { + return nil, fmt.Errorf("read error response: %s", err.Error()) + } + + return nil, &apiErr + case http.StatusInternalServerError: + var apiErr Problem + if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil { + return nil, fmt.Errorf("read error response: %s", err.Error()) + } + + return nil, &apiErr + default: + return nil, fmt.Errorf("unexpected response %d: %s", resp.StatusCode, http.StatusText(resp.StatusCode)) + } +} + // Terminate a Reader Checkout stops the current transaction on the target device. // // This process is asynchronous and the actual termination may take some time to be performed on the device. @@ -859,3 +1054,42 @@ func (c *ReadersClient) Update(ctx context.Context, merchantCode string, readerI return nil, fmt.Errorf("unexpected response %d: %s", resp.StatusCode, http.StatusText(resp.StatusCode)) } } + +// Get a Checkout for a Reader. +func (c *ReadersClient) GetCheckout(ctx context.Context, merchantCode string, readerID string, checkoutID string) (*GetReaderCheckoutResponse, error) { + path := fmt.Sprintf("/v0.1/merchants/%v/readers/%v/checkout/%v", merchantCode, readerID, checkoutID) + + resp, err := c.c.Call(ctx, http.MethodGet, path) + if err != nil { + return nil, fmt.Errorf("call %s %s: %w", http.MethodGet, path, err) + } + defer func() { + _ = resp.Body.Close() + }() + + switch resp.StatusCode { + case http.StatusOK: + var v GetReaderCheckoutResponse + if err := json.NewDecoder(resp.Body).Decode(&v); err != nil { + return nil, fmt.Errorf("decode response: %s", err.Error()) + } + + return &v, nil + case http.StatusUnauthorized: + var apiErr Problem + if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil { + return nil, fmt.Errorf("read error response: %s", err.Error()) + } + + return nil, &apiErr + case http.StatusNotFound: + var apiErr Problem + if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil { + return nil, fmt.Errorf("read error response: %s", err.Error()) + } + + return nil, &apiErr + default: + return nil, fmt.Errorf("unexpected response %d: %s", resp.StatusCode, http.StatusText(resp.StatusCode)) + } +}