@sumup/sdk
Version:
The official TypeScript SDK for the SumUp API
407 lines • 13.3 kB
TypeScript
import * as Core from "../../core.js";
/**
* Details of the payment card.
*/
export type CardResponse = {
/**
* Last 4 digits of the payment card number.
*/
last_4_digits?: string;
/**
* Issuing card network of the payment card.
*/
type?: "AMEX" | "CUP" | "DINERS" | "DISCOVER" | "ELO" | "ELV" | "HIPERCARD" | "JCB" | "MAESTRO" | "MASTERCARD" | "VISA" | "VISA_ELECTRON" | "VISA_VPAY" | "UNKNOWN";
};
/**
* Three-letter [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) code of the currency for the amount. Currently supported currency values are enumerated above.
*/
export type Currency = "BGN" | "BRL" | "CHF" | "CLP" | "CZK" | "DKK" | "EUR" | "GBP" | "HRK" | "HUF" | "NOK" | "PLN" | "RON" | "SEK" | "USD";
/**
* Details of the transaction.
*/
export type TransactionMixinBase = {
/**
* Unique ID of the transaction.
*/
id?: string;
/**
* Transaction code returned by the acquirer/processing entity after processing the transaction.
*/
transaction_code?: string;
/**
* Total amount of the transaction.
*/
amount?: number;
currency?: Currency;
/**
* Date and time of the creation of the transaction. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.
*/
timestamp?: string;
/**
* Current status of the transaction.
*/
status?: "SUCCESSFUL" | "CANCELLED" | "FAILED" | "PENDING";
/**
* Payment type used for the transaction.
*/
payment_type?: "ECOM" | "RECURRING" | "BOLETO";
/**
* Current number of the installment for deferred payments.
*/
installments_count?: number;
};
export type TransactionMixinCheckout = {
/**
* Unique code of the registered merchant to whom the payment is made.
*/
merchant_code?: string;
/**
* Amount of the applicable VAT (out of the total transaction amount).
*/
vat_amount?: number;
/**
* Amount of the tip (out of the total transaction amount).
*/
tip_amount?: number;
/**
* Entry mode of the payment details.
*/
entry_mode?: "CUSTOMER_ENTRY" | "BOLETO";
/**
* Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
*/
auth_code?: string;
/**
* Internal unique ID of the transaction on the SumUp platform.
*/
internal_id?: number;
};
/**
* Unique ID of the transaction event.
*/
export type EventID = number;
/**
* Unique ID of the transaction.
*/
export type TransactionID = string;
/**
* Type of the transaction event.
*/
export type EventType = "PAYOUT" | "CHARGE_BACK" | "REFUND" | "PAYOUT_DEDUCTION";
/**
* Status of the transaction event.
*/
export type EventStatus = "PENDING" | "SCHEDULED" | "FAILED" | "REFUNDED" | "SUCCESSFUL" | "PAID_OUT";
/**
* Amount of the event.
*/
export type AmountEvent = number;
/**
* Date and time of the transaction event.
*/
export type TimestampEvent = string;
export type Event = {
id?: EventID;
transaction_id?: TransactionID;
type?: EventType;
status?: EventStatus;
amount?: AmountEvent;
timestamp?: TimestampEvent;
/**
* Amount of the fee related to the event.
*/
fee_amount?: number;
/**
* Consecutive number of the installment.
*/
installment_number?: number;
/**
* Amount deducted for the event.
*/
deducted_amount?: number;
/**
* Amount of the fee deducted for the event.
*/
deducted_fee_amount?: number;
};
/**
* Details of a link to a related resource.
*/
export type Link = {
/**
* Specifies the relation to the current resource.
*/
rel?: string;
/**
* URL for accessing the related resource.
*/
href?: string;
/**
* Specifies the media type of the related resource.
*/
type?: string;
};
/**
* Details of the product for which the payment is made.
*/
export type Product = {
/**
* Name of the product from the merchant's catalog.
*/
name?: string;
/**
* Price of the product without VAT.
*/
price?: number;
/**
* VAT rate applicable to the product.
*/
vat_rate?: number;
/**
* Amount of the VAT for a single product item (calculated as the product of `price` and `vat_rate`, i.e. `single_vat_amount = price * vat_rate`).
*/
single_vat_amount?: number;
/**
* Price of a single product item with VAT.
*/
price_with_vat?: number;
/**
* Total VAT amount for the purchase (calculated as the product of `single_vat_amount` and `quantity`, i.e. `vat_amount = single_vat_amount * quantity`).
*/
vat_amount?: number;
/**
* Number of product items for the purchase.
*/
quantity?: number;
/**
* Total price of the product items without VAT (calculated as the product of `price` and `quantity`, i.e. `total_price = price * quantity`).
*/
total_price?: number;
/**
* Total price of the product items including VAT (calculated as the product of `price_with_vat` and `quantity`, i.e. `total_with_vat = price_with_vat * quantity`).
*/
total_with_vat?: number;
};
/**
* Details of a transaction event.
*/
export type TransactionEvent = {
id?: EventID;
event_type?: EventType;
status?: EventStatus;
amount?: AmountEvent;
/**
* Date when the transaction event is due to occur.
*/
due_date?: string;
/**
* Date when the transaction event occurred.
*/
date?: string;
/**
* Consecutive number of the installment that is paid. Applicable only payout events, i.e. `event_type = PAYOUT`.
*/
installment_number?: number;
timestamp?: TimestampEvent;
};
export type TransactionMixinHistory = {
/**
* Short description of the payment. The value is taken from the `description` property of the related checkout resource.
*/
product_summary?: string;
/**
* Total number of payouts to the registered user specified in the `user` property.
*/
payouts_total?: number;
/**
* Number of payouts that are made to the registered user specified in the `user` property.
*/
payouts_received?: number;
/**
* Payout plan of the registered user at the time when the transaction was made.
*/
payout_plan?: "SINGLE_PAYMENT" | "TRUE_INSTALLMENT" | "ACCELERATED_INSTALLMENT";
};
export type TransactionHistory = TransactionMixinBase & TransactionMixinHistory & {
transaction_id?: TransactionID;
/**
* Client-specific ID of the transaction.
*/
client_transaction_id?: string;
/**
* Email address of the registered user (merchant) to whom the payment is made.
*/
user?: string;
/**
* Type of the transaction for the registered user specified in the `user` property.
*/
type?: "PAYMENT" | "REFUND" | "CHARGE_BACK";
/**
* Issuing card network of the payment card used for the transaction.
*/
card_type?: "VISA" | "AMEX" | "CUP" | "DINERS" | "DISCOVER" | "ELO" | "ELV" | "HIPERCARD" | "JCB" | "MAESTRO" | "MASTERCARD" | "VISA_ELECTRON" | "VISA_VPAY" | "UNKNOWN";
};
/**
* Latitude value from the coordinates of the payment location (as received from the payment terminal reader).
*/
export type Lat = number;
/**
* Longitude value from the coordinates of the payment location (as received from the payment terminal reader).
*/
export type Lon = number;
/**
* Indication of the precision of the geographical position received from the payment terminal.
*/
export type HorizontalAccuracy = number;
export type LinkRefund = Link & {
/**
* Minimum allowed amount for the refund.
*/
min_amount?: number;
/**
* Maximum allowed amount for the refund.
*/
max_amount?: number;
};
export type TransactionFull = TransactionMixinBase & TransactionMixinCheckout & TransactionMixinHistory & {
/**
* Email address of the registered user (merchant) to whom the payment is made.
*/
username?: string;
lat?: Lat;
lon?: Lon;
horizontal_accuracy?: HorizontalAccuracy;
/**
* Simple name of the payment type.
*/
simple_payment_type?: "MOTO" | "CASH" | "CC_SIGNATURE" | "ELV" | "CC_CUSTOMER_ENTERED" | "MANUAL_ENTRY" | "EMV";
/**
* Verification method used for the transaction.
*/
verification_method?: "none" | "signature" | "offline pin" | "online pin" | "offline pin + signature" | "confirmation code verified";
card?: CardResponse;
/**
* Local date and time of the creation of the transaction.
*/
local_time?: string;
/**
* Payout type for the transaction.
*/
payout_type?: "BANK_ACCOUNT" | "BALANCE" | "PREPAID_CARD";
/**
* List of products from the merchant's catalogue for which the transaction serves as a payment.
*/
products?: Product[];
/**
* List of VAT rates applicable to the transaction.
*/
vat_rates?: Record<string, unknown>[];
/**
* List of transaction events related to the transaction.
*/
transaction_events?: TransactionEvent[];
/**
* Status generated from the processing status and the latest transaction state.
*/
simple_status?: "SUCCESSFUL" | "PAID_OUT" | "CANCEL_FAILED" | "CANCELLED" | "CHARGEBACK" | "FAILED" | "REFUND_FAILED" | "REFUNDED" | "NON_COLLECTION";
/**
* List of hyperlinks for accessing related resources.
*/
links?: Record<string, unknown>[];
/**
* List of events related to the transaction.
*/
events?: Event[];
/**
* Details of the payment location as received from the payment terminal.
*/
location?: {
lat?: Lat;
lon?: Lon;
horizontal_accuracy?: HorizontalAccuracy;
};
/**
* Indicates whether tax deduction is enabled for the transaction.
*/
tax_enabled?: boolean;
};
export type RefundTransactionParams = {
/**
* Amount to be refunded. Eligible amount can't exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction.
*/
amount?: number;
};
export type GetTransactionV2_1QueryParams = {
id?: string;
internal_id?: string;
transaction_code?: string;
foreign_transaction_id?: string;
client_transaction_id?: string;
};
export type GetTransactionQueryParams = {
id?: string;
internal_id?: string;
transaction_code?: string;
};
export type ListTransactionsV2_1QueryParams = {
transaction_code?: string;
order?: "ascending" | "descending";
limit?: number;
users?: string[];
statuses?: ("SUCCESSFUL" | "CANCELLED" | "FAILED" | "REFUNDED" | "CHARGE_BACK")[];
payment_types?: ("CASH" | "POS" | "ECOM" | "BALANCE" | "MOTO" | "BOLETO" | "UNKNOWN")[];
types?: ("PAYMENT" | "REFUND" | "CHARGE_BACK")[];
changes_since?: string;
newest_time?: string;
newest_ref?: string;
oldest_time?: string;
oldest_ref?: string;
};
export type ListTransactionsV2_1Response = {
items?: TransactionHistory[];
links?: Link[];
};
export type ListTransactionsQueryParams = {
transaction_code?: string;
order?: "ascending" | "descending";
limit?: number;
users?: string[];
statuses?: ("SUCCESSFUL" | "CANCELLED" | "FAILED" | "REFUNDED" | "CHARGE_BACK")[];
payment_types?: ("CASH" | "POS" | "ECOM" | "BALANCE" | "MOTO" | "BOLETO" | "UNKNOWN")[];
types?: ("PAYMENT" | "REFUND" | "CHARGE_BACK")[];
changes_since?: string;
newest_time?: string;
newest_ref?: string;
oldest_time?: string;
oldest_ref?: string;
};
export type ListTransactionsResponse = {
items?: TransactionHistory[];
links?: Link[];
};
export declare class Transactions extends Core.APIResource {
/**
* Refund a transaction
*/
refund(txnId: string, body: RefundTransactionParams, params?: Core.FetchParams): Core.APIPromise<void>;
/**
* Retrieve a transaction
*/
get(merchantCode: string, query?: GetTransactionV2_1QueryParams, params?: Core.FetchParams): Core.APIPromise<TransactionFull>;
/**
* Retrieve a transaction
*/
getDeprecated(query?: GetTransactionQueryParams, params?: Core.FetchParams): Core.APIPromise<TransactionFull>;
/**
* List transactions
*/
list(merchantCode: string, query?: ListTransactionsV2_1QueryParams, params?: Core.FetchParams): Core.APIPromise<ListTransactionsV2_1Response>;
/**
* List transactions
*/
listDeprecated(query?: ListTransactionsQueryParams, params?: Core.FetchParams): Core.APIPromise<ListTransactionsResponse>;
}
export declare namespace Transactions {
export type { AmountEvent, CardResponse, Currency, Event, EventID, EventStatus, EventType, GetTransactionQueryParams, GetTransactionV2_1QueryParams, HorizontalAccuracy, Lat, Link, LinkRefund, ListTransactionsQueryParams, ListTransactionsV2_1QueryParams, Lon, Product, RefundTransactionParams, TimestampEvent, TransactionEvent, TransactionFull, TransactionHistory, TransactionID, TransactionMixinBase, TransactionMixinCheckout, TransactionMixinHistory, };
}
//# sourceMappingURL=index.d.ts.map