receipts.go

// Code generated by `go-sdk-gen`. DO NOT EDIT.

package sumup

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"strconv"
	"time"

	"github.com/sumup/sumup-go/client"
)

// Receipt details for a transaction.
type Receipt struct {
	// Acquirer-specific metadata related to the card authorization.
	AcquirerData *ReceiptAcquirerData `json:"acquirer_data,omitempty"`
	// EMV-specific metadata returned for card-present payments.
	EmvData *json.RawMessage `json:"emv_data,omitempty"`
	// Merchant details displayed on a transaction receipt.
	MerchantData *ReceiptMerchantData `json:"merchant_data,omitempty"`
	// Transaction details displayed on a receipt.
	TransactionData *ReceiptTransaction `json:"transaction_data,omitempty"`
}

// Acquirer-specific metadata related to the card authorization.
type ReceiptAcquirerData struct {
	// Authorization code returned by the acquirer.
	AuthorizationCode *string `json:"authorization_code,omitempty"`
	// Local timestamp of the card authorization.
	LocalTime *string `json:"local_time,omitempty"`
	// Return code reported by the acquirer.
	ReturnCode *string `json:"return_code,omitempty"`
	// Identifier of the terminal used for the authorization.
	Tid *string `json:"tid,omitempty"`
}

// Payment card details displayed on the receipt.
type ReceiptCard struct {
	// Last four digits of the payment card number.
	Last4Digits *string `json:"last_4_digits,omitempty"`
	// Issuing card network of the payment card.
	Type *string `json:"type,omitempty"`
}

// Transaction event details as rendered on the receipt.
type ReceiptEvent struct {
	// Amount associated with the transaction event, in major units.
	// Format: double
	Amount *json.Number `json:"amount,omitempty"`
	// Unique identifier of the transaction event.
	// Format: int64
	ID *TransactionEventID `json:"id,omitempty"`
	// Receipt number associated with the event.
	ReceiptNo *string `json:"receipt_no,omitempty"`
	// Status of the transaction event.
	//
	// Not every value is used for every event type.
	//
	// - `PENDING`: The event has been created but is not final yet. Used for events that are still being processed and
	// whose final outcome is not known yet.
	// - `SCHEDULED`: The event is planned for a future payout cycle but has not been executed yet. This applies to
	// payout events before money is actually sent out.
	// - `RECONCILED`: The underlying payment has been matched with settlement data and is ready to continue through
	// payout processing, but the funds have not been paid out yet. This applies to payout events.
	// - `PAID_OUT`: The payout event has been completed and the funds were included in a merchant payout.
	// - `REFUNDED`: A refund event has been accepted and recorded in the refund flow. This is the status returned for
	// refund events once the transaction amount is being or has been returned to the payer.
	// - `SUCCESSFUL`: The event completed successfully. Use this as the generic terminal success status for event
	// types that do not expose a more specific business outcome such as `PAID_OUT` or `REFUNDED`.
	// - `FAILED`: The event could not be completed. Typical examples are a payout that could not be executed or
	// an event that was rejected during processing.
	Status *TransactionEventStatus `json:"status,omitempty"`
	// The timestamp of when the transaction event occurred.
	Timestamp *time.Time `json:"timestamp,omitempty"`
	// Unique identifier of the transaction.
	TransactionID *TransactionID `json:"transaction_id,omitempty"`
	// Type of the transaction event.
	Type *TransactionEventType `json:"type,omitempty"`
}

// Merchant details displayed on a transaction receipt.
type ReceiptMerchantData struct {
	// Locale used for rendering localized receipt fields.
	Locale *string `json:"locale,omitempty"`
	// Merchant profile details displayed on the receipt.
	MerchantProfile *ReceiptMerchantDataMerchantProfile `json:"merchant_profile,omitempty"`
}

