mercadopago/dist/clients/payment/create/types.d.ts

Mercadopago SDK for Node.js

/**
 * Request types for the create-payment operation (`POST /v1/payments`).
 *
 * These types define the shape of the request body, payer data,
 * payment-method overrides, forwarding data, and point-of-interaction
 * details that the Payments API accepts when creating a new payment.
 *
 * @module clients/payment/create/types
 */
import type { Address, Items, Shipments } from '../../../clients/commonTypes';
import type { MercadoPagoConfig } from '../../../mercadoPagoConfig';
import type { Identification, Payer, Phone } from '../commonTypes';
import type { Options } from '../../../types';
/**
 * Internal client payload passed to the create-payment function.
 */
export declare type PaymentCreateClient = {
    /** Payment creation request body. */
    body: PaymentCreateRequest;
    /** SDK configuration including the access token. */
    config: MercadoPagoConfig;
};
/**
 * Public-facing input accepted by {@link Payment.create}.
 */
export declare type PaymentCreateData = {
    /** Payment creation request body. */
    body: PaymentCreateRequest;
    /** Per-request option overrides (timeout, idempotency key, etc.). */
    requestOptions?: Options;
};
/**
 * Request body for creating a new payment.
 *
 * At minimum, `transaction_amount`, a `payer` with an `email`, and either
 * a `payment_method_id` or a card `token` must be provided.
 */
export declare type PaymentCreateRequest = {
    /** Extra data for fraud prevention (buyer IP, items, shipment). */
    additional_info?: AdditionalInfo;
    /** Marketplace application fee collected from the seller. */
    application_fee?: number;
    /** When `true`, the payment is either instantly approved or rejected (no pending state). */
    binary_mode?: boolean;
    /** URL the buyer is redirected to after completing the payment flow. */
    callback_url?: string;
    /** Promotional campaign identifier for discounts. */
    campaign_id?: string;
    /** Set to `false` to authorize without capturing (pre-authorization). */
    capture?: boolean;
    /** Discount coupon amount to deduct from the transaction. */
    coupon_amount?: number;
    /** Discount coupon code. */
    coupon_code?: string;
    /** Expiration date after which the payment can no longer be completed (ISO 8601). */
    date_of_expiration?: string;
    /** Description shown to the buyer and on the card statement. */
    description?: string;
    /** Differential pricing configuration identifier. */
    differential_pricing_id?: number;
    /** Integrator-supplied external reference for reconciliation. */
    external_reference?: string;
    /** Number of instalments selected by the buyer. */
    installments?: number;
    /** Card issuer identifier. */
    issuer_id?: number;
    /** Arbitrary key-value metadata attached to the payment. */
    metadata?: any;
    /** Webhook URL for receiving payment status notifications. */
    notification_url?: string;
    /** Payment method identifier (e.g. `visa`, `pix`, `bolbradesco`). */
    payment_method_id?: string;
    /** Payment method overrides (authentication data, type). */
    payment_method?: PaymentMethod;
    /** Text that appears on the buyer's card statement. */
    statement_descriptor?: string;
    /** Card token generated by MercadoPago.js or the Tokenization API. */
    token?: string;
    /** Gross amount to charge in the specified currency. */
    transaction_amount?: number;
    /** 3-D Secure mode (e.g. `optional`, `not_supported`). */
    three_d_secure_mode?: string;
    /** Buyer (payer) information. */
    payer?: PayerRequest;
    /** Data forwarded to sub-merchants or card networks. */
    forward_data?: ForwardDataRequest;
    /** Channel and subscription context for recurring payments. */
    point_of_interaction?: PointOfInteractionRequest;
    /** Sponsor (marketplace owner) account identifier. */
    sponsor_id?: number;
    /** Transaction-level details (e.g. financial institution for bank transfers). */
    transaction_details?: TransactionDetailsRequest;
};
/**
 * Payer (buyer) data included in a payment creation request.
 */
export declare type PayerRequest = {
    /** Payer type (e.g. `customer`, `guest`). */
    type?: string;
    /** MercadoPago payer identifier. */
    id?: string;
    /** Payer e-mail address. */
    email?: string;
    /** Government-issued identification document. */
    identification?: Identification;
    /** Payer phone number. */
    phone?: Phone;
    /** Payer first name. */
    first_name?: string;
    /** Payer last name. */
    last_name?: string;
    /** Entity type: `individual` or `association`. */
    entity_type?: string;
    /** Payer billing address (extended with neighborhood and city). */
    address?: AddressRequest;
};
/**
 * Data forwarded to sub-merchants or card networks in gateway mode.
 */
export declare type ForwardDataRequest = {
    /** Sub-merchant details for payment facilitator flows. */
    sub_merchant?: SubMerchant;
    /** Card-network transaction data for recurring / MIT transactions. */
    network_transaction_data?: NetworkTransactionData;
};
/**
 * Card-network transaction identifier used for Merchant-Initiated Transactions (MIT).
 */
export declare type NetworkTransactionData = {
    /** Original transaction ID assigned by the card network. */
    network_transaction_id?: string;
};
/**
 * Extended address including neighborhood, city, and federal-unit fields.
 */
