Payment Method Types
CreatePaymentResult
This object is the return value of the CreatePaymentFn.
interface CreatePaymentResult {
amount: number;
state: Exclude<PaymentState, 'Error'>;
transactionId?: string;
errorMessage?: string;
metadata?: PaymentMetadata;
}
amount
numberThe 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
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 PaymentProcess, may be something else entirely according to your business logic.
transactionId
stringThe unique payment reference code typically assigned by the payment provider.
errorMessage
stringIf 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
PaymentMetadataThis 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.
interface CreatePaymentErrorResult {
amount: number;
state: 'Error';
transactionId?: string;
errorMessage: string;
metadata?: PaymentMetadata;
}
amount
numberstate
'Error'transactionId
stringerrorMessage
stringmetadata
PaymentMetadataCreateRefundResult
This object is the return value of the CreateRefundFn.
interface CreateRefundResult {
state: RefundState;
transactionId?: string;
metadata?: PaymentMetadata;
}
SettlePaymentResult
This object is the return value of the SettlePaymentFn when the Payment has been successfully settled.
interface SettlePaymentResult {
success: true;
metadata?: PaymentMetadata;
}
SettlePaymentErrorResult
This object is the return value of the SettlePaymentFn when the Payment could not be settled.
interface SettlePaymentErrorResult {
success: false;
state?: Exclude<PaymentState, 'Settled'>;
errorMessage?: string;
metadata?: PaymentMetadata;
}
success
falsestate
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
PaymentProcess).
errorMessage
stringThe message that will be returned when attempting to settle the payment, and will
also be persisted as Payment.errorMessage.
metadata
PaymentMetadataCancelPaymentResult
This object is the return value of the CancelPaymentFn when the Payment has been successfully cancelled.
interface CancelPaymentResult {
success: true;
metadata?: PaymentMetadata;
}
CancelPaymentErrorResult
This object is the return value of the CancelPaymentFn when the Payment could not be cancelled.
interface CancelPaymentErrorResult {
success: false;
state?: Exclude<PaymentState, 'Cancelled'>;
errorMessage?: string;
metadata?: PaymentMetadata;
}
success
falsestate
Exclude<PaymentState, 'Cancelled'>The state to transition this Payment to upon unsuccessful cancellation.
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
PaymentProcess).
errorMessage
stringThe message that will be returned when attempting to cancel the payment, and will
also be persisted as Payment.errorMessage.
metadata
PaymentMetadataCreatePaymentFn
This function contains the logic for creating a payment. See PaymentMethodHandler for an example.
Returns a CreatePaymentResult.
type CreatePaymentFn<T extends ConfigArgs> = (
ctx: RequestContext,
order: Order,
amount: number,
args: ConfigArgValues<T>,
metadata: PaymentMetadata,
method: PaymentMethod,
) => CreatePaymentResult | CreatePaymentErrorResult | Promise<CreatePaymentResult | CreatePaymentErrorResult>
SettlePaymentFn
This function contains the logic for settling a payment. See PaymentMethodHandler for an example.
type SettlePaymentFn<T extends ConfigArgs> = (
ctx: RequestContext,
order: Order,
payment: Payment,
args: ConfigArgValues<T>,
method: PaymentMethod,
) => SettlePaymentResult | SettlePaymentErrorResult | Promise<SettlePaymentResult | SettlePaymentErrorResult>
CancelPaymentFn
This function contains the logic for cancelling a payment. See PaymentMethodHandler for an example.
type CancelPaymentFn<T extends ConfigArgs> = (
ctx: RequestContext,
order: Order,
payment: Payment,
args: ConfigArgValues<T>,
method: PaymentMethod,
) => CancelPaymentResult | CancelPaymentErrorResult | Promise<CancelPaymentResult | CancelPaymentErrorResult>
CreateRefundFn
This function contains the logic for creating a refund. See PaymentMethodHandler for an example.
type CreateRefundFn<T extends ConfigArgs> = (
ctx: RequestContext,
input: RefundOrderInput,
amount: number,
order: Order,
payment: Payment,
args: ConfigArgValues<T>,
method: PaymentMethod,
) => CreateRefundResult | Promise<CreateRefundResult>