// Merchant profile details displayed on the receipt.
type ReceiptMerchantDataMerchantProfile struct {
	// Business address of the merchant.
	Address *ReceiptMerchantDataMerchantProfileAddress `json:"address,omitempty"`
	// Business name of the merchant.
	BusinessName *string `json:"business_name,omitempty"`
	// Company registration number of the merchant.
	CompanyRegistrationNumber *string `json:"company_registration_number,omitempty"`
	// Email address of the merchant.
	Email *string `json:"email,omitempty"`
	// Language configured for the merchant profile.
	Language *string `json:"language,omitempty"`
	// Short unique identifier for the merchant.
	MerchantCode *string `json:"merchant_code,omitempty"`
	// VAT identification number of the merchant.
	VATID *string `json:"vat_id,omitempty"`
	// Website of the merchant.
	Website *string `json:"website,omitempty"`
}

// Business address of the merchant.
type ReceiptMerchantDataMerchantProfileAddress struct {
	// First line of the merchant address.
	AddressLine1 *string `json:"address_line_1,omitempty"`
	// Second line of the merchant address.
	AddressLine2 *string `json:"address_line_2,omitempty"`
	// City of the merchant address.
	City *string `json:"city,omitempty"`
	// Two-letter ISO 3166-1 alpha-2 country code of the merchant address.
	Country *string `json:"country,omitempty"`
	// English name of the country in the merchant address.
	CountryEnName *string `json:"country_en_name,omitempty"`
	// Localized name of the country in the merchant address.
	CountryNativeName *string `json:"country_native_name,omitempty"`
	// Landline phone number of the merchant.
	Landline *string `json:"landline,omitempty"`
	// Postal code of the merchant address.
	PostCode *string `json:"post_code,omitempty"`
	// Region or state of the merchant address.
	RegionName *string `json:"region_name,omitempty"`
}

// Card reader details displayed on the receipt.
type ReceiptReader struct {
	// Unique identifier of the physical card reader.
	Code *string `json:"code,omitempty"`
	// Model of the physical card reader.
	Type *string `json:"type,omitempty"`
}

// Transaction details displayed on a receipt.
type ReceiptTransaction struct {
	// Total transaction amount, in major units.
	Amount *string `json:"amount,omitempty"`
	// Payment card details displayed on the receipt.
	Card *ReceiptCard `json:"card,omitempty"`
	// Card reader details displayed on the receipt.
	CardReader *ReceiptReader `json:"card_reader,omitempty"`
	// Three-letter ISO 4217 currency code of the transaction.
	Currency *string `json:"currency,omitempty"`
	// Entry mode of the payment details.
	EntryMode *string `json:"entry_mode,omitempty"`
	// Transaction events displayed on the receipt.
	Events []ReceiptEvent `json:"events,omitempty"`
	// Number of installments.
	InstallmentsCount *int `json:"installments_count,omitempty"`
	// Short unique identifier for the merchant.
	MerchantCode *string `json:"merchant_code,omitempty"`
	// Payment type used for the transaction.
	PaymentType *string `json:"payment_type,omitempty"`
	// Whether the transaction was processed as credit or debit.
	ProcessAs *ReceiptTransactionProcessA `json:"process_as,omitempty"`
	// Products associated with the transaction.
	Products []ReceiptTransactionProduct `json:"products,omitempty"`
	// Receipt number associated with the transaction.
	ReceiptNo *string `json:"receipt_no,omitempty"`
	// Current processing status of the transaction.
	Status *string `json:"status,omitempty"`
	// The timestamp of when the transaction was created.
	Timestamp *time.Time `json:"timestamp,omitempty"`
	// Tip included in the transaction amount, in major units.
	TipAmount *string `json:"tip_amount,omitempty"`
	// Transaction code returned after processing the transaction.
	TransactionCode *string `json:"transaction_code,omitempty"`
	// Unique identifier of the transaction.
	TransactionID *TransactionID `json:"transaction_id,omitempty"`
	// VAT included in the transaction amount, in major units.
	VATAmount *string `json:"vat_amount,omitempty"`
	// VAT breakdown for the transaction.
	VATRates []ReceiptTransactionVATRate `json:"vat_rates,omitempty"`
	// Cardholder verification method.
	VerificationMethod *string `json:"verification_method,omitempty"`
}

// Whether the transaction was processed as credit or debit.
type ReceiptTransactionProcessA string

const (
	ReceiptTransactionProcessACredit ReceiptTransactionProcessA = "CREDIT"
	ReceiptTransactionProcessADebit  ReceiptTransactionProcessA = "DEBIT"
)

