@sumup/sdk
Version:
The official TypeScript SDK for the SumUp API
532 lines • 16.2 kB
TypeScript
import * as Core from "../../core.js";
/**
* Profile's personal address information.
*/
export type Address = {
/**
* City name from the address.
*/
city?: string;
/**
* Two letter country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
*/
country?: string;
/**
* First line of the address with details of the street name and number.
*/
line_1?: string;
/**
* Second line of the address with details of the building, unit, apartment, and floor numbers.
*/
line_2?: string;
/**
* Postal code from the address.
*/
postal_code?: string;
/**
* State name or abbreviation from the address.
*/
state?: string;
};
/**
* __Required when payment type is `card`.__ Details of the payment card.
*/
export type Card = {
/**
* Name of the cardholder as it appears on the payment card.
*/
name: string;
/**
* Number of the payment card (without spaces).
*/
number: string;
/**
* Year from the expiration time of the payment card. Accepted formats are `YY` and `YYYY`.
*/
expiry_year: string;
/**
* Month from the expiration time of the payment card. Accepted format is `MM`.
*/
expiry_month: "01" | "02" | "03" | "04" | "05" | "06" | "07" | "08" | "09" | "10" | "11" | "12";
/**
* Three or four-digit card verification value (security code) of the payment card.
*/
cvv: string;
/**
* Required five-digit ZIP code. Applicable only to merchant users in the USA.
*/
zip_code?: string;
/**
* 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";
/**
* Created mandate
*/
export type MandateResponse = {
/**
* Indicates the mandate type
*/
type?: string;
/**
* Mandate status
*/
status?: string;
/**
* Merchant code which has the mandate
*/
merchant_code?: string;
};
/**
* 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;
};
/**
* Checkout
*
* Details of the payment checkout.
*/
export type Checkout = {
/**
* Unique ID of the payment checkout specified by the client application when creating the checkout resource.
*/
checkout_reference?: string;
/**
* Amount of the payment.
*/
amount?: number;
currency?: Currency;
/**
* Unique identifying code of the merchant profile.
*/
merchant_code?: string;
/**
* Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
*/
description?: string;
/**
* URL to which the SumUp platform sends the processing status of the payment checkout.
*/
return_url?: string;
/**
* Unique ID of the checkout resource.
*/
id?: string;
/**
* Current status of the checkout.
*/
status?: "PENDING" | "FAILED" | "PAID";
/**
* Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.
*/
date?: string;
/**
* Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
*/
valid_until?: string | null;
/**
* Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
*/
customer_id?: string;
mandate?: MandateResponse;
/**
* List of transactions related to the payment.
*/
transactions?: (TransactionMixinBase & TransactionMixinCheckout)[];
};
/**
* Details of the payment checkout.
*/
export type CheckoutCreateRequest = {
/**
* Unique ID of the payment checkout specified by the client application when creating the checkout resource.
*/
checkout_reference: string;
/**
* Amount of the payment.
*/
amount: number;
currency: Currency;
/**
* Unique identifying code of the merchant profile.
*/
merchant_code: string;
/**
* Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
*/
description?: string;
/**
* URL to which the SumUp platform sends the processing status of the payment checkout.
*/
return_url?: string;
/**
* Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
*/
customer_id?: string;
/**
* Purpose of the checkout.
*/
purpose?: "CHECKOUT" | "SETUP_RECURRING_PAYMENT";
/**
* Unique ID of the checkout resource.
*/
id?: string;
/**
* Current status of the checkout.
*/
status?: "PENDING" | "FAILED" | "PAID";
/**
* Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.
*/
date?: string;
/**
* Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
*/
valid_until?: string | null;
/**
* List of transactions related to the payment.
*/
transactions?: (TransactionMixinBase & TransactionMixinCheckout)[];
/**
* __Required__ for [APMs](https://developer.sumup.com/online-payments/apm/introduction) and __recommended__ for card payments. Refers to a url where the end user is redirected once the payment processing completes. If not specified, the [Payment Widget](https://developer.sumup.com/online-payments/tools/card-widget) renders [3DS challenge](https://developer.sumup.com/online-payments/features/3ds) within an iframe instead of performing a full-page redirect.
*/
redirect_url?: string;
};
/**
* Mandate is passed when a card is to be tokenized
*/
export type MandatePayload = {
/**
* Indicates the mandate type
*/
type: "recurrent";
/**
* Operating system and web client used by the end-user
*/
user_agent: string;
/**
* IP address of the end user. Supports IPv4 and IPv6
*/
user_ip?: string;
};
/**
* Personal details for the customer.
*/
export type PersonalDetails = {
/**
* First name of the customer.
*/
first_name?: string;
/**
* Last name of the customer.
*/
last_name?: string;
/**
* Email address of the customer.
*/
email?: string;
/**
* Phone number of the customer.
*/
phone?: string;
/**
* Date of birth of the customer.
*/
birth_date?: string;
/**
* An identification number user for tax purposes (e.g. CPF)
*/
tax_id?: string;
address?: Address;
};
/**
* Details of the payment instrument for processing the checkout.
*/
export type CheckoutProcessMixin = {
/**
* Describes the payment method used to attempt processing
*/
payment_type: "card" | "boleto" | "ideal" | "blik" | "bancontact";
/**
* Number of installments for deferred payments. Available only to merchant users in Brazil.
*/
installments?: number;
mandate?: MandatePayload;
card?: Card;
/**
* __Required when using a tokenized card to process a checkout.__ Unique token identifying the saved payment card for a customer.
*/
token?: string;
/**
* __Required when `token` is provided.__ Unique ID of the customer.
*/
customer_id?: string;
personal_details?: PersonalDetails;
};
export type CheckoutSuccess = Checkout & {
/**
* Transaction code of the successful transaction with which the payment for the checkout is completed.
*/
transaction_code?: string;
/**
* Transaction ID of the successful transaction with which the payment for the checkout is completed.
*/
transaction_id?: string;
/**
* Name of the merchant
*/
merchant_name?: string;
/**
* Refers to a url where the end user is redirected once the payment processing completes.
*/
redirect_url?: string;
/**
* Object containing token information for the specified payment instrument
*/
payment_instrument?: {
/**
* Token value
*/
token?: string;
};
};
/**
* 3DS Response
*/
export type CheckoutAccepted = {
/**
* Required action processing 3D Secure payments.
*/
next_step?: {
/**
* Where the end user is redirected.
*/
url?: string;
/**
* Method used to complete the redirect.
*/
method?: string;
/**
* Refers to a url where the end user is redirected once the payment processing completes.
*/
redirect_url?: string;
/**
* Indicates allowed mechanisms for redirecting an end user. If both values are provided to ensure a redirect takes place in either.
*/
mechanism?: ("iframe" | "browser")[];
/**
* Contains parameters essential for form redirection. Number of object keys and their content can vary.
*/
payload?: {
PaReq?: Record<string, unknown>;
MD?: Record<string, unknown>;
TermUrl?: Record<string, unknown>;
};
};
};
export type ErrorExtended = Error & {
/**
* Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, `card.name` refers to the `name` parameter embedded in the `card` object.
*/
param?: string;
};
/**
* Error message for forbidden requests.
*/
export type ErrorForbidden = {
/**
* Short description of the error.
*/
error_message?: string;
/**
* Platform code for the error.
*/
error_code?: string;
/**
* HTTP status code for the error.
*/
status_code?: string;
};
/**
* Error message structure.
*/
export type DetailsError = {
/**
* Short title of the error.
*/
title?: string;
/**
* Details of the error.
*/
details?: string;
/**
* The status code.
*/
status?: number;
failed_constraints?: {
message?: string;
reference?: string;
}[];
};
export type GetPaymentMethodsQueryParams = {
amount?: number;
currency?: string;
};
export type GetPaymentMethodsResponse = {
available_payment_methods?: {
/**
* The ID of the payment method.
*/
id: string;
}[];
};
export type ListCheckoutsQueryParams = {
checkout_reference?: string;
};
export type ListCheckoutsResponse = CheckoutSuccess[];
export type DeactivateCheckoutResponse = {
/**
* Unique ID of the payment checkout specified by the client application when creating the checkout resource.
*/
checkout_reference?: string;
/**
* Unique ID of the checkout resource.
*/
id?: string;
/**
* Amount of the payment.
*/
amount?: number;
currency?: Currency;
/**
* Unique identifying code of the merchant profile.
*/
merchant_code?: string;
/**
* Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
*/
description?: string;
/**
* Purpose of the checkout creation initially
*/
purpose?: "SETUP_RECURRING_PAYMENT" | "CHECKOUT";
/**
* Current status of the checkout.
*/
status?: "EXPIRED";
/**
* Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.
*/
date?: string;
/**
* Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
*/
valid_until?: string | null;
/**
* Merchant name
*/
merchant_name?: string;
/**
* The merchant's country
*/
merchant_country?: string;
/**
* List of transactions related to the payment.
*/
transactions?: (TransactionMixinBase & TransactionMixinCheckout)[];
};
export declare class Checkouts extends Core.APIResource {
/**
* Get available payment methods
*/
listAvailablePaymentMethods(merchantCode: string, query?: GetPaymentMethodsQueryParams, params?: Core.FetchParams): Core.APIPromise<GetPaymentMethodsResponse>;
/**
* List checkouts
*/
list(query?: ListCheckoutsQueryParams, params?: Core.FetchParams): Core.APIPromise<CheckoutSuccess[]>;
/**
* Create a checkout
*/
create(body: CheckoutCreateRequest, params?: Core.FetchParams): Core.APIPromise<Checkout>;
/**
* Retrieve a checkout
*/
get(id: string, params?: Core.FetchParams): Core.APIPromise<CheckoutSuccess>;
/**
* Process a checkout
*/
process(id: string, body: CheckoutProcessMixin, params?: Core.FetchParams): Core.APIPromise<CheckoutSuccess | CheckoutAccepted>;
/**
* Deactivate a checkout
*/
deactivate(id: string, params?: Core.FetchParams): Core.APIPromise<DeactivateCheckoutResponse>;
}
export declare namespace Checkouts {
export type { Address, Card, Checkout, CheckoutAccepted, CheckoutCreateRequest, CheckoutProcessMixin, CheckoutSuccess, Currency, DetailsError, ErrorExtended, ErrorForbidden, GetPaymentMethodsQueryParams, ListCheckoutsQueryParams, MandatePayload, MandateResponse, PersonalDetails, TransactionMixinBase, TransactionMixinCheckout, };
}
//# sourceMappingURL=index.d.ts.map