@sumup/sdk
Version:
The official TypeScript SDK for the SumUp API
475 lines • 14.7 kB
TypeScript
import * as Core from "../../core";
/**
* A RFC 9457 problem details object.
*
* Additional properties specific to the problem type may be present.
*
*/
export type Problem = {
/**
* A URI reference that identifies the problem type.
*/
type: string;
/**
* A short, human-readable summary of the problem type.
*/
title?: string;
/**
* The HTTP status code generated by the origin server for this occurrence of the problem.
*/
status?: number;
/**
* A human-readable explanation specific to this occurrence of the problem.
*/
detail?: string;
/**
* A URI reference that identifies the specific occurrence of the problem.
*/
instance?: string;
};
/**
* Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.
*/
export type Metadata = Record<string, unknown>;
/**
* 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.
*/
export type ReaderID = string;
/**
* Custom human-readable, user-defined name for easier identification of the reader.
*/
export type ReaderName = string;
/**
* The status of the reader object gives information about the current state of the reader.
*
* Possible values:
*
* - `unknown` - The reader status is unknown.
* - `processing` - The reader is created and waits for the physical device to confirm the pairing.
* - `paired` - The reader is paired with a merchant account and can be used with SumUp APIs.
* - `expired` - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
*/
export type ReaderStatus = "unknown" | "processing" | "paired" | "expired";
/**
* Information about the underlying physical device.
*/
export type ReaderDevice = {
/**
* A unique identifier of the physical device (e.g. serial number).
*/
identifier: string;
/**
* Identifier of the model of the device.
*/
model: "solo" | "virtual-solo";
};
/**
* Reader
*
* A physical card reader device that can accept in-person payments.
*/
export type Reader = {
id: ReaderID;
name: ReaderName;
status: ReaderStatus;
device: ReaderDevice;
metadata?: Metadata;
/**
* The timestamp of when the reader was created.
*/
created_at: string;
/**
* The timestamp of when the reader was last updated.
*/
updated_at: string;
};
/**
* 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.
*/
export type ReaderPairingCode = string;
/**
* CreateReaderCheckoutUnprocessableEntity
*
* Unprocessable entity
*/
export type CreateReaderCheckoutUnprocessableEntity = {
errors: Record<string, unknown>;
};
/**
* CreateReaderCheckoutError
*
* Error description
*/
export type CreateReaderCheckoutError = {
errors: {
/**
* Error message
*/
detail?: string;
};
};
/**
* StatusResponse
*
* Status of a device
*/
export type StatusResponse = {
data: {
/**
* Battery level percentage
*/
battery_level?: Record<string, unknown>;
/**
* Battery temperature in Celsius
*/
battery_temperature?: number;
/**
* Type of connection used by the device
*/
connection_type?: "btle" | "edge" | "gprs" | "lte" | "umts" | "usb" | "Wi-Fi";
/**
* Firmware version of the device
*/
firmware_version?: string;
/**
* Timestamp of the last activity from the device
*/
last_activity?: string;
/**
* Latest state of the device
*/
state?: "IDLE" | "SELECTING_TIP" | "WAITING_FOR_CARD" | "WAITING_FOR_PIN" | "WAITING_FOR_SIGNATURE" | "UPDATING_FIRMWARE";
/**
* Status of a device
*/
status: "ONLINE" | "OFFLINE";
};
};
/**
* CreateReaderTerminateUnprocessableEntity
*
* Unprocessable entity
*/
export type CreateReaderTerminateUnprocessableEntity = {
errors: Record<string, unknown>;
};
/**
* BadGateway
*
* 502 Bad Gateway
*/
export type BadGateway = {
errors: {
/**
* Fuller message giving context to error
*/
detail: string;
};
};
/**
* CreateReaderTerminateError
*
* Error description
*/
export type CreateReaderTerminateError = {
errors: {
/**
* Error message
*/
detail?: string;
};
};
/**
* BadRequest
*
* 400 Bad Request
*/
export type BadRequest = {
errors: {
/**
* Fuller message giving context to error
*/
detail?: string;
/**
* Key indicating type of error
*/
type: "INVALID_BEARER_TOKEN" | "INVALID_USER_AGENT" | "NOT_ENOUGH_UNPAID_PAYOUTS" | "DUPLICATE_HEADERS";
};
};
/**
* CreateReaderCheckoutResponse
*/
export type CreateReaderCheckoutResponse = {
data: {
/**
* 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).
*
*/
client_transaction_id: string;
};
};
/**
* GatewayTimeout
*
* 504 Gateway Timeout
*/
export type GatewayTimeout = {
errors: {
/**
* Fuller message giving context to error
*/
detail: string;
};
};
/**
* Unauthorized
*
* 401 Unauthorized
*/
export type Unauthorized = {
errors: {
/**
* Fuller message giving context to error
*/
detail?: string;
/**
* Key indicating type of error
*/
type: "INVALID_ACCESS_TOKEN" | "INVALID_PASSWORD";
};
};
/**
* InternalServerError
*
* 500 Internal Server Error
*/
export type InternalServerError = {
errors: {
/**
* Fuller message giving context to error
*/
detail: string;
};
};
/**
* CreateReaderCheckoutRequest
*
* Reader Checkout
*/
export type CreateReaderCheckoutRequest = {
/**
* Affiliate
*
* Affiliate metadata for the transaction.
* It is a field that allow for integrators to track the source of the transaction.
*
*/
affiliate?: {
/**
* 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.
*
*/
app_id: string;
/**
* 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).
*
*/
foreign_transaction_id: string;
/**
* 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.
*
*/
key: string;
/**
* Additional metadata for the transaction.
* It is key-value object that can be associated with the transaction.
*
*/
tags?: Record<string, unknown>;
} | null;
/**
* The card type of the card used for the transaction.
* Is is required only for some countries (e.g: Brazil).
*
*/
card_type?: "credit" | "debit";
/**
* Description of the checkout to be shown in the Merchant Sales
*/
description?: string;
/**
* 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.
*
*/
installments?: number | null;
/**
* Webhook URL to which the payment result will be sent.
* It must be a HTTPS url.
*
*/
return_url?: string;
/**
* 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.
*
*/
tip_rates?: number[];
/**
* Time in seconds the cardholder has to select a tip rate.
* If not provided, the default value is 30 seconds.
*
* It can only be set if `tip_rates` is provided.
*
* **Note**: If the target device is a Solo, it must be in version 3.3.38.0 or higher.
*
*/
tip_timeout?: number;
/**
* Money
*
* 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.
*
*/
total_amount: {
/**
* Currency ISO 4217 code
*/
currency: string;
/**
* 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.
*
*/
minor_unit: number;
/**
* Integer value of the amount.
*/
value: number;
};
};
/**
* NotFound
*
* 404 Not Found
*/
export type NotFound = {
errors: {
/**
* Fuller message giving context to error
*/
detail: string;
};
};
export type ListReadersResponse = {
items: Reader[];
};
export type CreateReaderParams = {
pairing_code: ReaderPairingCode;
name: ReaderName;
metadata?: Metadata;
};
export type UpdateReaderParams = {
name?: ReaderName;
metadata?: Metadata;
};
export type CreateReaderTerminateParams = Record<string, unknown>;
export declare class Readers extends Core.APIResource {
/**
* List all readers of the merchant.
*/
list(merchantCode: string, params?: Core.FetchParams): Core.APIPromise<ListReadersResponse>;
/**
* Create a new Reader for the merchant account.
*/
create(merchantCode: string, body: CreateReaderParams, params?: Core.FetchParams): Core.APIPromise<Reader>;
/**
* Retrieve a Reader.
*/
get(merchantCode: string, id: ReaderID, params?: Core.FetchParams): Core.APIPromise<Reader>;
/**
* Delete a reader.
*/
delete(merchantCode: string, id: ReaderID, params?: Core.FetchParams): Core.APIPromise<void>;
/**
* Update a Reader.
*/
update(merchantCode: string, id: ReaderID, body: UpdateReaderParams, params?: Core.FetchParams): Core.APIPromise<Reader>;
/**
* Creates a Checkout for a Reader.
*
* This process is asynchronous and the actual transaction may take some time to be stared on the device.
*
*
* There are some caveats when using this endpoint:
* * 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.
*
*/
createCheckout(merchantCode: string, readerId: string, body: CreateReaderCheckoutRequest, params?: Core.FetchParams): Core.APIPromise<CreateReaderCheckoutResponse>;
/**
* Provides the last known status for a Reader.
*
* This endpoint allows you to retrieve updates from the connected card reader, including the current screen being displayed during the payment process and the device status (battery level, connectivity, and update state).
*
* Supported States
*
* * `IDLE` – Reader ready for next transaction
* * `SELECTING_TIP` – Waiting for tip input
* * `WAITING_FOR_CARD` – Awaiting card insert/tap
* * `WAITING_FOR_PIN` – Waiting for PIN entry
* * `WAITING_FOR_SIGNATURE` – Waiting for customer signature
* * `UPDATING_FIRMWARE` – Firmware update in progress
*
* Device Status
*
* * `ONLINE` – Device connected and operational
* * `OFFLINE` – Device disconnected (last state persisted)
*
* **Note**: If the target device is a Solo, it must be in version 3.3.39.0 or higher.
*
*/
getStatus(merchantCode: string, readerId: string, params?: Core.FetchParams): Core.APIPromise<StatusResponse>;
/**
* 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.
*
*
* There are some caveats when using this endpoint:
* * The target device must be online, otherwise terminate won't be accepted
* * The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc.
* * There is no confirmation of the termination.
*
* If a transaction is successfully terminated and `return_url` was provided on Checkout, the transaction status will be sent as `failed` to the provided URL.
*
*
* **Note**: If the target device is a Solo, it must be in version 3.3.28.0 or higher.
*
*/
terminateCheckout(merchantCode: string, readerId: string, body?: CreateReaderTerminateParams, params?: Core.FetchParams): Core.APIPromise<void>;
}
export declare namespace Readers {
export type { BadGateway, BadRequest, CreateReaderCheckoutError, CreateReaderCheckoutRequest, CreateReaderCheckoutResponse, CreateReaderCheckoutUnprocessableEntity, CreateReaderParams, CreateReaderTerminateError, CreateReaderTerminateParams, CreateReaderTerminateUnprocessableEntity, GatewayTimeout, InternalServerError, Metadata, NotFound, Problem, Reader, ReaderDevice, ReaderID, ReaderName, ReaderPairingCode, ReaderStatus, StatusResponse, Unauthorized, UpdateReaderParams, };
}
//# sourceMappingURL=index.d.ts.map