// ReceiptTransactionProduct is a schema definition.
type ReceiptTransactionProduct struct {
	// Product description.
	Description *string `json:"description,omitempty"`
	// Product name.
	Name *string `json:"name,omitempty"`
	// Product price.
	// Format: double
	Price *json.Number `json:"price,omitempty"`
	// Product price including VAT.
	// Format: double
	PriceWithVAT *json.Number `json:"price_with_vat,omitempty"`
	// Product quantity.
	// Format: int64
	Quantity *int64 `json:"quantity,omitempty"`
	// VAT amount for a single product.
	// Format: double
	SingleVATAmount *json.Number `json:"single_vat_amount,omitempty"`
	// Total price calculated as the product price multiplied by the quantity.
	// Format: double
	TotalPrice *json.Number `json:"total_price,omitempty"`
	// Total product price including VAT.
	// Format: double
	TotalWithVAT *json.Number `json:"total_with_vat,omitempty"`
	// Total VAT amount for the product quantity.
	// Format: double
	VATAmount *json.Number `json:"vat_amount,omitempty"`
	// VAT rate.
	// Format: double
	VATRate *json.Number `json:"vat_rate,omitempty"`
}

// ReceiptTransactionVATRate is a schema definition.
type ReceiptTransactionVATRate struct {
	// Gross amount to which the VAT rate applies.
	Gross *float32 `json:"gross,omitempty"`
	// Net amount to which the VAT rate applies.
	Net *float32 `json:"net,omitempty"`
	// VAT rate applied to the transaction amount.
	Rate *float32 `json:"rate,omitempty"`
	// VAT amount included in the gross amount.
	VAT *float32 `json:"vat,omitempty"`
}

// ReceiptsGetParams are query parameters for GetReceipt.
type ReceiptsGetParams struct {
	// Short unique identifier for the merchant.
	Mid string
	// Unique identifier of the transaction event to include on the receipt.
	TxEventID *int
}

// QueryValues converts [ReceiptsGetParams] into [url.Values].
func (p *ReceiptsGetParams) QueryValues() url.Values {
	q := make(url.Values)

	q.Set("mid", p.Mid)

	if p.TxEventID != nil {
		q.Set("tx_event_id", strconv.Itoa(*p.TxEventID))
	}

	return q
}

// ReceiptsClient provides access to the Receipts API.
//
// The Receipts model obtains receipt-like details for specific transactions.
type ReceiptsClient struct {
	c *client.Client
}

func NewReceiptsClient(c *client.Client) *ReceiptsClient {
	return &ReceiptsClient{c: c}
}

// Retrieves receipt specific data for a transaction.
func (c *ReceiptsClient) Get(ctx context.Context, transactionID string, params ReceiptsGetParams) (*Receipt, error) {
	path := fmt.Sprintf("/v1.1/receipts/%v", transactionID)

	resp, err := c.c.Call(ctx, http.MethodGet, path, client.WithQueryValues(params.QueryValues()))
	if err != nil {
		return nil, fmt.Errorf("call %s %s: %w", http.MethodGet, path, err)
	}
	defer func() {
		_ = resp.Body.Close()
	}()

	switch resp.StatusCode {
	case http.StatusOK:
		var v Receipt
		if err := json.NewDecoder(resp.Body).Decode(&v); err != nil {
			return nil, fmt.Errorf("decode response: %s", err.Error())
		}

		return &v, nil
	case http.StatusBadRequest:
		var apiErr Error
		if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil {
			return nil, fmt.Errorf("read error response: %s", err.Error())
		}

		return nil, &apiErr
	case http.StatusUnauthorized:
		var apiErr Problem
		if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil {
			return nil, fmt.Errorf("read error response: %s", err.Error())
		}

		return nil, &apiErr
	case http.StatusNotFound:
		var apiErr Error
		if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil {
			return nil, fmt.Errorf("read error response: %s", err.Error())
		}

		return nil, &apiErr
	default:
		return nil, fmt.Errorf("unexpected response %d: %s", resp.StatusCode, http.StatusText(resp.StatusCode))
	}
}