Payment Method Types

CreatePaymentResult

This object is the return value of the CreatePaymentFn.

Signature

interface CreatePaymentResult {
  amount: number;
  state: Exclude<PaymentState, 'Error'>;
  transactionId?: string;
  errorMessage?: string;
  metadata?: PaymentMetadata;
}

Members

amount

property
type:
number
The amount (as an integer - i.e. $10 = 1000) that this payment is for. Typically this should equal the Order total, unless multiple payment methods are being used for the order.

state

property
type:
Exclude<PaymentState, 'Error'>

The PaymentState of the resulting Payment.

In a single-step payment flow, this should be set to 'Settled'. In a two-step flow, this should be set to 'Authorized'.

If using a CustomOrderProcess, may be something else entirely according to your business logic.

transactionId

property
type:
string
The unique payment reference code typically assigned by the payment provider.

errorMessage

property
type:
string
If the payment is declined or fails for ome other reason, pass the relevant error message here, and it gets returned with the ErrorResponse of the addPaymentToOrder mutation.

metadata

property
type:
PaymentMetadata

This field can be used to store other relevant data which is often provided by the payment provider, such as security data related to the payment method or data used in troubleshooting or debugging.

Any data stored in the optional public property will be available via the Shop API. This is useful for certain checkout flows such as external gateways, where the payment provider returns a unique url which must then be passed to the storefront app.

CreatePaymentErrorResult

This object is the return value of the CreatePaymentFn when there has been an error.

Signature

interface CreatePaymentErrorResult {
  amount: number;
  state: 'Error';
  transactionId?: string;
  errorMessage: string;
  metadata?: PaymentMetadata;
}

Members

amount

property
type:
number

state

property
type:
'Error'

transactionId

property
type:
string

errorMessage

property
type:
string

metadata

property
type:
PaymentMetadata

CreateRefundResult

This object is the return value of the CreateRefundFn.

Signature

interface CreateRefundResult {
  state: RefundState;
  transactionId?: string;
  metadata?: PaymentMetadata;
}

Members

state

property
type:
RefundState

transactionId

property
type:
string

metadata

property
type:
PaymentMetadata

SettlePaymentResult

This object is the return value of the SettlePaymentFn when the Payment has been successfully settled.

Signature

interface SettlePaymentResult {
  success: true;
  metadata?: PaymentMetadata;
}

Members

success

property
type:
true

metadata

property
type:
PaymentMetadata

SettlePaymentErrorResult

This object is the return value of the SettlePaymentFn when the Payment could not be settled.

Signature

interface SettlePaymentErrorResult {
  success: false;
  state?: Exclude<PaymentState, 'Settled'>;
  errorMessage?: string;
  metadata?: PaymentMetadata;
}

Members

success

property
type:
false

state

property
type:
Exclude<PaymentState, 'Settled'>
The state to transition this Payment to upon unsuccessful settlement. Defaults to Error. Note that if using a different state, it must be legal to transition to that state from the Authorized state according to the PaymentState config (which can be customized using the CustomPaymentProcess).

errorMessage

property
type:
string
The message that will be returned when attempting to settle the payment, and will also be persisted as Payment.errorMessage.

metadata

property
type:
PaymentMetadata

CreatePaymentFn

This function contains the logic for creating a payment. See PaymentMethodHandler for an example.

Returns a CreatePaymentResult.

Signature

type CreatePaymentFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    order: Order,
    amount: number,
    args: ConfigArgValues<T>,
    metadata: PaymentMetadata,
) => CreatePaymentResult | CreatePaymentErrorResult | Promise<CreatePaymentResult | CreatePaymentErrorResult>

SettlePaymentFn

This function contains the logic for settling a payment. See PaymentMethodHandler for an example.

Signature

type SettlePaymentFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    order: Order,
    payment: Payment,
    args: ConfigArgValues<T>,
) => SettlePaymentResult | SettlePaymentErrorResult | Promise<SettlePaymentResult | SettlePaymentErrorResult>

CreateRefundFn

This function contains the logic for creating a refund. See PaymentMethodHandler for an example.

Signature

type CreateRefundFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    input: RefundOrderInput,
    amount: number,
    order: Order,
    payment: Payment,
    args: ConfigArgValues<T>,
) => CreateRefundResult | Promise<CreateRefundResult>