export declare interface AddressRequest extends Address {
    /** Neighborhood or district name. */
    neighborhood?: string;
    /** City name. */
    city?: string;
    /** State or federal-unit code. */
    federal_unit?: string;
}
/**
 * Sub-merchant identification for Payment Facilitator (PayFac) flows.
 *
 * Required by card-network regulations when the collector operates as
 * a payment facilitator on behalf of smaller merchants.
 */
export declare type SubMerchant = {
    /** Sub-merchant unique identifier. */
    sub_merchant_id?: string;
    /** Merchant Category Code (ISO 18245). */
    mcc?: string;
    /** Country where the sub-merchant operates. */
    country?: string;
    /** Street door number. */
    address_door_number?: number;
    /** Postal / ZIP code. */
    zip?: string;
    /** Tax or business document number. */
    document_number?: string;
    /** City name. */
    city?: string;
    /** Street address. */
    address_street?: string;
    /** Trade / brand name of the sub-merchant. */
    business_name?: string;
    /** ISO 3166-2 region code. */
    region_code_iso?: string;
    /** Internal region code. */
    region_code?: string;
    /** Document type (e.g. `CNPJ`, `CPF`). */
    document_type?: string;
    /** Sub-merchant phone number. */
    phone?: string;
    /** Sub-merchant website URL. */
    url?: string;
    /** Legal / registered name of the sub-merchant. */
    legal_name?: string;
};
/**
 * Point of interaction for recurring or subscription payments.
 */
export declare type PointOfInteractionRequest = {
    /** Identifier of the resource this payment is linked to. */
    linkedTo?: string;
    /** Interaction type (e.g. `SUBSCRIPTIONS`). */
    type?: string;
    /** Interaction sub-type. */
    sub_type?: string;
    /** Subscription / recurring transaction data. */
    transaction_data?: TransactionDataRequest;
};
/**
 * Transaction data for subscription and recurring payment contexts.
 */
export declare type TransactionDataRequest = {
    /** Whether this is the first charge in a subscription. */
    first_time_use?: boolean;
    /** Position of this payment within the subscription cycle. */
    subscription_sequence?: SubscriptionSequenceRequest;
    /** Subscription plan identifier. */
    subscription_id?: string;
    /** Invoice period for the current billing cycle. */
    invoice_period?: InvoicePeriodRequest;
    /** Reference to a previous payment in the same subscription. */
    payment_reference?: PaymentReferenceRequest;
    /** Billing date for this charge (ISO 8601). */
    billing_date?: string;
};
/**
 * Position of the current payment within a subscription cycle.
 */
export declare type SubscriptionSequenceRequest = {
    /** Current sequence number (1-based). */
    number?: number;
    /** Total number of payments expected in the subscription. */
    total?: number;
};
/**
 * Invoice period describing the billing cycle length.
 */
export declare type InvoicePeriodRequest = {
    /** Number of units in the billing cycle. */
    period?: number;
    /** Unit of the period (e.g. `monthly`, `daily`). */
    type?: string;
};
/**
 * Reference to a prior payment, used to link recurring charges.
 */
export declare type PaymentReferenceRequest = {
    /** Identifier of the referenced payment. */
    id?: string;
};
/**
 * Additional information attached to a payment request for fraud analysis.
 */
export declare type AdditionalInfo = {
    /** IP address of the buyer at the time of purchase. */
    ip_address?: string;
    /** Items being purchased. */
    items?: Array<Items>;
    /** Supplementary payer data. */
    payer?: Payer;
    /** Shipping details. */
    shipments?: Shipments;
};
/**
 * Payment method overrides for authentication and type selection.
 */
export declare type PaymentMethod = {
    /** Authentication and processing data for the payment method. */
    data?: PaymentMethodData;
    /** Payment method category (e.g. `credit_card`, `debit_card`). */
    type?: string;
};
/**
 * Processing data attached to a payment method override.
 */
export declare type PaymentMethodData = {
    /** External 3DS authentication results to forward to the processor. */
    authentication?: PaymentMethodDataAuthentication;
};
/**
 * 3-D Secure authentication results obtained externally and forwarded
 * to MercadoPago for gateway-mode processing.
 */
export declare type PaymentMethodDataAuthentication = {
    /** Access Control Server (ACS) transaction identifier. */
    acs_trans_id?: string;
    /** Final authentication status (e.g. `Y`, `N`, `A`). */
    authentication_status?: string;
    /** CAVV / AAV cryptogram proving the authentication. */
    cryptogram?: string;
    /** Directory Server (DS) transaction identifier. */
    ds_trans_id?: string;
    /** Electronic Commerce Indicator returned by the issuer. */
    eci?: string;
    /** 3DS Server transaction identifier. */
    three_ds_server_trans_id?: string;
    /** 3DS protocol version used (e.g. `2.1.0`, `2.2.0`). */
    three_ds_version?: string;
    /** Authentication type (e.g. `frictionless`, `challenge`). */
    type?: string;
};
/**
 * Transaction-level details for bank-transfer payment methods.
 */
export declare type TransactionDetailsRequest = {
    /** Financial institution identifier or name for bank transfers. */
    financial_institution?: string;
};