@sumup/sdk
Version:
The official TypeScript SDK for the SumUp API
492 lines • 16 kB
TypeScript
import * as Core from "../../core";
/**
* Profile's personal address information.
*/
export type AddressLegacy = {
/**
* 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;
};
/**
* Issuing card network of the payment card used for the transaction.
*/
export type CardType = "AMEX" | "CUP" | "DINERS" | "DISCOVER" | "ELO" | "ELV" | "HIPERCARD" | "JCB" | "MAESTRO" | "MASTERCARD" | "VISA" | "VISA_ELECTRON" | "VISA_VPAY" | "UNKNOWN";
/**
* __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;
type: CardType;
};
/**
* 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;
};
/**
* Payment type used for the transaction.
*/
export type PaymentType = "CASH" | "POS" | "ECOM" | "RECURRING" | "BITCOIN" | "BALANCE" | "MOTO" | "BOLETO" | "DIRECT_DEBIT" | "APM" | "UNKNOWN";
/**
* Details of the transaction.
*/
export type TransactionBase = {
/**
* 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?: PaymentType;
/**
* Current number of the installment for deferred payments.
*/
installments_count?: number;
};
/**
* Entry mode of the payment details.
*/
export type EntryMode = "BOLETO" | "SOFORT" | "IDEAL" | "BANCONTACT" | "EPS" | "MYBANK" | "SATISPAY" | "BLIK" | "P24" | "GIROPAY" | "PIX" | "QR_CODE_PIX" | "APPLE_PAY" | "GOOGLE_PAY" | "PAYPAL" | "NONE" | "CHIP" | "MANUAL_ENTRY" | "CUSTOMER_ENTRY" | "MAGSTRIPE_FALLBACK" | "MAGSTRIPE" | "DIRECT_DEBIT" | "CONTACTLESS" | "MOTO" | "CONTACTLESS_MAGSTRIPE" | "N/A";
export type TransactionCheckoutInfo = {
/**
* 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?: EntryMode;
/**
* 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" | "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;
/**
* 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?: (TransactionBase & TransactionCheckoutInfo)[];
};
/**
* 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?: (TransactionBase & TransactionCheckoutInfo)[];
/**
* __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?: AddressLegacy;
};
/**
* Details of the payment instrument for processing the checkout.
*/
export type ProcessCheckout = {
/**
* 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 declare class Checkouts extends Core.APIResource {
/**
* Get payment methods available for the given merchant to use with a checkout.
*/
listAvailablePaymentMethods(merchantCode: string, query?: GetPaymentMethodsQueryParams, params?: Core.FetchParams): Core.APIPromise<GetPaymentMethodsResponse>;
/**
* Lists created checkout resources according to the applied `checkout_reference`.
*/
list(query?: ListCheckoutsQueryParams, params?: Core.FetchParams): Core.APIPromise<CheckoutSuccess[]>;
/**
* Creates a new payment checkout resource. The unique `checkout_reference` created by this request, is used for further manipulation of the checkout.
*
* For 3DS checkouts, add the `redirect_url` parameter to your request body schema.
*
* Follow by processing a checkout to charge the provided payment instrument.
*
*/
create(body: CheckoutCreateRequest, params?: Core.FetchParams): Core.APIPromise<Checkout>;
/**
* Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively.
*/
get(id: string, params?: Core.FetchParams): Core.APIPromise<CheckoutSuccess>;
/**
* Processing a checkout will attempt to charge the provided payment instrument for the amount of the specified checkout resource initiated in the `Create a checkout` endpoint.
*
* Follow this request with `Retrieve a checkout` to confirm its status.
*
*/
process(id: string, body: ProcessCheckout, params?: Core.FetchParams): Core.APIPromise<CheckoutSuccess | CheckoutAccepted>;
/**
* Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated.
*/
deactivate(id: string, params?: Core.FetchParams): Core.APIPromise<Checkout>;
}
export declare namespace Checkouts {
export type { AddressLegacy, Card, CardType, Checkout, CheckoutAccepted, CheckoutCreateRequest, CheckoutSuccess, Currency, DetailsError, EntryMode, ErrorExtended, ErrorForbidden, GetPaymentMethodsQueryParams, ListCheckoutsQueryParams, MandatePayload, MandateResponse, PaymentType, PersonalDetails, ProcessCheckout, TransactionBase, TransactionCheckoutInfo, };
}
//# sourceMappingURL=index.d.ts.map